Portable Handoff
Carry verified project context across AI sessions, models, and coding agents.
- Source repo
- legoambarish/portable-handoff
- Stars
- ★ 23
- Last updated
- 2mo ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 80/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeChatGPT · Claude.ai (Unsupported)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Claude Code user halfway through a refactor can preserve constraints, corrections, blockers, and Git state before the context window fills.
- Not a fit if
- Users who need to create and validate capsules inside plain ChatGPT or Claude web chats
- Teams needing sync, accounts, or collaboration features in v0.1
- Anyone needing cryptographic proof of capsule authorship
- Source review
- 80/100 · Good
What does this agent do, and when should you use it?
Portable Handoff is a local-first Python CLI and skill package for transferring project context between AI sessions, models, and coding agents. A model supplies the semantic account, while local code records Git state, file hashes, and timestamps and overrides the model when those sources disagree. The result is a Markdown capsule containing both readable prose and canonical JSON, with provenance and trust labels attached to claims. Its interfaces include the preflight, finalize, load, validate, list, export, and doctor commands, plus integration material for Claude Code, Codex, Cursor, and generic shell-based hosts. It requires Python 3.11+, a shell, and a writable filesystem, but no account, API key, network service, database, vector store, or runtime dependency; plain ChatGPT and Claude web conversations can only prepare unverified drafts.
The workflow begins with portable-handoff preflight --cwd . --source-host codex, which assesses the environment and collects deterministic repository evidence. A model then writes draft JSON from the conversation and available project context; constraints, decisions, and other claims can carry explicit provenance and trust, while bare strings default to model_inference / inferred. portable-handoff finalize --preflight .handoff/evidence/preflight-xxxx.json --draft DRAFT.json --output auto merges that draft with the local evidence, gives machine facts precedence, redacts high-confidence secrets, validates paths, and normalizes trust labels. It writes a Markdown capsule containing human-readable prose, canonical JSON, and a SHA-256 digest. load latest produces a briefing for a fresh session while checking the embedded JSON, digest, agreement between both representations, and the current repository; validate checks a named capsule, list enumerates capsules, and export --format prose creates pasteable text. The system can promote an unanswered question to blocked status, report whether a recorded commit was reachable from a remote, and display a proposed command as inert text with a risk label without executing it.
- A Claude Code user halfway through a refactor can preserve constraints, corrections, blockers, and Git state before the context window fills.
- An engineer moving among Codex, Claude Code, and Cursor can use one capsule format instead of re-explaining the project to every tool.
- A solo developer working across local repositories can distinguish model recollection from machine-recorded commits, hashes, and timestamps.
- A maintainer pausing work can preserve an unanswered decision as an explicit blocker so the next session does not proceed under a false no-blockers state.
- A user working in a chat interface without shell access can prepare a template-based draft, then finalize it later on a machine that has the CLI.
- A developer reviewing a capsule received from elsewhere can verify its digest, sanitize control and bidirectional characters, validate repository-relative paths, and redact high-confidence secrets before use.
How do you install or deploy this agent?
Python 3.11 or newer is required. Run:
git clone https://github.com/legoambarish/portable-handoff
cd portable-handoff
pip install -e .
portable-handoff doctor --cwd .A pip installation alone does not include the skill files read by agents, so retain the repository clone. For Claude Code, run python scripts/install_skill.py --destination ~/.claude/skills/handoff; for Codex, run python scripts/install_skill.py --destination ~/.codex/skills/handoff. For Cursor, run mkdir -p .cursor/rules followed by cp integrations/cursor/commands/handoff.md .cursor/rules/handoff.mdc; automatic loading additionally requires the appropriate alwaysApply or globs frontmatter. No account, API key, or runtime network service is required. Git is optional, but its absence produces degraded operation with repository facts recorded as unknown.
How do you use this agent?
Start with portable-handoff doctor --cwd . in the relevant directory to confirm that the host is supported or identify degraded operation. To create a capsule, run portable-handoff preflight --cwd . --source-host codex, have the model produce DRAFT.json, and then run portable-handoff finalize --preflight .handoff/evidence/preflight-xxxx.json --draft DRAFT.json --output auto, replacing the example preflight name with the actual generated path. On success, finalize prints one JSON line containing fields such as outcome, path, schema_version, validated, and redactions. In a new session, use portable-handoff load latest --cwd . for the compact briefing. Use portable-handoff validate CAPSULE.md --cwd . to verify a file, portable-handoff list --cwd . to enumerate capsules, or portable-handoff export CAPSULE.md --format prose to prepare text for a chat. In plain ChatGPT or Claude web conversations, copy the structure from skills/handoff/assets/handoff-template.md, generate a draft, save it, and later run finalize on a machine with the CLI; the chat-only result is not a validated capsule.
What are this agent's strengths and limitations?
- It separates model-authored meaning from locally collected Git state, file hashes, and timestamps, giving deterministic evidence precedence during conflicts.
- Claims carry provenance and trust, and only deterministic sources such as Git, tools, tests, files, or transcripts can retain verified status.
- Capsules contain both readable prose and canonical JSON, with digest, representation-agreement, and repository-state checks for detecting damage or staleness.
- It runs locally without accounts, API keys, network access, a database, a vector store, or runtime third-party dependencies.
- Imported content is treated as data: secrets are redacted, terminal and invisible Unicode controls are stripped, paths are constrained to the repository, and recorded commands are never executed.
- Python 3.11+, shell access, and a writable filesystem are required, excluding direct operation inside plain ChatGPT and Claude web conversations.
- The pip package does not carry the agent skill files, so a complete integration requires retaining the clone and installing or copying host-specific files separately.
- Semantic quality still depends on the model performing compaction; the documentation notes that many real entries may remain inferred and that compaction loses information.
- Version 0.1 has no synchronization, accounts, team features, or second-model review.
- The unkeyed SHA-256 digest detects accidental edits or truncation but does not prove authorship, because an editor can recompute it.
- Operation without Git is degraded and records repository facts as unknown.
How does this agent compare with similar options?
Compared with asking a model to summarize a session, Portable Handoff assigns interpretation to the model but obtains Git state, file hashes, timestamps, remote reachability, and integrity results from local code, then labels every claim by source and trust. That stronger evidence trail adds a preflight, draft, and finalize workflow and requires a local shell and filesystem; it still cannot guarantee that the model noticed every important semantic detail.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Portable Handoff This agent | 80 · Good | CLIFree | ★ 23 | 2mo ago | Python | Codex · Claude Code |
| Piia Engram | 77 · Good | CLIFree | ★ 165 | today | Python | Codex · Claude Code |
| Remnic Agent Memory | 73 · Some gaps | CLIFree + model costs | ★ 232 | 2d ago | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| GameDesignOS: A Local-First Operating System for AI-Assisted Game Design | 71 · Some gaps | CLIFree | ★ 452 | 2mo ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The CLI is described as local-first with no runtime dependencies or network access. The skill declares Bash, Read, and Write, treats imported content as untrusted data, and presents next-action commands as inert text, supporting limited access and clear data flows. Security notes cover high-confidence secret redaction, path checks, and digest limits, while acknowledging incomplete secret detection and heuristic command labels. The packet does not establish per-action confirmation or a recovery process, so scores are reduced.
The CLI uses structured error types and exit codes, and the skill requires verbatim command results. README, CLI, and security notes are broadly consistent about capsule use and limits. CI configuration covers multiple operating systems and Python versions, but is not evidence of a run here; installation still depends on obtaining Python, Git, and build tooling, so dependency availability and failure handling are not fully demonstrated.
The README and skill target context transfer across chats, models, and coding agents. They give paths for Claude Code, Codex, Cursor, generic shells, and a draft-only option without a shell, and explain when to stop, degrade, or offer only a draft. The trigger is specific and host capability is checked through doctor, supporting high scores.
The README includes a contents list, platform-specific installation instructions, create/read examples, security guidance, and limits. Apache-2.0 metadata matches the supplied license. Version 0.1.0 and alpha status are stated, but the packet contains no changelog. Contribution and DCO processes are mentioned, but no maintainer or ongoing update responsibility is identified, so those items lose points.
The product separates model semantics from local Git, hash, and timestamp facts and produces a readable, validated continuation briefing. Its quoted command output is usable and it addresses repeated explanations and summary hallucinations. Semantic quality still depends on what the model captures; the README says entries are often inference, and setup requires a clone and Python environment, so cost-benefit is not full marks.
The README describes provenance labels, deterministic facts overriding model claims, integrity checks, and the fact that a digest cannot prove authorship. The CLI shows JSON output and concrete command behavior; supplied adapter tests support untrusted transcript handling and rejection of some malformed inputs. Several important behaviors remain documented claims, and the test sample does not establish the whole product or any executed result, so cross-source corroboration is partial.
- The SHA-256 digest does not authenticate the author; review capsules before sharing because secret detection covers only high-confidence patterns.
- Semantic compaction depends on the model and may omit context. Do not treat inferred content as verified facts or run capsule commands without review.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/portable-handoff)<a href="https://followagents.com/en/agents/portable-handoff"><img src="https://followagents.com/badge/portable-handoff.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.1.0-alpha Pre-release
Release notes excerpt
First public release. Portable Handoff compacts an AI coding session into one Markdown file: the active model writes the goal, decisions, corrections, and next action, and a local script writes the parts a model shouldn't be trusted to remember on its own: the current Git branch and commit, whether that commit was ever pushed anywhere, and file hashes. Every claim carries a label for where it came from and how much to trust it, and a claim marked verified requires a deterministic source, never just the model's word. Standard library only, no runtime dependencies, offline by default. No …View on GitHub ↗
FAQ
Does it require a paid service, API key, or internet connection?
Will it execute a next-step command found in a capsule?
next_action.command is rendered as inert fenced text and labeled read_only, review, or dangerous.What happens if a capsule is altered or the repository has changed?
load checks the embedded JSON, SHA-256 digest, agreement between prose and JSON, and the current repository against the recorded state. A capsule that fails integrity checks is refused rather than repaired; staleness is reported as fresh, possibly_stale, stale, obsolete, unverified, or missing.Is Git mandatory?
doctor reports a degraded capability without it, and repository facts are recorded as unknown.Does the digest establish who authored the capsule?
Thanks — we use this to improve the page.