My past two articles, on smoothing the seams between sessions and seeing them all at once, were inspired by my continual effort to get a grasp on the multitude of agents I have running across multiple projects and ultimately, grappling with my own limited context window. Part of that has been encouraging the agents to document and with the pace of change the agents afford, that's a lot of documentation. That can quickly get out of hand, disorganized, and stale.

There are more than a handful of solutions out there already that attempt to address this. So many, in fact, that rather than picking one that didn't work out, I thought I'd engage Claude Opus to help me out. I'm not going to claim it beats them, because I haven't run them side by side. What I can show you is what this one measures, on a real 136-document tree, and you can decide from there whether it's the approach you want.

What came out of that is doc-librarian, a Claude Code skill that treats docs/ as what it literally is, a small library, and applies the discipline libraries have used for well over a century: a taxonomy, a controlled vocabulary, a catalog, hub-and-spoke indexes, and a records lifecycle that ends in an archive rather than a delete.

The agent-builds-on-a-stale-document failure is the one I felt first. A person skimming a docs folder can usually smell that something has gone off: the screenshot is from an old UI, the command has a flag that no longer exists. An agent reads it at face value and starts building. So "which of these documents are still true" stops being a tidiness question and becomes a correctness one, and the answer that worked for me was structural: a document is either current, or it is visibly archived, and there is no third state where it sits in a live folder looking authoritative. That rule turned out to answer the other half as well, since a folder with the dead documents visibly out of it is a smaller thing to search.

Then I pointed it at my own worst case: a 9-package TypeScript monorepo, 136 markdown documents, frontmatter on none of them, and nobody who could say which of them were still true.

This is for people whose docs/ has outgrown their memory of it, enough documents that "I'll just read them" has stopped being a plan. If yours is a dozen files you wrote this quarter, you don't have this problem yet.

TL;DR

• doc-librarian is a Claude Code skill that audits, triages, reorganizes, indexes and weeds a docs/ tree, and installs the enforcement that keeps it organized afterwards.

• Every verdict is measured, not guessed: staleness from git log, orphanhood from a repo-wide referrer count that reads source and config as well as other docs, near-duplicates from TF-IDF cosine.

• Cheap signal runs first and scores the whole tree in 11 seconds. Agents are spent reading only the pile it couldn't decide.

• It never deletes a referenced document. The lifecycle is deprecate, archive, and much later dispose, and the step that moves and rewrites does nothing until you pass --apply.

• The second half is a governance kit: a linter, an authoring-time guard that nudges any agent writing a non-conforming doc, and a commit-time gate.

• Install and driving instructions: START-HERE.md.

How a docs directory decays

Sprawl, duplication, orphans, stale shelves, and no catalog: nothing that says what each document is for, so classification lives only in whoever wrote it. You have all five or you wouldn't be reading this.

The cost is in the deciding rather than the reshuffling. To know whether a document is still true, someone has to read it and then read the code it describes, and at 136 documents I'd put that at a week I didn't have. So the tree stays as it is, and each new document is filed by vibes into whichever folder looks least wrong.

There's a second cost that only shows up once you start moving things. Documentation gets cited from live source, tests, CI config, editor and agent config, and root-level README and CLAUDE.md files. On my corpus, 56 of the 62 documents that moved had referrers outside docs/, and 30 of those were hard. An ESLint config naming a standards doc, a JSDoc comment citing a design doc, a @see on an exported function, a test asserting a filename. A docs reorganization is not a docs-only change, and finding that out halfway through a migration is a bad time to learn it.

The methodology

Library science already has answers for all five, and the skill is organized around them rather than around file operations. Documents are classified by Diátaxis, which sorts by what the reader is doing rather than by subject and is mutually exclusive and collectively exhaustive, which is what stops folders multiplying. Tags come from a curated TAGS.md and nowhere else, because inventing one at write time gives you auth, authentication and authn as three separate facets. The rest is bookkeeping that pays for itself: frontmatter on every document so the corpus is queryable, a README in every folder so nothing is reachable only by grep, and a lifecycle that ends in an archive rather than a delete, because the archive is what makes weeding safe enough to actually do.

Underneath all five is the discipline that makes the rest trustworthy: every verdict has to cite something. A document is stale because git says when it last changed. It's an orphan because a repo-wide grep found nothing pointing at it, checked against source and config rather than just other documents. It's a near-duplicate because the TF-IDF cosine cleared a threshold you set, and without the optional Python pass installed that one degrades to matching normalized titles, which the report tells you.

The measurements are not automatically right, and mine were wrong. An early version of the referrer counter only looked at links between documents, so anything cited from source code counted as an orphan, and orphanhood feeds the WEED bucket. It was routing live documents toward deletion.

What saved it was that every row prints its evidence. The agents reading the REVIEW pile kept returning verdicts that contradicted the score. This says orphaned, but it's cited from AgentSpecGenerator.ts:456 and four other places. They did that on five different documents, independently, without being told the bug existed.

The safety guarantees lean on that same counter. The rule that a referenced document is never deleted is enforced by the count that was wrong, so a miscounted document reads as unreferenced and the guard waves it through, which is why the WEED pile still goes to the reading agents and why I'd treat that guard as the second line rather than the first.

Fixing that counter and two related path-resolution bugs reclassified 42 of the 136 documents as KEEP, cutting the pile that needed an agent to read it from 96 to 56.

What a run looks like

Triage is the cheap half, and triage-docs.ts scores every document on staleness, inbound references, dead code anchors, duplicate similarity and location, and drops each into one of three buckets: KEEP, WEED, or REVIEW, where REVIEW explicitly means "the signal could not decide this one." On my corpus that split the 136 into 76 KEEP, 56 REVIEW and 4 WEED, and the 76 never get read by anything. It prints its reasoning per row, in the tool's own words: very stale (14mo), orphaned (no inbound links anywhere), dead code anchors (0% resolve), in "migration/" (iterative/likely-completed).

The deep dive is the expensive half, and it runs only on what the score didn't settle: REVIEW, plus the small WEED pile, because nothing gets discarded on a score alone. plan-review-batches.ts packs that bucket into batches of related documents, so one agent reading a folder sees the whole folder, and writes a brief per batch. Then one agent per batch reads the documents and the code around them and returns a per-document verdict with evidence. On my corpus that was 15 batches for 102 documents, and that is the number to price it by rather than the 11 seconds, which only ever covered the cheap half. That 102 is what I actually paid, because I ran the appraisal before I had fixed the referrer counter, when triage was still handing it 96 REVIEW and 6 WEED. With the counter fixed the same corpus routes 60 documents to the agents instead, which is the figure to plan against.

Here is a real one, trimmed. This is the actual output row for a document in my repo:

doc_path:  migration/branded-ids.md
verdict:   ARCHIVE      confidence: high      inbound_links: 0

One-shot generated snapshot from 2026-05-13, never regenerated since. All 339
checkboxes are still unchecked (`grep -c '^- \[x\]'` → 0) despite active,
ongoing ID-branding work in the same area since. Spot-checked line-number
anchors have drifted: `orchestration-engine.ts:178` no longer contains the
cited `runId?: string;` snippet.

Flag for the librarian: that generator script's OUTPUT_PATH still points at
`docs/migration/branded-ids.md` — if anyone re-runs it, the file reappears at
this path, undoing an archive-move unless the script is also updated.

That last paragraph is the reason the deep dive exists. No amount of scoring finds a script that will silently recreate a document you just archived. Somebody reading the code around it does, and that is the only thing that found it.

The verdicts roll up into a migration map, and the map is what you sign off on, rather than the migration itself. Here is how mine opens:

Proposed by `doc-librarian` Procedure B. **Nothing has been moved.** This is the
sign-off artifact: approve it, or amend it, before the first `git mv`.

## Shape

| | count |
|---|---:|
| documents today | 136 |
| stays put — `docs/TAGS.md`, the vocabulary | 1 |
| → `archive/` | 73 |
| → `tutorials/` | 1 |
| → `how-to/` | 13 |
| → `reference/` | 16 |
| → `explanation/` | 26 |
| → `decisions/` | 1 |
| → `project/` | 5 |
| frontmatter to author (every surviving doc has none) | 62 |
| moving docs with live non-docs referrers to rewrite | 22 |

## Needs your call — 5 items

Those five are the things it would not decide for me, among them two duplicate pairs where one copy of each is regenerated by a skill, and a document whose generator hardcodes the old path in four places. The per-document tables come after all of that, current path to target path with the live referrers each move would break. The skill is explicit that you don't map and move at the same time. Read the map next to the verdicts rather than on its own, though: the map is destinations and counts, and the reasoning that caught my orphan bug lives in the verdict report beside it.

What it writes, and how to undo it

Worth having as a closed list before you point it at anything, because it is otherwise spread across three phases.

Installing the skill touches ~/.claude/skills/ and nothing else, so no repository and no settings.json.

/doc-librarian setup writes six things into the repo you run it in, all tracked: docs/scripts/lint-docs.ts, .claude/hooks/docs_structure_guard.py, a starter docs/TAGS.md if you don't already have one, a hook entry in .claude/settings.json, npm scripts in package.json, and a .doc-librarian/ line in .gitignore. The settings.json entry is the one your teammates inherit.

The migration moves documents with git mv, so every move lands as a rename with its history intact, and rewrites links inside docs/. It does nothing at all until you pass --apply.

Then run it on a branch and git diff each batch before you commit it. That is not me being careful for its own sake: it's how I caught the frozen-capture corruption in my own migration, and the tool never would have.

Adopting it: the initial cleanup

Install is a clone, a dry run, and an installer:

git clone https://github.com/agentience/agentience-skills.git
cd agentience-skills/skills/doc-librarian
./install.sh --dry-run     # prints every path it would touch
./install.sh

It symlinks into ~/.claude/skills/, writes nothing to settings.json, and changes no repository. Then start a new session — a running one keeps the skill text it loaded at startup.

From inside the repo you want organized, /doc-librarian setup installs the governance kit. The recommended order for a neglected tree is then: bootstrap a tag vocabulary from the corpus's own language, weed, audit what survived, finalize governance, reorganize, index. That is G → E → A → F → B → D in the skill's own lettering. It reads one docs/ tree, so on a monorepo you point it at the one you mean rather than at nine.

The order is not arbitrary, and weeding before reorganizing is the part I'd insist on: reshuffling documents you're about to discard is wasted work, and a clean new structure lends false authority to dead content. Audit after weeding too, so you're measuring the collection you're actually keeping.

Two things to do before the first git mv, both of which I'd have skipped if the skill hadn't insisted:

The first is the broken-link baseline. Run the linter before you touch anything and write the number down. Afterwards, an absolute count of broken links tells you nothing — a corpus that was already broken will still be broken, and without the baseline you cannot separate breakage you caused from breakage you inherited. Mine was 25 before and 13 after, every remaining one a strict subset of the original 25. The honest claim is "no new broken links," and you can only make it if you measured first. As a side effect the migration repaired 12 links that were already broken.

The second is the blast radius. For every document the map moves, git grep -l "old/path.md" -- ':!docs', and classify each referrer as soft (only other docs) or hard (source, tests, config, root files), and report the split before you start. That split, 56 of 62 with 30 of them hard, is what told me the migration had to pass the test suite and not just the link checker.

Then migrate in batches, verify each, commit each, and never start a batch while the previous one has left new breakage. apply-actions.ts does the mechanical work and is dry-run by default; it refuses to delete a document with inbound links even when you ask it to.

One rule I'd put on a sticker: frozen artifacts are not documents. Test fixtures, captured model outputs, recorded HTTP sessions. These live under docs/ in a lot of repos, and a link rewriter will happily rewrite them. Rewriting a captured output changes the thing it recorded. In my migration an early pass silently edited 22 frozen experiment captures, one set of which existed precisely to measure whether a model cites file paths that exist. It was caught by a git diff against those directories, not by anything in the tool, which is why it's now rule seven of the skill's safety rules. It stayed a rule rather than a guard: nothing in the tool excludes them for you.

Adopting it: keeping it clean

A one-shot cleanup has nothing holding it in place. The repo that produced those 136 documents is still producing them at the same rate, so the half I'd expect to matter more over time is the part that runs afterwards, and it's what /doc-librarian setup installs:

• lint-docs.ts, copied into your repo as the single source of truth for every check: links, tags against the controlled vocabulary, frontmatter schema, bucket/type agreement.

• A PostToolUse guard hook, registered in that repo's .claude/settings.json, so it fires for everyone who works in the repo, not just you. When any agent writes a document that doesn't conform, the hook exits non-zero and hands the agent back the fix list: classify the Diátaxis type, pick the one correct folder, add frontmatter, name it kebab-case, wire it into the index. The write has already happened at that point; what you get is the agent correcting it in the same turn rather than someone auditing it months later. It fails open on any error of its own, so a broken hook never blocks authoring.

• A commit-time gate: lint-docs.ts --staged in your pre-commit hook, blocking, plus --staleness as a non-blocking review report.

• .doc-librarian/ gitignored, with the reports written there rather than into docs/. A report written into the tree becomes a document, and the next scan appraises the skill's own output alongside your corpus. That one isn't finished — plan-review-batches.ts still defaults its briefs into the tree it just read, so pass it an out-dir.

The guard is Claude Code-specific; the linter and the pre-commit gate are not, so on a client without hooks you get the same rules one step later.

What it won't do

Named up front, because each of these bit mine:

• Reference counting is liveness-blind. A citation from specs/completed/ weighs exactly as much as one from live source, so a genuinely dead document can hold itself out of the WEED bucket on dead referrers. It errs toward human review rather than deletion, which is the safe direction — but a high inbound count is not proof of relevance.

• Nothing checks anchors. guide.md#configuration survives a move as a link to the right file and the wrong place in it. The linter sees paths, not fragments; the skill tells you to grep them by hand.

• It rewrites links inside docs/ only. Referrers in source, tests and config are counted but not rewritten, so you get the list and the edits are yours to make.

• It can write to files under docs/ that aren't documents. Anything in the docs tree that is a captured artifact rather than prose is fair game for the link rewriter, and excluding it is a rule the skill states rather than a check the code runs, which is how 22 of mine got rewritten.

• It cannot tell you what is true. It measures stale, orphaned and duplicated. Whether the content is still correct is a reading task — that's what the deep dive is for, and even that returns verdicts for a human to accept.

The first three are open on purpose: design questions I'd have had to guess at, and a skill that quietly did the wrong thing in those places would be worse than one that names them. The fourth is not on purpose; it is unfinished, and it is the one I'd check by hand.

Try it

The fastest path is to hand an agent the bootstrap document and let it install and drive the skill itself:

Read https://raw.githubusercontent.com/agentience/agentience-skills/main/skills/doc-librarian/START-HERE.md and follow it.

It's written for an agent rather than a person, it's self-contained, and it ends with the rules that keep an enthusiastic agent from destroying a corpus quickly and plausibly. Everything else, the eight procedures and the scripts and the templates, is in the repo.

Start with audit. It only counts things, so it's the one step I'd run without thinking twice about it.

A friend (thanks Pat Santora!) pointed me at Herdr and said it might get all of that into one place.

So I moved every session out of VS Code's integrated terminal into Herdr, running standalone in iTerm2, one workspace per repo. The editor is now purely for reading and editing code. What I get back is a sidebar that reports what every agent in every project is doing, without me going to look.

This is for people running more agents than they can hold in their head — several repos, several sessions in each. If you run one session in one repo, the terminal you already have is fine.

TL;DR

• With 12 to 30 sessions across 3 to 5 windows, I was the only thing that knew when one of them needed me, and I only knew by going and looking.

• Herdr is a terminal multiplexer — tmux's category — that knows which of its panes are running agents. One workspace per repo, and the sidebar reports each agent as working, idle, done, blocked or unknown, across every project at once. There are audio cues too.

• The lag from a session needing me to me knowing about it went from about 20 minutes — my next pass through the windows — to under a minute. Nothing became automatic: what I do when I get there is unchanged, and I still start every one of those actions myself. Only the noticing moved.

• I didn't wait for the migration to break things. I listed the two workflows I refused to lose and solved both before switching: my tmuxp layouts, and Ctrl+Shift+W to jump between projects without touching the mouse.

• One already existed as a plugin and needed two upstream PRs to fit; the other I wrote. Neither took a day.

• Herdr: herdr.dev. The project-jump plugin: github.com/agentience/herdr-plugin-ide-jump

Here is the artifact, from this machine, right now — every pane in every project that has an agent in it:

w8  client-a         w8:pP  claude  working  spreader-label-normalise
w8  client-a         w8:pD  claude  idle     Starting without starting
w8  client-a         w8:pH  claude  idle     Claude Code
w8  client-a         w8:pQ  claude  idle     Claude Code
wA  tribal-markdown  wA:p2  claude  idle     Startup baseline exploration
wH  client-b         wH:p7  claude  idle     Claude Code
wR  ide-jump         wR:p4  claude  idle     Plugin Windows compatibility verification
wS  herdr-spreader   wS:p1  claude  idle     Claude Code

Twelve workspaces on this machine, one per repo. Eight panes had an agent in them at the moment I captured that. Client project names are redacted, nothing else is. In the terminal this is a sidebar rather than a list I ask for, and the fourth column is the whole point: one working, seven waiting on me.

The noticing was the problem

An agent session asks for you in several different ways. It finishes and sits idle. It stops on a permission prompt and waits. It reaches a decision it can't make — which of two approaches, whether to touch a file it wasn't asked to touch. It runs long enough that the useful thing to do is end it and carry the state forward, the one case I'd already built machinery for. Every one of those is the same event from where I sit: this session is now waiting on me.

With four to six sessions in a window and three to five windows, the only way to catch that event was to look. So I looked, in rounds: cycle the windows, read what each session was doing, deal with anything finished or blocked, go back to whatever I'd been doing. Between rounds, a session that stopped sat there. Twenty minutes was a good pass; some were much longer.

Now the state is reported to me instead. A session that goes quiet shows as idle in a list already on screen, and I answer it in under a minute — or I see it and know it's something to get to as soon as I can, which is a different and equally useful thing to know. Herdr classifies each agent pane as working, idle, done, blocked or unknown, and two of those carry most of the value. done is the same quiet pane as idle, labelled differently because the work finished while I wasn't looking at that tab. blocked means Herdr recognised an approval or question prompt on screen. "It finished" and "it's stuck on me" are the two things I most need to tell apart from across the room, and they're now different words in a list rather than two screens that look alike.

Nothing became automatic. Every action I take when I get there, I still start myself. What changed is when I find out. A session that wants an answer, a decision or a handoff now says so while it is waiting, rather than on my next lap through the windows. The improvement is entirely in the gap between a session needing me and my knowing about it, and that gap was the cost.

Adapting to Herdr, and adapting Herdr to me

The sessions moved out of the editor, one workspace per repo, and I learned Herdr's shape rather than reaching for the tmux commands I already knew. That part I just took.

But I wanted to keep some of the niceties of the workflow I already had. Before moving, I named the two things I use constantly and would notice losing, and went at them before they could become problems:

My tmuxp layouts. I like being able to launch or re-establish the several windows I'm used to in a repo without re-initialising them each time. Herdr has no equivalent config file. The server persists workspaces, tabs, panes and their directories itself, which covers the normal day but not a machine that has just come up. I looked at how to solve that, checked the plugin marketplace, and found a near-exact solution already there: herdr-spreader, which applies tmuxinator-style layouts from YAML.

Near-exact, not exact. It could build a layout but not re-apply one — every run created a second copy of everything — and its layouts had to live in one central file rather than in the repos they describe. Both gaps went upstream as PRs: --on-existing create|skip|sync so a re-run adds only what's missing, and include: so the central config can point at a layout file that ships with each repo. A stranger was running the first one within a day and found a real defect in it: my tab matching compared labels exactly, so another plugin that renumbers tabs to [1] name made every tab look missing and duplicated the lot. They diagnosed it and proposed the fix, which is now in.

Ctrl+Shift+W. In VS Code that hotkey is how I switch projects — pick the one I want from a list, no mouse, no hunting through windows. Nothing in Herdr did that, so I wrote ide-jump: a plugin that raises the editor window for the project a pane belongs to, either directly or through a filterable picker with the current repo already selected. It was built before it became an issue, which is the part I'd repeat. It has since taken an outside contribution adding a Windows backend, and it works with editors other than VS Code.

Two gestures, two solutions, neither of them a day's work. What made it cheap was that the platform had a seam wherever I needed one — a plugin marketplace with a maintained project already in it, and an upstream that takes PRs.

What VS Code is for now

Reading and editing code. That's it.

That reads like a small change and isn't: the integrated terminal was where every agent lived, which meant the editor window was also the session window, and the two were stuck together. Pulling them apart is what let the sessions be listed somewhere else. It's also why ide-jump had to exist before the move rather than after — with the terminal outside the editor, "get me to the code for this project" becomes a gesture that needs its own answer.

What it still costs

Jumping back and forth between the terminal window and each of my IDE sessions is a habit I'm still building. The plugin helps a lot — that's what it's for — but going from one window that held both to two windows that hold one each is a real change, and I notice it.

That's the trade the whole thing rests on: the terminal and the editor stopped being the same window, and in exchange every agent in every project reports its state to one place.

Try it

• Herdr — herdr.dev. Start it, make a workspace per repo, and run your sessions in it. The status list is the feature; everything else here is me refusing to give up two gestures.

• herdr-spreader — herdr plugin install yuk1ty/herdr-spreader, if you want your layouts back. The idempotence and repo-local-layout PRs (#17, #18) are open at the time of writing, so check whether they've landed before you rely on --on-existing sync.

• ide-jump — herdr plugin install agentience/herdr-plugin-ide-jump. Note that title matching needs your editor to put the folder name in the window title; VS Code needs "window.title": "${rootName}" for this to work.

If you're deciding whether it's worth it, the question I'd ask is the one Pat effectively asked me: how do you currently find out that a session needs you? If the answer is "I go and look," that's the thing this replaces.

So I went back to the discipline I'd let slide. When I want to bring the context back down, I run /handoff. Everything after that call is automatic: the document gets written, and the next session opens already reading it. Two thousand words of state instead of the 500K-token session they came from.

This is for long sessions across several repos or more than one machine. If your sessions are short and single-threaded, you don't have this problem yet.

TL;DR

• When I want to manage the context down, I run /handoff. It writes a handoff document into the repo: decided vs. open, traps, don't-touch, decisions I owe, verification state.

• The session writing it starts the fresh session — a hook replaces the tmux window with a fresh session that has already read the document and starts the work. This helps alleviate my brain's context overload with multiple sessions running.

• Drafting is delegated to a cheap subagent working from a digested transcript, but the salience — what mattered, what to avoid — comes from the session that did the work, written out before it hands over. That split is the load-bearing part.

• Versus /compact: you choose when it runs, never what survives, and you never see the result. A big window doesn't fix that, it postpones it. Nothing forces a checkpoint, so you carry the whole session all day, and that's what burns the limit.

• Installable, degrades cleanly without tmux, and mostly portable to other agents: github.com/agentience/agentience-skills

For work that runs across sessions and machines, I wanted a carry-forward I write, review and commit. Here's the actual artifact, from a real project, trimmed:

# /handoff — skill shipped and verified twice; only the post is left

## Work items
- [x] Built the relaunch chain — marker file + Stop hook — committed
      3ce9f60. Verified across 5 stubbed hook paths.
- [x] Verified the packaged skill end to end on a second machine, twice.
      Three defects found and fixed (f5475f5).
- [ ] **(in progress)** Retry the install on a machine with no nvm.
      Preflight passes there; the actual run has never been tried.

## Traps
- A running session keeps the command text it loaded at startup. Only a
  NEW session proves an edit works — testing in the session that made the
  edit tests the old text every time.
- The marker file must carry the `.claude/handoffs/` prefix, not a bare
  filename. Evidence in the log at 19:12:59: "named a missing doc —
  not relaunching."

## Don't touch
- The uncommitted work in the plugin repo — other sessions', not this
  one's. Commit path-scoped.

## Decisions needed
1. How much tmux-specificity to keep. Recommend: ship both halves, make
   the relaunch a clean no-op without tmux, say so in the README.

That's what /handoff leaves behind when I call it. You can find plenty of handoff variants; what happens to it next is where this stops looking like just another handoff, so that's where I'll start.

Closing the seam

Every write-up on session handoffs I've read stops one step short of here: write a good summary for the next session, and you're done. But a document does nothing until someone opens it, and with several sessions going, that can be hours. The work wasn't waiting on the handoff. It was waiting on me.

So the last thing /handoff does is leave a marker file naming the document it just wrote. A hook picks that up as the session ends and replaces the tmux window with a fresh session that starts by reading the document. Same window, same place on screen. What's in it is a new session, several steps ahead of where I left off.

That matters more than it sounds, because I'm never running one session. There are usually several going across different repos — eight, one day last week — and I lose track of them. Now the work doesn't idle while I'm elsewhere: I come back an hour later and the session has already read the document and is waiting to start, or has already started, because I asked it to when the handoff was written. Writing the handoff was never the part I dropped. Picking it back up was.

And it closes. The session that gets started this way opens by reading the document, works, keeps it current as it goes, and ends by handing it on. That's why the command has three modes rather than one:

• /handoff — write a new document and hand off.

• /handoff --read <path> — start a session by loading one, and own it from there.

• /handoff --next — bring the document you've been maintaining fully current and hand off on it, rather than writing a second document about the same work.

--next is what makes this a loop. A maintained document is only current as of the last time you touched it, which is never the moment you stop. So the last thing a session does is bring its own document up to date and pass it to the next one. Work that takes six sessions leaves one file behind, not six, and no session after the first one ever starts cold.

Write what's true, not what happened

The next session doesn't need the history. It needs to know what to do next, and enough context to do it well. Five headings cover that:

• Decided vs. open. Split honestly. A question you can answer by running one command isn't open, it's unfinished. Answer it now, while you have the context, rather than handing it to a session with less.

• Traps. Ordering constraints, stale artifacts, a test that passes for the wrong reason. Everything learned the hard way in the last four hours.

• Don't touch. Deliberate non-goals. Half the value of a handoff is stopping the next session from helpfully "fixing" something that's that way on purpose.

• Decisions you owe. Real forks, options and a recommendation, in the file. The next session can't read your conversation.

• Verification state. What was actually run and observed, written precisely enough that nobody rounds "5 of 7 paths tested" up to "it works."

The judgment isn't in the transcript to be summarized. A digest can tell you what was said and done; it can't tell you that one of those things was a dead end you'd rather never revisit. That distinction is why this is a document rather than a longer context window.

That list is the part worth stealing whether or not you install anything. It's five headings in a markdown file. Start writing them by hand at the end of your next long session and you'll get the document half of this, everything except the automatic pickup, without any of the machinery.

What the subagent can't know

Writing the document inside the session that's ending is the expensive way to do it: every turn re-sends the whole accumulated context, so the handoff costs the most exactly when that context is largest. So the work splits in two:

• First, the session that did the work writes out the salience: what's decided, what's open, what will bite, what not to touch, what it owes someone else. Two hundred words, no research. It already knows all of this.

• Then a script reduces the transcript — main loop plus every subagent sidecar — to a timestamped timeline: tool calls as one-liners, errors kept, thinking blocks and successful tool output dropped. Roughly 1.5% of the original. A Sonnet subagent drafts the document from that plus the brief, in a fresh context, so none of it lands in the window I'm trying to empty.

The digest gives coverage. Only the session that was there can give salience, and it's the one thing a fresh reader can't reconstruct from a transcript at any price. Skip that half and you get a document that's complete and unusable.

I measured this across the 66 handoff-writer runs on this machine: the writer takes a median of two minutes and spends about 9K output tokens. Its fresh input is a median of fourteen tokens. The digest is small and everything else is a cache read.

One side effect worth having: the digest is built from the transcript on disk, which still holds everything the live session compacted away. By hour four the subagent is reading hour one at full fidelity, while the session that lived through it is working from a compacted version of the same hour.

Whoever reads it, owns it

A handoff describes the moment it was written. The next session reads it, works three hours, learns six things. The file still says what it said this morning. By the third session it's lying.

So there's a rule: the session that reads the document maintains it while it works. Not at the end; sessions don't reliably get an end.

• Tick items as they're done. Mark in-progress ones with a line on where they stand, so an interrupted session leaves something that looks half-finished rather than untouched.

• Append to a dated progress log instead of rewriting it, so a later reader can tell what each session actually did.

• Put traps next to the item they bite.

What makes it hold is that the document carries its own update instruction, in the file. It gets pasted into fresh sessions where nothing else would enforce it. That rule is what --next hands forward: not a snapshot of when the work started, but a document that's been true at every step since.

Try it out

One self-contained directory, opt-in and reversible installer:

github.com/agentience/agentience-skills

The relaunch half needs tmux. Without it nothing breaks, you just do the last step yourself: /handoff writes the document and tells you the path, and you open a session and run /handoff --read <path>. That's one line of typing standing between the no-tmux experience and the tmux one. Everything else, the document, the three modes, the ownership rule, is identical. Start a new session after installing. A running session keeps the skill text it loaded at startup, so the one you install from won't see it.

If you're not on Claude Code

I built and tested all of this on Claude Code, so that's what the repo installs. But almost nothing here depends on it. The parts that carry over as-is are the ones that matter: the section set, the rule that the reading session maintains the document, splitting a mechanical digest from hand-written salience, and leaving a marker file at the end of a session so the next one opens itself.

Two pieces would need porting. The digest script reads Claude Code's transcript format, so you'd rewrite it against whatever your agent writes to disk, or skip it and draft from live context instead. And something has to notice the marker file when a session ends. Claude Code is the only agent I've tried, but I'd expect any that can run a shell command at that point to work. If yours can't, a wrapper script that runs the agent and then checks for the file gets you there from the outside.

The document is just markdown in your repo. That part works everywhere, including for the humans on the project.

Changes are welcome as PRs: a different section set, a port to another agent, whatever you had to fix to make it work where you are. And if you've solved this a different way, put it in the comments — I'd like to know what I missed.