portable-handoff

Portable Handoff is a local-first command-line tool whose goal is to maintain the same context across different AI chats, models, and coding agents, avoiding the need to re-explain the project every time you switch AI tools.

Purpose After working with a coding agent for a while, the context window fills up or you switch tools, and the next session often starts from scratch. Directly asking the model to "summarize what we did" yields a summary that reads smoothly but may quietly fabricate content. Portable Handoff instead writes a capsule: a Markdown file in which the model provides meaning and local code provides facts. Git status, file hashes, and timestamps come from the local machine, not from the model's recollection. Every claim is labeled with its source and confidence.

Main capabilities

• Generate a capsule: the model writes a draft JSON based on what it has seen, local code collects facts and merges them, and when the two disagree, local facts take precedence.
• Load a capsule: on load, it checks the embedded JSON, the SHA-256 digest, the consistency of the two halves' content, and how well the current repository matches the recorded content. Staleness status returns fresh, possibly_stale, stale, obsolete, unverified, or missing. Capsules that fail integrity checks are rejected and never repaired.
• Status promotion: unanswered questions in the draft are promoted to blocked status rather than in_progress.
• Publish warnings: from git branch --remotes --contains, not written by the model.
• Trust labels: trust: verified requires a deterministic source (git, tool, test, file, transcript), otherwise it is downgraded to claimed, preventing the model from whitewashing recollection into fact.
• Safe handling: imported prose is treated as data rather than instructions; paths from capsules are validated as repository-relative paths before use; next_action.command is printed as inert fenced text and labeled read_only/review/dangerous, and is never executed; text is stripped of terminal control sequences and invisible or bidirectional Unicode; high-confidence secrets are redacted before hashing or writing, and reports retain counts and categories but not matched values.
• The digest does not prove authorship: it is an unkeyed SHA-256 that can catch truncation and accidental edits, but anyone who edits the JSON can recompute it.

How to use

1. Clone the repository. A pip install alone will get you the CLI, but the skill files the agent actually reads live in the same clone, and pip does not package them.
2. Requires Python 3.11 or newer. No runtime dependencies, no network access, no account, no API key, no database, no vector store. Run doctor first to check the current environment; it outputs supported, degraded, or unsupported.
3. Skill install locations: for Claude Code, ~/.claude/skills/ (machine-wide) or .claude/skills/ (single project); for Codex, ~/.codex/skills/ or .codex/skills/; Cursor's agent already has a shell and can run CLI commands directly, or you can convert existing instructions into project rules.
4. For environments without a shell (such as pure ChatGPT or Claude web chat), there is no way to write files or run doctor, so there is nothing to install. You can paste the shape of skills/handoff/assets/handoff-template.md into the chat and have the model fill it in and save the returned content. This is a draft, not a capsule; it has no summary and no verified repository facts. Later, on a machine with the CLI, you can run finalize to get a real capsule.
5. Let the agent install it itself: paste the specified prompt into Claude Code, Codex, Cursor, or another tool with a shell; it includes cloning, pip install -e ., running python scripts/install_skill.py --destination pointing at the skills directory, and running portable-handoff doctor --cwd . and pasting the output verbatim.
6. finalize prints one line you can cite. The claims list in the draft accepts bare strings, defaulting to model_inference / inferred, so the model only needs to spend tokens on the few items that deserve a stronger label.
7. The capsule stores its content in both prose and canonical JSON; load and export each give half.

When to use it

• In Claude Code, Codex, Cursor, or any terminalwork.
• When you need to migrate coding session context between different AI tools.
• When you need verifiable repository facts rather than model recall.

Limitations

• Requires a filesystem and shell. Not suitable for pure ChatGPT or Claude web chat.
• Slash command registration varies by host; artifacts and the CLI behave the same everywhere.
• Semantic quality depends on the model doing the compression. In real capsules most entries end up labeled inferred, honest but thin; capsule quality depends on what the model notices. Compression loses information. Git facts prove repository state, not what anyone said.
• v0.1 has no sync, no accounts, no team features, and no second model checking the first model's work.
• The quality test tool tests/quality/evaluate_quality.py runs twelve scenarios through the real pipeline and has been mutation-tested; it can show that the pipeline preserved what it was given, but not how much the model provided.
• The license is Apache-2.0. Commits require a Signed-off-by line (git commit -s) and follow the DCO.