handover

Handover

Handover

DOI

Claude Code, Cursor, and Codex forget everything between sessions. The next agent inherits a session summary nobody checked, re-derives what you already knew, and rebuilds what you deliberately threw away.

Handover is an agent-to-agent handover document with a header a machine can verify, plus deterministic tooling: a linter that scores it and checks it against the live repo, and a trap-based benchmark that measures whether the handoff actually transferred. The document, and the rules that keep it honest, are the product.

No LLM in any enforcement path. No network. No telemetry. Zero dependencies (plain Node, which Claude Code already requires).

Why this exists

Agents forget everything between sessions, and nobody checks their handoff notes. A session ends, the next agent inherits a summary that says “see discussion above.” There is no above. The reasons and the dead ends went out with the context window, so the successor re-derives what it can and rebuilds what it shouldn’t.

A better summary doesn’t fix this. What goes missing is the part you can’t recover by reading the code: approaches that were tried and failed, things deliberately not built, changes that were reverted and must not come back. Handover makes that the load-bearing part of the document, and every claim in it carries its own check.

Why not just CLAUDE.md or AGENTS.md?

Different jobs, and they compose rather than compete. CLAUDE.md and AGENTS.md are standing context: durable rules and project shape that are true every session, hand-maintained, read at startup. A Handover is a transfer: point-in-time state for one workstream, written at a session boundary, consumed once, then superseded.

The operational difference is that a Handover is checkable and a context file isn’t. It is anchored to a commit (true_at_sha), so drift since is measurable instead of assumed. It carries a verify_cmd, so status: done can be refused until that command actually passes. Nothing in AGENTS.md can go stale loudly, because nothing in it makes a falsifiable claim about repository state. That is the gap this fills. Keep your context files; this is the thing that hands off the work.

Try it in a minute

As a Claude Code plugin:

/plugin marketplace add geekidharsh/handover
/plugin install handover@handover

Exit and restart Claude Code (hooks only load at session start). Then work normally: any HANDOVER_*.md you save is checked for a valid header, /handover:write scaffolds a compliant handoff from live git state, /handover:lint scores one, /handover:audit reports what happened, and node bench/run.js measures whether an artifact transfers. The plugin also ships a behavioral gate (reads auto-approve, writes ask, destructive ops refused, repeated failures interrupt), a separable concern that is not part of the handover document; see Scope.

Or use the CLI directly: any repo, any harness

The document, lint, scaffold, and bench are plain Node (≥18) with zero dependencies; only the hooks and slash commands are Claude Code-specific. From any git repo:

node <handover>/bin/handover-scaffold.js > Docs/HANDOVER_myfeature_2026-08-01.md   # header pre-filled from live git/gh state
node <handover>/bin/handover-lint.js Docs/HANDOVER_myfeature_2026-08-01.md          # structure score (0-100)
node <handover>/bin/handover-lint.js <doc> --repo                                   # + does true_at_sha exist, how far has HEAD drifted
node <handover>/bin/handover-lint.js <doc> --verify --claims --strict               # + run verify_cmd and every claim's own check

(npm install -g the checkout and the same tools are on your PATH as handover-lint / handover-scaffold.) For enforcement without any harness integration, install the git hook; it validates any staged HANDOVER_*.md and fails open if Handover isn’t present:

cp hooks/pre-commit.sample .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Adopting Handover in another harness (Cursor, Aider, Codex CLI, your own runner) is documented in docs/PORTING.md.

The document

PROTOCOL.md is the full spec. A Handover document is a hybrid: a strict YAML header tooling validates deterministically, plus a human prose body. The header carries the facts that must never be lost or ambiguous: the commit SHA the claims were true at, the one unambiguous first action, the command that verifies the state, and whether it supersedes an earlier doc.

Two load-bearing ideas:

The header is gated: a Write/Edit landing a HANDOVER_*.md with a malformed header is blocked, with the exact fields to fix, and status: done is refused unless a verify_cmd is present. Header-only; prose stays advisory. /handover:write scaffolds a compliant doc, filling the header from live git/gh state so the machine facts are read, not remembered. See templates/handover.template.md and a worked examples/handover.example.md (scores 100/100).

Lint and bench: keeping it honest, measuring the transfer

The tooling that makes the document more than a convention:

$ node bench/run.js   # excerpt, one of three scenarios
=== scenario: reverted-feature (3 planted traps) ===
  artifact          lint     valid  traps covered  quality
  good.handover.md  100/100  yes    3/3            100/100
  bad.handover.md   16/100   NO     0/3            8/100
  (no artifact)     0/100    NO     0/3            0/100
  delta (good - bad): +92 quality points; trap coverage 3/3 vs 0/3.

Scope

Handover ships a behavioral gate in this same repo: a mutation gate (reads allow / writes ask / destructive deny), sticky cross-tool denials, and a loop detector. This is a separate concern: it governs any agent action, not the handover document. Its real home is a separate agent clearance / permissions layer: the automatic per-action floor that runs beneath a human checkpoint (the “human-at-the-gate” model). It is slated for extraction there; it happens to ship here for now and is not part of the handover-document definition. Its design history, the full gate table, and the per-project .handover/policy.json mechanics live in docs/ARCHIVE.md.

Naming note. The gate belongs to that separate clearance product and will carry that product’s name once extracted; until then it ships here unnamed. Once the gate is extracted, this repo is cleanly just the handover document.

Lineage

Handover began as the agent-to-agent wire format inside a broader exploration of human↔agent session continuity. The two concerns stayed distinct on purpose: a ledger tracks one project’s truth over time between a human and their agents; a handover transfers a workstream across an agent boundary, cold. This repo is only the second thing. Fuller design history in docs/ARCHIVE.md.

Trust posture

What it deliberately does not do

Where the score lies to you:

(The behavioral gate’s own limits, namely that regex is not a sandbox and that command-string matching can over-trigger on prose, are documented with the gate in docs/ARCHIVE.md and docs/SECURITY.md.)

Test

./test/run.sh

37 top-level checks, including three bundled sub-suites (test/doc.test.js, 39 pure-core assertions; test/verify.test.sh, 21 repo-aware checks against a throwaway git repo; test/hook.test.sh, 4 checks on the harness-independent git hook, including that it fails open). Coverage: the STRUCTURE rubric (placeholder/gaming/injection/H1-weighting/masking/determinism), the VERIFICATION layer (fabricated SHA, drift, future date, verify_cmd pass/fail, non-git degrade, and a command-injection canary), the Handover header gate, and (for the separable gate) allow/ask/deny classification, route-around detection (including via Task), loop escalation with the false-positive fix, and policy self-edit gating.

Status

0.4.1 (portability + per-claim verification; 0.4.1 is the archived release, protocol and plugin unchanged since 0.4.0). The handover document, its lint, and its bench are built and hardened; the behavioral gate ships alongside as a separable concern (see Scope). A trust-and-abuse review reweighted the rubric to score substance over shape, added the repo-aware --repo/--verify layer, policy tamper-evidence, and fixed a command-injection bug found in review. 37 test checks pass. The repo’s own handoff (docs/HANDOFF.md) scores 100/100 and passes --verify against this repo, so the tool eats its own dog food. It also demonstrates the limit honestly: because committing the handoff moves HEAD, a doc can never anchor to a commit that contains itself, so --repo always reports one commit of drift whose only changed file is the handoff. Reporting drift that invalidated nothing is exactly the gap tracked in issue #3. It has also been exercised end-to-end on an external repo by a cold agent (scaffold → fill → lint --repo/--verify, plus deliberate attacks: fabricated SHA, unproven done, placeholders, all caught; two real bugs that run surfaced, a UTC-vs-local date drift and a too-quiet unproven done, are fixed with regression tests). Full history in CHANGELOG.md; threat model in docs/SECURITY.md; archived design history in docs/ARCHIVE.md; what’s next in docs/STALENESS.md. Public since 2026-08-02 under Apache-2.0; the hand-off-time verify gate is the next step.

Open questions

The unfinished edges are tracked as issues, and the interesting ones are unfinished on purpose rather than merely unstarted:

Smaller, well-scoped starting points: add a bench scenario (one directory, no core changes), flag dead doc links (no network at all), or port the write-time gate to Cursor, Aider, or your own runner. CONTRIBUTING.md has the four invariants any change has to hold.

Author

Built by Household, the workshop behind household.dev’s apps. The rest of the shelf, as it is published: household.dev/tools. Cite via CITATION.cff or the DOI above.

License

Apache-2.0.