Portable Handoff
Carry verified project context across AI sessions, models, and coding agents.
- Source repo
- legoambarish/portable-handoff
- Stars
- ★ 21
- Last updated
- 16d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 84/100 · Good
At a glance
- Works with
- Universal · cross-platformCodex · Claude CodeChatGPT · Claude.ai (Unsupported)
- 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.
- Main limitation
- Python 3.11+, shell access, and a writable filesystem are required, excluding direct operation inside plain ChatGPT and Claude web conversations.
- Source review
- 84/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 | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Portable Handoff This agent | 84 · Good | ★ 21 | 16d ago | Python | Codex · Claude Code |
| Remnic Agent Memory | 85 · Good | ★ 206 | 4d ago | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| zer0dex Local Memory | 84 · Good | ★ 60 | 2d ago | Python | — |
| GameDesignOS: A Local-First Operating System for AI-Assisted Game Design | 78 · Good | ★ 395 | 1mo ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows a local-first tool with no network or runtime dependencies, read-only CI repository permissions, adapters restricted to explicit roots, and rejection of symlink escapes. Capsule-supplied commands are displayed as inert, risk-labelled text and are never executed. Data flow, path constraints, integrity checks, and external effects are thoroughly described. Deductions apply because there is no general interactive confirmation gate before capsule writes; secret detection expressly covers only high-confidence patterns while capsules may retain absolute paths and other sensitive context; build and development dependencies use lower bounds and GitHub Actions are not pinned by commit digest; no explicit backup, undo, or atomic rollback procedure is documented; and although claim provenance is strong, the referenced CLEAN_ROOM, NOTICE, and third-party notice contents are absent from the supplied evidence and maintainer identity is generic.
The README, project metadata, CI, and supplied tests agree on supported Python versions, absence of runtime dependencies, host support, and security behavior. Tests cover duplicate keys, non-finite numbers, parent cycles, unknown record versions, unsupported SQLite, symlink escape, and non-mutating reads, with explicit failures. Dependency availability is reduced because operation still requires Python 3.11+, a shell and writable filesystem, Git is needed for full repository facts, and pip installation alone omits the skill files consumed by agents.
The material clearly distinguishes Claude Code, Codex CLI, Cursor, generic terminals, and web chats without shell access. The doctor capability states describe supported, degraded, and unsupported environments, while boundaries such as no sync, accounts, team features, signing, or second-model review are explicit. Trigger precision is deducted because automatic skill triggering is only described at a high level and the actual SKILL.md and trigger conditions are not supplied for inspection.
The README has strong information architecture, a contents list, platform-specific installation, creation and reading workflows, security, limits, contribution guidance, and licensing. Commands, schema terminology, and product naming are consistent. Apache-2.0 metadata matches the complete license text, and limitations are unusually concrete. Deductions apply because examples are extensive but there is no dedicated FAQ or systematic troubleshooting section; version identifiers are present but no changelog or compatibility history is supplied; and responsibility is attributed only to generic contributors and the repository vulnerability channel, without named maintainers, a support commitment, or a clear release owner.
The artifact is usable by both humans and parsers through Markdown plus canonical JSON, with briefing and prose-export modes. Combining model-authored meaning with locally collected Git, hash, and timestamp facts offers clear marginal value over an unconstrained conversational summary. Cost-benefit is reduced because users still need model draft generation, preflight and finalize steps, plus host-specific skill or rule installation; claims such as roughly 15% briefing size remain documentation assertions in this static review.
The design records provenance and trust for claims, restricts verified status to deterministic git, tool, test, file, or transcript sources, defaults model material to inferred, and downgrades unsupported trust elevation. Major README claims are corroborated by project metadata, CI configuration, and focused tests, while fact, claim, and inference categories are sharply separated. No deduction is warranted within these three static criteria; the full scores assess the documented traceability structure only and do not imply that tests or runtime behavior were independently executed.
- The unkeyed SHA-256 digest detects corruption or accidental edits but does not authenticate an author; an editor can recompute it.
- Command risk classification is an offline heuristic, not a sandbox; never execute a capsule-supplied command without human review.
- Secret redaction covers only high-confidence patterns, so inspect absolute paths, remote details, branch names, and unidentified credentials before sharing.
- The project is classified as Alpha and the supplied material contains no changelog, signing mechanism, or explicit compatibility commitment.
- This assessment is based only on the supplied static files; the CLI, tests, quality harness, and installation workflow were not executed.
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.