claude-handoff: Instructions file for Claude Code

AGENTS.md — instructions for AI coding agents

What this project is

claude-handoff turns Claude Code session transcripts (JSONL in ~/.claude/projects) into a single clean handoff.md another LLM can continue from, and distills a project's whole history into a persistent memory brief (--brief) injected at session start. Stdlib only; runtime code is the claude_handoff/ package plus a generated single-file build in single/.

Start here (green in four commands)

python3 -m unittest discover -s tests -v      # run tests
python3 -m claude_handoff tests/fixtures/agent_session.jsonl -o -   # smoke run
python3 scripts/build_single.py --check       # single-file build is fresh
uvx ruff check claude_handoff scripts tests   # lint (config in pyproject)

If all four pass, the tree is healthy. Packaging check when you touched pyproject.toml: pip install -e . && claude-handoff --version && chf --version.

Orientation — read in this order, only as far as your task needs:

You want to…	Read
Understand what the tool does for users	README.md (60-second scenarios + full flag reference), docs/GUIDE.md (day-with-it walkthrough + --brief mechanics)
Find which file holds what	INDEX.md, then the architecture map below
Touch the parser / JSONL schema	docs/DEVELOPMENT.md §2 (schema notes) — mandatory before parser edits
Understand why a design is the way it is	docs/DEVELOPMENT.md §3 (decision log, one row per decision)
Follow the working agreements	Invariants + workflows + gotchas below

Hard invariants — do not break these

• Zero runtime dependencies. Stdlib only. Do not add anything to pyproject.toml dependencies; do not import third-party packages. (Dev-only tooling like ruff via uvx is fine.)
• One package, one generated single file. Runtime code lives in the claude_handoff/ package (map below) with acyclic from .module import name imports. single/claude_handoff.py is GENERATED by scripts/build_single.py — never edit it by hand; rebuild after any package change (CI fails when it is stale).
• Python ≥ 3.9 compatibility (no match, no 3.10+ typing syntax outside from __future__ import annotations).
• Parse defensively. The JSONL schema is undocumented and drifts across Claude Code versions. Unknown record types are skipped, never fatal; content may be a string or a block list; corrupt lines are tolerated.
• Deterministic mode makes no network calls. Only --llm may touch the network — via stdlib urllib for API providers, or by spawning the local claude CLI for --llm claude-cli. No other subprocesses, no SDKs.
• Never invent transcript content. The exporter reorganizes and truncates; it must not fabricate. LLM outputs that claim facts carry session citations so they stay verifiable.
• Untrusted content stays data. Transcripts embed arbitrary external text; every prompt that consumes them, the handoff preamble, and the brief injection wrapper carry a data-not-instructions guard (pinned by InjectionDefenseTests — keep the phrase intact when editing prompts).
• Redact before egress. Secret-shaped strings are stripped from anything sent to an LLM and from every final document (redact_secrets via redact_doc — a written or pasted handoff is egress too); default on, --no-redact opts out (CLI only; hook and MCP always redact, and the config file may never set no_redact).
• Hooks are inert, not mute. They never raise, always exit 0, never call an LLM, and never create files on their own — but every swallowed error is reported on stderr (textutil.warn); tolerated parse/cache paths report under --debug / CLAUDE_HANDOFF_DEBUG=1 (textutil.debug). Never add a bare silent except.
• Never truncate instructions. Size caps may trim transcripts and chunk notes, never the prompt rules or the user's --focus.
• Cache is best-effort and content-addressed. A cache failure must never fail the run; bump CACHE_VERSION whenever CHUNK_PROMPT changes (brief note prompts self-invalidate — the prompt text is part of the hash). --focus goes only into the reduce pass so cached notes stay reusable.
• Chunk calls are sequential for SERIAL_PROVIDERS (claude-cli, ollama) — parallel claude -p subprocesses conflict and local Ollama boxes choke. API providers fan out via ThreadPoolExecutor; keep the serial/parallel split.