A Route, Not a Territory

Two Hundred and Twenty-Six Megabytes

One file in the Claude Code projects folder held a single session's transcript: 226 megabytes of JSON lines, the full record of one long working thread. Twelve more sat beside it, 372 megabytes together. The first draft of a session switcher opened every one of them and read it top to bottom to recover three facts — a title, a branch, and when the session was last touched. On that store it would not have finished opening.

The problem the switcher exists for is ordinary. A dozen sessions across several projects, and no memory of which one had the fix. Claude Code's own picker already lists them. What a list cannot say is which of them is worth going back to — which was left mid-thought, which is waiting on someone else, which is spent.

That second question is the real one. It is not a question about where things are. The disk already knows where things are. It is a question about when — and an animal answered it a long time before anyone needed a session list.

The Hermit’s Circuit

Hermit hummingbirds don't defend a patch of flowers. They trap-line: they fly a long, regular route between widely scattered flowers and return to each on its own schedule. Gill's 1988 study of the strategy in Ecology names the tension a trap-liner lives with: wait for undefended nectar to build up, and risk losing it to a competitor who got there first.

The capability a circuit depends on was measured in a related bird. In a 2006 study in Current Biology, Henderson, Hurly, Bateson and Healy gave wild rufous hummingbirds eight artificial flowers. Four refilled ten minutes after being emptied; four refilled after twenty. The birds came back to each flower on that flower's own interval. They were storing not only where they had fed, but when.

Which is the switcher's brief, restated by a bird. Not a map of every session. A record of when each one was last touched, and a sense of whether it has had time to refill.

Reading Only What Changed

The same brief fixed the performance. A bird does not re-inspect a flower it drained five minutes ago, and an index should not re-read a transcript that hasn't moved. The switcher keeps one record per file, keyed by size and modification time — the stat-first trick trailant's indexer already used — and passes over anything unchanged.

Transcripts only grow. So a session that gained ten lines is read from where the last read stopped, not from the top:

sed -n '41,50p;51q' session.jsonl

The trailing q is the whole trick. Without it, sed prints the range and then reads on to the end of the file anyway. On the 226-megabyte transcript that was the difference between 0.04 seconds and 0.00. In the running engine, across all 372 megabytes, the first open made 52 small reads and pulled 15.2 megabytes. The next open made four.

What the Surface Actually Says

Anthropic opened Mods — early-access plugins that hook directly into the Claude Code engine — in a public issue on the claude-code repository. The first draft guessed at the API from that announcement and got its shape wrong: a default export where the engine wants a named register, a self-mounted terminal overlay where the engine wants a pane it draws itself.

The real contract turned out to live in two places the prose never mentions. The first is the validator. claude plugin validate refused the mod twice: once because the engine interface was passed into a function imported from another file, once because a function receiving it was nested instead of declared at the top of the module. Neither rule is written down anywhere. Both exist so the validator can work out everything a mod could touch before any of it runs — and print it:

env reads:  HOME, OS, USERPROFILE
env writes: nothing

That is The Validator That Can't Lie again, pointed at a platform instead of a brief: the trustworthy statement of what is allowed is the one the system enforces, not the one it describes. The second place is measurement. The engine cuts a subprocess's output at 4 MiB — the largest capture came back at 3.99 — so a single transcript line bigger than that can never arrive whole, and a reader that waits for one stalls on that file for good.

Measurement can also be honestly wrong. A probe of every command available to a session found seventy and no /resume, so for a while a picked row could only print a command to paste. The probe had run in print mode, which hides interactive commands. In a real terminal on Claude Code 2.1.281, /resume was there, and a row from the current project now switches in place. What a Seal Actually Proves made the same point about a different live run: the check was accurate about everything it could see.

Marking Where the Work Is

The index answers when. It cannot answer whether the work was finished. That takes a mark, and where the mark gets made decides whether it gets made at all.

A tool that reconstructs the trail afterwards is called on at the moment a session has already been forgotten — which is exactly the moment remembering to run the tool is least likely. Reconstruction earns its keep on a schedule, when someone has sat down to review a fortnight. As a memory aid it arrives too late. So the switcher takes its marks from inside the session, while the work is happening:

/switcher #wip #client-x
/switcher -#client-x #blocked
/switcher Token refresh bug

Typed there, the edit folds in: a tag adds, -#tag removes, and a title changes only when one is typed, because a mark made mid-flight shouldn't quietly overwrite the one made that morning. The command is registered to run immediately, even while a turn is still streaming — which is usually when a session announces it will be worth coming back to.

What gets marked matters as much as where. Not the project — the list already filters on that for free. The state: #wip and #blocked turn a list of sessions into a queue, and that is the one thing no transcript can know about itself.

A Route, Not a Territory

The general shape is that a system which keeps the map is doing the easy half. The map already exists; it is the directory listing. The useful half is the circuit: where was this last, how long ago, and is it worth going back yet. A territorial bird defends a patch. A hermit keeps a route and a clock — and marks each flower as it leaves it, not later, when it would have to remember which ones mattered.

The 226-megabyte file is still there, still growing. The switcher reads it in small pieces now, and only the pieces that are new.

Explore the artifact

Related