A decision log Claude Code writes as it works

Claude Code and Pando, for a decision log.

A Claude Code session in the api repository settled that every service sends times as UTC ISO strings, because the weekly report had joined two time zones wrong. A week later a session in the worker repository, on your laptop, writes local times again. Claude Code’s docs say each session "begins with a fresh context window", and that what carries over is CLAUDE.md, instructions you write, and auto memory, notes Claude writes itself. "Auto memory is machine-local", and each git repository gets its own. So unless somebody copied the decision into instructions the worker session reads, that session is the new person Michael Nygard described in 2011, in the post that made architecture decision records popular: "Without understanding the rationale or consequences, this person has only two choices": "Blindly accept the decision." or "Blindly change it."

Give Claude Code a Decisions bullet in your outline, and have it write there each decision that spans repositories or machines or waits on you to accept it, the decision on the line and its context and consequences in the note, so a later session in any repository and on any machine where Pando is connected reads it back with search or changes. A decision about one repository’s code belongs in an ADR file in that repository instead, where it travels with the code.

Set it up

In a terminal: claude mcp add --transport http --scope user pando https://pando.ink/mcp
Start claude, run /mcp, select pando and choose Authenticate.

The command adds Pando with --scope user, because Claude Code’s docs say "Local scope is the default. A local-scoped server loads only in the project where you added it", and a decision log that spans repositories needs Pando in all of them. Claude Code needs a Pro, Max, Team, Enterprise or Console account.

On Pando’s consent page you choose Read and write your outline or Read your outline only, and either level starts it on your whole outline. The box beneath, ticked by default, makes a bullet under Home named after the client for it to remember in, and it may write there even if you chose read only. That bullet is the simplest home for Decisions.

An ADR, as a bullet

Nygard’s definition is short: "An architecture decision record is a short text file in a format similar to an Alexandrian pattern." and "Each record describes a set of forces and a single decision in response to those forces." adr.github.io adds: "The collection of ADRs created and maintained in a project constitute its decision log." His record has five parts, Title, Context, Decision, Status and Consequences, and each has a place on a bullet:

The line is the title, with the date in front: 2026-09-23 UTC ISO strings for times between services. Nygard’s titles are "short noun phrases", and the line is what you read when you scan the branch. Search’s date-before: and date-after: read a date written in the line.
The note holds Context, Decision and Consequences, in full sentences. Nygard is blunt about bullets: "Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments. (Bullets kill people, even PowerPoint bullets.)" Here the bullet is only the line, and the reasons are sentences in the note, and a read that carries a note carries all of it: nothing shortens one.
Status is the checkbox. Written as a todo, a decision nobody has ticked is proposed, and a ticked one is accepted, which is Nygard’s own pair: "proposed" if the stakeholders "haven’t agreed with it yet", "accepted" once they have. A decision that a later one reverses he marks "superseded" "with a reference to its replacement", and here that is one line at the end of the note, further down.
Consequences include the costs. Nygard: "All consequences should be listed here".
The link is the number. Nygard numbers his records "sequentially and monotonically", and "Numbers will not be reused." A bullet’s address stays the same when it is moved or reworded, so its link is what Supersedes and Superseded by point at. And since remember puts each new decision last under its parent, the branch still reads in the order the decisions were made.

- Decisions
  - [x] 2026-09-18 One payment provider for the shop and the app
  - [ ] 2026-09-23 UTC ISO strings for times between services
    note: Context: The api and the worker each wrote times in their
          own zone, and the weekly report joined them wrong twice.
          Decision: Every service sends and stores times as UTC ISO
          strings.
          Consequences: Each screen converts to local time where it
          shows one. Rows written before this need a one-off
          migration.

Telling Claude Code to keep it

Pando does not start Claude Code, so the habit goes into CLAUDE.md, which Claude Code’s docs describe as "instructions you write to give Claude persistent context". Put these lines in the CLAUDE.md of every repository where it should keep the log:

Decisions live in Pando, under a bullet called Decisions in your
memory. Find it with tree on your memory; the first time, make it
with remember.
- At the start, call changes with the cursor written in the bullet
  called Cursor in your memory, then write the new cursor over it
  with remember and that bullet’s id. Make Cursor the first time.
- Before changing something a decision covers, search for it with
  focus on Decisions, and read the note.
- When you decide something a session in another repository would
  otherwise work out again, remember it under Decisions as a todo:
  the date and the decision on the line; Context, Decision and
  Consequences in the note, in full sentences.
- Never rewrite or delete a decision. To reverse one, write a new one
  whose note begins with Supersedes and a link to the old one, add
  Superseded by and a link to the new one to the end of the old
  one’s note with appendNote, and tell me.
- Do not tick decisions. I tick what I accept.

The last line is a request and not a lock: any agent that may change a bullet may also tick it. What refuses it is a lock on that bullet, further down.

Reading it back

changes, at the start of a session. With no branch named, it reads Claude Code’s memory bullet and everything under it, and answers with what changed since the cursor it handed out last time, each bullet with its note. Pando’s own measurement: five changed bullets came back in 1,060 bytes where a tree read over the same branch was 962,608, and on a real week of 731 changed bullets it was only 1.1 times cheaper than a tree read in outline mode. The first call, with no cursor, reads the whole branch, so the cursor is worth keeping. A row says a decision changed, not whether it is ticked; the search below answers that.
search, before touching something a decision covers. A bare word matches any part of a word in a line or a note, ignoring case and accents, so migration finds the decision whose consequences mention it. With focus on Decisions, layout:todo is:incomplete -superseded lists what is still proposed, and layout:todo is:complete -superseded what is accepted and still stands. A minus word leaves out every decision whose line or note contains it, so keep superseded for the Superseded by line.
tree with mode full, to read the whole log at once. Its default outline mode leaves the notes out, and the notes are where the reasons are. A full read also gives the time each ticked decision was ticked.

When a new line uses mostly the same words as one already directly under Decisions, remember still writes it and names the older one as similar, so the two can be folded into one. It compares lines, not notes, and the date in front counts as words: a decision reworded on another day can slip past, and two short decisions from the same day can be named as each other’s twins.

Changing its mind the way Nygard asks

"If a decision is reversed, we will keep the old one around, but mark it as superseded. (It’s still relevant to know that it was the decision, but is no longer the decision.)" In the outline that makes a reversal a new decision, written last like any other, whose note opens with Supersedes and a link to the old one. The old one keeps its words and gets one line at the end of its note, Superseded by and a link to the new one, which update’s appendNote adds without resending the note. A link to a bullet is its text with the address https://pando.ink/app/ and its id, and inside Pando it opens the bullet in place.

Rewriting the old line would lose what Nygard wants kept. A one-bullet update, and remember with an id, both answer replaced when a whole line or note goes over one that was there, and replaced carries the words that were there, so Claude Code can put them back.

Keeping accepted decisions out of its reach

Once you accept a decision, protect that bullet against agents: choose Protect it from changes in its menu, open the menu again, choose How it is protected, and under Refuses pick Agents only. Claude Code can still read it, because a lock stops changes, not reading, and it can no longer untick, reword or delete it. It cannot add Superseded by to it either, so when it reverses one, it tells you and you add the line. Until you do, the search for accepted decisions still lists the old one.

Protect each decision, not the Decisions bullet. Putting a new bullet into a protected branch counts as changing it, so a lock on the whole branch would stop Claude Code writing the next decision too.

If the log lives somewhere else

Approved to read and write, Claude Code can keep Decisions anywhere in your outline, under the project your repositories belong to for one. Then name that bullet by its link in the CLAUDE.md lines, because with no branch named, tree and changes read only its memory bullet. Approved read only, it can write only in its memory bullet until you hold it to that project’s branch: open the branch, open Agents and API keys in Settings, tap its row under Your agents, and press Let it reach only “…”, the bullet you are in. From then on it reads and writes that bullet and everything under it, remembers there, and reaches nothing else in your outline, even if you approved it read only.

That includes the bullet it remembered in before. If Decisions and Cursor started there, move them under the project’s branch first, or the next session cannot reach its own log.

Files in the repository, or bullets in the outline

For a decision about one repository’s code, keep the ADR in that repository. Nygard’s scope is "one significant decision for a specific project", and he keeps the records "in the project repository", so they travel with the code to everyone who clones it. The tools that grew up around the idea do the same: adr-tools keeps them in doc/adr by default, and MADR in docs/decisions. If every decision you care about is about one repository’s code, that is the better home, and Pando adds nothing.

The outline is for the decisions no single repository owns: a convention across several services, a choice of provider, anything a second machine or another agent has to see. Auto memory stays with one repository on one machine, and Pando, added with --scope user, is the same outline in every repository and on every machine where you connect it.

And it is for a decision a person has to accept. Nygard raised the objection himself, that records "in version control with the code" are "less accessible for project managers, client stakeholders, and others who don’t live in version control", and answered it: GitHub renders Markdown, so "it looks just as friendly as any wiki page would." For reading, that holds. A proposal in the outline can also be ticked by the person it waits on, you or somebody you shared the branch with to edit, in Pando on a phone, and the next session finds it among the accepted ones with the search above.

Where this is not the answer

A decision about one repository’s code. The ADR file in that repository goes wherever the code goes, and the outline does not.
A log that has to be read without being asked. Pando does not start Claude Code, so a session reads Decisions only because CLAUDE.md tells it to, and a proposal waits in the outline until a session or a person looks.
A tick only a person can make. The consent page says "everything it changes is written down as an automated change", but nothing reserves the box for you: an agent that may change a bullet may tick it, so a tick means accepted only because Claude Code was asked to leave it alone, or because a lock refuses it.
A record, kept by Pando itself, of when each decision was made. A full tree read gives when a bullet last changed, when it was ticked, which here is when it was accepted, and when its line was last written, which is the day of the decision only until somebody rewords the line. So the date in the line is the one to go by.

What it costs

Nothing, for 1,000 bullets, with every feature included and no payment card. A decision is one bullet, its reasons are its note, so two decisions a week come to about 104 bullets a year.

Deeper

Connect an agent, about two minutes · The twelve tools · Which note apps an agent can reach · Who runs this