agent-handoff
Health Uyari
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Gecti
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Move native coding-agent sessions between Codex and Claude Code as files or end-to-end encrypted links.
agent-handoff
English | 简体中文
Move the actual coding session, not a hand-written handoff summary. Share a Codex or Claude Code task as a portable file or end-to-end encrypted link; the receiver imports it as a new native task and continues the conversation.
Conversation, tool evidence, images, and task metadata travel together. Same-agent transfers preserve native event structure; cross-agent transfers use a neutral transcript. No screenshots, copy-paste, account, or server-side conversation history.
Install in 30 seconds
# Claude Code
claude plugin marketplace add https://github.com/DavidDingXu/agent-handoff
claude plugin install agent-handoff@agent-handoff
# Codex
codex plugin marketplace add https://github.com/DavidDingXu/agent-handoff
codex plugin add agent-handoff@agent-handoff
Restart the agent, then say “share the current task” / 「分享当前任务」. The receiver installs the same plugin and says “import <file/link>” / 「导入 <文件/链接>」. Both sides need the plugin; no Go toolchain or Cloudflare account is required.
Compatibility
Verified on 2026-10-27 with Codex CLI 0.164.0 and Claude Code 2.1.311:
plugin installation, imported Codex history read/resume/list (including a fresh
home), and Claude resume with the imported history sent to a local API fixture.
CI repeats these native-client checks against the current npm releases; ordinary
unit tests alone do not certify a new client version.
Codex exports support plain and Zstandard-compressed rollouts, including
pagination bases. On a fresh home, Codex creates its own database on first launch.
Cross-agent Codex imports use model_provider from the receiver's baseconfig.toml, defaulting to openai. Runtime command-line overrides and named
profile files are not inferred. Continue a Claude import from its target
directory with claude --resume <session-id>, or use the returnedfallback_command in its indicated fallback_shell (sh or PowerShell).
These checks cover local coding sessions and text/tool history. They do not
certify the Claude web chat, cloud-only tasks, multi-agent child-session trees,
or full cross-agent image/attachment restoration. Embedded media remains in the
raw source session; account-bound attachment references are not made portable.
Highlights
- Four-quadrant handoff — codex→codex, codex→claude, claude→codex, claude→claude. Same-agent imports preserve native events and content while rewriting the identity fields required for a new task; cross-agent imports are semantic via an agent-neutral transcript.
- Zero-config encrypted links —
--format linkencrypts locally with AES-256-GCM and uploads ciphertext to the project-operated free service. If that service is unavailable, the CLI automatically tries an anonymous multi-provider relay; if every upload fails, it keeps a local zip. Teams can connect their own file service through configuration without depending on Cloudflare. See docs/link-service.md. - Secret scan before export — six high-confidence rules (OpenAI/Anthropic keys, AWS keys, GitHub tokens, private key blocks, bearer JWTs) block a share until you explicitly confirm. Findings are always reported, redacted for display.
- Never touches your data — import appends one new task and nothing else. Existing threads, indexes, and database rows are never modified; automatic backups are taken before every write.
- One static binary — pure Go (CGO-free sqlite), builds for macOS/Linux on amd64/arm64 and Windows amd64. JSON output for agents and humans alike.
Architecture

The core owns encryption, bundle validation, and append-only native import.
Users extend file uploads through declarative configuration; new agent adapters
remain reviewed source integrations until a third implementation proves a safe
cross-platform plugin contract. See extensions and customization.
Why not just write a handoff note?
| Method | Conversation and tool evidence | Opens as a native task | File or encrypted link | Codex ↔ Claude Code |
|---|---|---|---|---|
| Copy/paste or summary | Partial | No | Manual | Manual rewrite |
| Generic handoff prompt | Summarized | No | Usually text | Summarized |
| agent-handoff | Included | Yes | Both | Built in |
The product loop is intentionally receiver-driven: every shared file or link carries the installation path, so a teammate can install once and continue the task without asking the sender to reformat it.
Other install options
Standalone CLI — macOS/Linux:
curl -fsSL https://raw.githubusercontent.com/DavidDingXu/agent-handoff/main/install.sh | sh
Standalone CLI — Windows PowerShell:
irm https://raw.githubusercontent.com/DavidDingXu/agent-handoff/main/install.ps1 | iex
Or download an archive from Releases. Both installers require and verify the published SHA-256 checksum.
From source (Go 1.26+):
git clone https://github.com/DavidDingXu/agent-handoff && cd agent-handoff
make build # → bin/agent-handoff
make install # → $(go env GOPATH)/bin/agent-handoff
Quick start
Once the plugin is installed, everything is conversational — your agent drives the bundled agent-handoff skill.
The screenshot below comes from the real agent-handoff Skill running inside
Claude Code. It shows the native file-or-link question rather than a standalone
CLI demonstration.

Claude Code loads the Skill and asks whether to export a permanent zip or create an encrypted link.
The native choice appears whenever the current agent mode exposes its question
tool. Codex modes without request_user_input show the same file-or-link choice
as a concise text question and wait for the reply; they never silently choose a
format or imitate a native numbered form. Successful links are always printed
verbatim in a copyable code block, including the required #h= or #k=
fragment.
Share the current task
You: “share the current task” / 「分享当前任务」
The agent produces fix-flaky-retry-test.agent-handoff.zip and shows a card: title, size, 27 messages, 2 images. Send the file over IM/email.
Share as a link
You: “create a share link” / 「生成分享链接」
The agent returns an end-to-end encrypted HTTPS link without an account, token, or deployment. The project-operated compatible service (currently the optional Worker implementation) is used first, with a 10-minute default and up to 24 hours via --ttl. If it is unavailable, anonymous providers are automatic fallbacks (24 hours by default, configurable up to 7 days; a provider may delete its copy sooner). The decryption capability stays in the URL fragment, so always send the full link. Every service is best-effort; use a zip when delivery must be permanent. See docs/link-service.md.
Use your own file service
The built-in service needs no configuration. To use an existing domestic object
store, enterprise file platform, or another file service, declare an HTTP
provider in the platform config directory at agent-handoff/config.json:
{
"providers": [{
"name": "my-service",
"upload_url": "https://files.example.com/api/upload",
"upload_type": "multipart",
"file_field": "file",
"headers": { "Authorization": "Bearer ${MY_FILE_TOKEN}" },
"response_type": "json",
"url_json_pointer": "/data/url"
}]
}
Keep tokens in local environment variables, not in the config or conversation.
agent-handoff still uploads only locally encrypted ciphertext, and the receiver
needs no configuration for that file service. If every configured provider
fails, the CLI returns a local zip and does not silently upload elsewhere. See
custom providers for config paths,
fields, and raw/multipart examples.
Import on the receiving side
Your teammate just tells their agent (Codex or Claude Code, with the plugin installed):
“import /path/to/fix-flaky-retry-test.agent-handoff.zip” / 「导入 <文件>」
“import https://share.example.com/s/Wi5x…#k=Qm9…” / 「导入 <链接>」
The agent shows a preview card (title, origin, time range, first/last message), then imports it as a native new task at the top of the task list, ready to continue. Imported titles use the [Handoff] prefix so they are easy to distinguish from local tasks. Re-importing the same share returns duplicate instead of silently forking.
Cross-agent
Source and target agents are auto-detected (e.g. importing a codex-exported bundle inside Claude Code) — no manual flags needed. Same-agent → native-fidelity restore with fresh task identity; cross-agent → semantic conversion (visible conversation and tool evidence preserved; model, git branch, timestamps carried over).
Prefer the CLI directly? The Commands section below is what every conversation above runs under the hood.
Commands
| Command | Purpose |
|---|---|
share |
Export a thread/session as .agent-handoff.zip (or an encrypted link) |
preview |
Inspect a bundle (file or URL) without importing |
import |
Dry-run or --execute an import into a target agent |
verify |
Confirm an imported task is queryable in the target agent's state |
Key flags (see agent-handoff with no arguments for the full list):
share:--source codex|claude,--thread <id>|current,--format zip|link,--out FILE,--config FILE,--ttl SECONDS,--include-secretsimport:--target codex|claude,--cwd DIR,--execute,--allow-duplicate,--home DIRverify:--thread ID,--source codex|claude,--cwd DIR
Source/target agents are auto-detected from CODEX_THREAD_ID / CLAUDE_SESSION_ID-style environment variables, defaulting to codex. Homes resolve from CODEX_HOME / CLAUDE_CONFIG_DIR or ~/.codex / ~/.claude.
Environment: AGENT_HANDOFF_RESOLVER (optional static resolver page for relay links); provider credential variables are referenced by the user's own config.json.
How it works
sender receiver
────── ────────
~/.codex/sessions/…/rollout.jsonl ─┐ ┌─> new rollout.jsonl (fresh UUIDv7 id)
~/.codex/state_5.sqlite (threads row)│ zip │ threads row appended (schema-aware)
neutral transcript ←────────┼──────> │ ~/.claude/projects/…/<uuid>.jsonl
images, manifest, checksums ─┘ or │ index entry + ledger record
link (AES-256-GCM, capability in URL fragment)
A bundle is a deterministic zip: manifest.json, the raw source session, a neutral transcript, agent metadata, images, a secret-scan report, per-file SHA-256 checksums, and an AGENT_README.md written for the receiving agent. Full spec: docs/bundle-format.md.
Import is deliberately conservative:
- Checksums first — integrity is verified before anything is written.
- Duplicate ledger — a per-home ledger records every import; re-importing the same share returns
status: duplicateinstead of silently forking. - Append-only writes — backups land next to the originals; on failure the error is reported verbatim.
- Untrusted content stays data — nothing inside a shared session is ever executed or fetched by agent-handoff itself.
Security
- Link payloads are AES-256-GCM encrypted client-side; the server stores ciphertext only and cannot decrypt.
- Export is blocked on high-confidence secret findings unless you pass
--include-secrets. - Bundle checksums make tampering detectable;
previewreportschecksum_status. - Please report vulnerabilities privately — see SECURITY.md.
Development
make test # unit + integration (four-quadrant round trips, link crypto)
make lint # golangci-lint
make build # bin/agent-handoff
With both CLIs installed, run the native compatibility tests withAGENT_HANDOFF_NATIVE_TESTS=1 go test ./internal/integration_test -run TestNative -count=1.
They use temporary homes and a local API fixture, without account credentials or
paid model requests. CODEX_BIN and CLAUDE_BIN can select specific executables.
CI runs tests with -race on Ubuntu/macOS/Windows. Architecture: internal/bundle (container format), internal/{codex,claude} (agent adapters), internal/neutral (cross-agent transcript), internal/link (E2E crypto + compatible hosted endpoints and configured providers), internal/safety (secret scan), internal/cli. Adding another agent also requires native restore, neutral conversion, host detection, and the cross-agent test matrix; see docs/adding-agent.md.
Planned work includes native OpenCode and DeepSeek Harness support, better
setup diagnostics, and richer pre-share review. See the outcome-focused
roadmap.
Contributions welcome — see CONTRIBUTING.md (中文). Apache-2.0 licensed.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi