agent-handoff

agent
Guvenlik Denetimi
Uyari
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.

SUMMARY

Move native coding-agent sessions between Codex and Claude Code as files or end-to-end encrypted links.

README.md

agent-handoff

English | 简体中文

CI
CodeQL
Release
License

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 base
config.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 returned
fallback_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 link encrypts 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

agent-handoff 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 running the agent-handoff Skill

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-secrets
  • import: --target codex|claude, --cwd DIR, --execute, --allow-duplicate, --home DIR
  • verify: --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:

  1. Checksums first — integrity is verified before anything is written.
  2. Duplicate ledger — a per-home ledger records every import; re-importing the same share returns status: duplicate instead of silently forking.
  3. Append-only writes — backups land next to the originals; on failure the error is reported verbatim.
  4. 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; preview reports checksum_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 with
AGENT_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)

Sonuc bulunamadi