/handoff does not ask the next session to read your project. It asks it to prove that it did.
The handoff is a specialized skill for Claude Code designed to ensure accurate knowledge transfer between successive AI sessions. Rather than relying on simple summaries, it uses a validation loop where the expiring session quizzes the new one to prove it understands the project context. The outgoing session generates an exam from its active memory, grades the incoming session's cited answers, and automatically repairs documentation if inaccuracies are detected. This process replaces passive reading with verified comprehension, granting a "green light" only when the new session is fully prepared to continue the work. By catching misunderstandings before they impact the code, the tool prevents the loss of critical project details during context transitions.
You end a long session and open a fresh one. It reads the handoff document, says it has the picture, and sounds right. Then it proposes the thing the last session ruled out, for a reason nobody wrote down. A document read closely looks exactly like one that was skimmed, and nothing in an ordinary handoff tells the two apart: you do not always write everything down and sometimes, even if rarely, important information is lost on every transfer.
So /handoff writes it down, then asks the next session questions only a reader could answer. It
pulls what the old session knows into one handoff document. It writes the questions out of live
memory, while that memory still exists. Not every subject earns one: a question is spent on a
decision and why it was taken, on something that must not be done, on the exact next step, or on
where something lives, and only where it still matters when the work resumes. Anything the old
session marked BLOCKING gets a question of its own, ahead of the rest.
Then it makes every answer cite the document it came from, or say plainly that the answer is not there. It grades what came back against its own memory, one verdict at a time. Where an answer proves a document wrong, that document gets repaired on the spot, not filed as a note for later. Only then does it print the green light.
A summary cannot do that, and a summary is what you already have. Nothing about one tells you whether it was read, whether it was enough, or whether the fact that mattered was in it. Summaries get graded by the next mistake. These answers get graded first.
| An ordinary handoff | /handoff |
|---|---|
| writes a document | writes a document, then examines its reader |
| assumes it was understood | measures whether it was |
| you find out when the work goes wrong | you find out before the work starts |
| leaves your documents as they already were | repairs them where the exam proves them wrong |
| one-way | the feedback lands while the old session can still check it |
One clone installs it. One command tells you it worked. It needs no framework and no configuration, and it runs in any project you already have.
Requires Claude Code 2.1.110 or newer. Either route below needs read access to the repository.
The repository is the skill, so cloning it into your personal skills directory is the whole install:
git clone https://github.com/1Popov/handoff.git ~/.claude/skills/handoffWindows PowerShell does not expand a leading ~ in an argument it hands to git. It exits zero,
reports a successful clone, and creates a directory named ~ beside you, so write $HOME out:
git clone https://github.com/1Popov/handoff.git "$HOME\.claude\skills\handoff"Then type /handoff with no argument. It answers with its three subcommands, which is how you know
the install took. A running session picks up a newly installed skill without a restart; if yours
does not, /reload-skills re-scans.
What is installed is the clone, so updating is pulling it and nothing else:
git -C ~/.claude/skills/handoff pullgit -C "$HOME\.claude\skills\handoff" pullIf that directory already holds an older copy that was downloaded rather than cloned, remove it
first. git clone refuses to write into a directory that is not empty.
There is a second route for people who keep their tools as plugins. It needs Claude Code 2.1.142 or
newer, and it names the command /handoff:handoff rather than /handoff. Both lines are typed
inside Claude Code:
/plugin marketplace add 1Popov/handoff
/plugin install handoff@handoff-skill
Installed that way it updates through /plugin, never through git:
/plugin marketplace update
/plugin update
Take one route or the other. Both at once leaves two copies of the same skill on your machine, under two different names.
The two sessions are two Claude Code windows, open at the same time on the same project folder. The old one has been doing the work and is running out of room. The new one is the window you just opened to carry on. They never talk to each other: everything passes through four files in your repository, which is also what lets you read the whole exchange afterwards.
In the session that holds the knowledge, run /handoff pack. It writes the handoff and the
interview, commits them, and prints the prompt to paste into the next session.
Open a second window in the same project, paste that prompt, and run /handoff unpack. It reads
what the handoff names, writes its answers, and stops.
Back in the first window, run /handoff check. It grades. On green you are done. Otherwise it names
what to repair and you run the second step again, three rounds at most.
/clear is not the move here. Clearing or closing the old window destroys the grader, and check
then grades from an empty context and prints a green light over nothing. Keep that window open until
it prints the light.
OLD SESSION NEW SESSION
/handoff pack ──── writes ────► RESUME-HERE.md
INTERVIEW.md
│
▼
/handoff unpack
answers with a source, stops
│
ANSWERS.md
│
/handoff check ◄──────────────────────┘
one verdict per answer:
PASS / FAIL / DOC-GAP / DOC-STALE / NO-MEMORY
│
├── not green ──► repairs the DOCUMENT, then round 2
└── green ──────► STATUS: GREEN
PASS is a correct answer. FAIL is careless reading, and it is the only verdict that blames the session answering. DOC-GAP means the fact is genuinely missing from the documents, so the document is repaired before the feedback goes back. DOC-STALE means a document asserts something that is no longer true. NO-MEMORY means the grader does not hold the expected answer itself. It is never a pass, and it never carries a green light.
An honest "not in the seed docs" is graded as a defect in the documents, not in the reader. A confident guess with no source is what fails.
Here is a real round from this project's own history. The old session asked about a measurement it had made itself, one whose result had gone into a project document weeks earlier. The new session found that document, read it correctly, and answered with the citation. The grade came back:
DOC-STALE — the answer is a faithful reading of
.planning/STATE.md, and that entry is no longer true. […] Nothing is wrong with the reading. The document was wrong. Repaired before this correction was written.
The new session did nothing wrong. A later measurement had overturned that entry and nobody had updated it, so the document had been wrong for every session that read it since. Nothing about the answer could have revealed it. The only thing that could was a question whose real answer one session still held in memory, asked while it still held it.
Most handoffs are one-way: you write the document, the next session reads it or does not, and you find out which when something goes wrong. This one closes. The answers come back while the old session still remembers, a misreading is corrected before it reaches the work, and a wrong document is fixed at its source. Every cycle leaves the project's own documents more correct than it found them, audited against a memory that was about to disappear.
Not your whole project. The handoff names what to read and what to merely know the location of, and an entry can name three sections of a fifty-page log instead of the log. The old session decides that, because it is the one that knows, and it reports what the list will cost before you spend it.
A second round is cheaper still: it reads the corrections and the documents they name, answers again only what did not pass, and carries the rest forward untouched.
Scope it too tightly and the missing fact comes back as a documentation gap, repaired by the same loop that catches everything else.
Six places this will not help you.
- It grades what it thought to ask. At most ten questions, written from one session's memory. What that session forgot it knew, it cannot ask about, and no verdict covers it.
- The green light is the grader's assertion, and nothing on disk can check it. The expected answers exist only in the old session's context, deliberately: a key in a file is a key the new session can read instead of reading the documents. The cost of that choice is that a PASS is exactly as good as the grader's memory, and there is no way to audit one after the fact.
- Grading spends the old session's remaining context, the resource that makes it a grader. Run
packwhile there is enough of it left. If that session has already been auto-compacted, its memory is thinner than it looks and nothing here measures that. - You open the new session and you relay the green light. No hook does it for you: a file-change hook fires only inside a session that is already running, so it can neither wake an idle session nor start one that does not exist.
- Three rounds maximum. Still not green after three means the failing section of the document gets rewritten, rather than the new session being questioned a fourth time.
- The tool closes nothing. The green light reports that the context transferred and says you can close the old session. Closing it is yours to do.
Four files under .planning/handoff/: RESUME-HERE.md, the master handoff; INTERVIEW.md;
ANSWERS.md; and FEEDBACK.md, which carries the verdicts and the green light. Each has exactly
one writer.
A project that already keeps its documents in .planning/ gets them written into it; a project
without one gets the directory created. The skill needs no framework, and outside Claude Code it
needs only git.
pack also edits documents you wrote yourself, wherever a fact in them is demonstrably wrong. It
stages what it wrote or repaired one file at a time, named one by one and never the working tree
wholesale, so every edit is visible in the commit and can be undone on its own. It never pushes.
Why none of this runs by itself, and the three automation options you could add: AUTOMATION.md.
MIT. See LICENSE.