Agent Capsule turns a complete Codex / Claude Code conversation into a shareable link.
You only need to send the link to someone else. They can import that conversation into their own local Codex or Claude Code, get a native thread/session like the one on your machine, with the full context, and continue working directly inside the conversation.
After they hand the link to their own Codex or Claude Code, the agent can import the session into the local native UI/UX and continue from there.
The CLI command is capsule.
The full flow is export → browser preview → import → continue in a native task. Click any image to view it full size.
| Export an encrypted share link | Preview and inspect it in the browser |
|---|---|
 |
 |
| Import it as a new Codex task | Continue with the restored context |
|---|---|
 |
 |
Sometimes you want to hand off the whole agent workspace: the conversation, the investigation path, tool use, working context, and unfinished next steps.
Agent Capsule packages that session into a capsule that can be imported in one step. The receiver gets more than a record of what you talked about; they can restore it into their own agent and keep working.
Agent Capsule currently supports Codex and Claude Code export/import, including cross-agent artifact imports through share links and zip capsules.
It also supports controlled Codex profile migration between Macs: selected projects and their native threads, user configuration, skills, memories, and automations can be moved while preserving the target Mac's authentication and device identity.
Codex image uploads referenced by a session are preserved. Agent Capsule does not package arbitrary non-image files yet.
Same-agent imports create a new native session/thread. Cross-agent imports preserve the visible transcript, tool evidence, working context, and a raw source sidecar for later inspection. They do not migrate provider credentials, login state, cloud state, filesystem checkpoints, or private encrypted agent state.
Install capsule:
curl -fsSL https://raw.githubusercontent.com/z2z23n0/agent-capsule/main/install.sh | shIf your shell cannot find capsule after installation, add ~/.local/bin to
your PATH.
Agents can optionally install the Agent Capsule skill from
skills/agent-capsule. The skill teaches the
agent when to install the CLI, how to export or share a session, how to import
after inspection and explicit approval, and how to verify restored sessions.
Capsule files and links do not depend on the skill. They include agent-facing bootstrap instructions so a receiving agent can understand the workflow, install the CLI, inspect the capsule, import it into the local native Codex / Claude Code UI/UX, and verify the restored thread/session even without a preinstalled skill.
Export the current Codex thread as an encrypted share link:
capsule export --source codex --thread currentExport the current Claude Code session instead:
capsule export --source claude --thread currentThe default export format is link. A share link looks like this:
https://<worker-host>/s/<share-id>#k=<base64url-key>
The capsule is encrypted with AES-256-GCM before upload. The service stores the ciphertext and manifest; the decryption key lives in the URL fragment and is not sent to the server by normal browser requests.
The browser page shows a locally decrypted preview and includes agent-friendly CLI install, inspect, and import commands.
For sessions with images, the browser preview shows image thumbnails when they fit the preview size limit. Large image-heavy sessions still import from the complete encrypted capsule.
If link upload fails because the service is unavailable or over quota, Agent
Capsule writes a local .capsule.zip fallback and returns
status: fallback_zip.
Export the current session as a local zip capsule only when you explicitly need a file:
capsule export --source codex --thread current --format zip --name "handoff topic"
capsule export --source claude --thread current --format zip --name "handoff topic"Inspect the capsule before importing:
capsule inspect handoff-topic.capsule.zipWrite the imported thread/session into local agent history:
capsule import handoff-topic.capsule.zip --target codex --target-cwd . --execute
capsule import handoff-topic.capsule.zip --target claude --target-cwd . --executeVerify the imported thread/session:
capsule verify --target codex --home ~/.codex --thread <new-thread-id> --target-cwd .
capsule verify --target claude --home ~/.claude --thread <new-session-id> --target-cwd .Profile migration is separate from session handoff. It preserves selected native thread ids and uses controlled overwrite semantics for a newly installed target Codex. Project working trees are recreated with Git; uncommitted and untracked files are not copied.
capsule profile export \
--target-home /Users/<target-user>/.codex \
--target-workspace /Users/<target-user>/workspace \
--project /path/to/project-a \
--git-bundle-fallback \
--out ~/.codex/profile-migrations/<migration-id>
capsule profile serve ~/.codex/profile-migrations/<migration-id> --listen :8765On the target Mac:
capsule profile fetch <tokenized-source-url> --out ~/.codex/profile-migrations/<migration-id>
capsule profile clone ~/.codex/profile-migrations/<migration-id> --execute
capsule profile import ~/.codex/profile-migrations/<migration-id> --home ~/.codex
capsule profile schedule-import ~/.codex/profile-migrations/<migration-id> --home ~/.codex --executeAfter Codex reopens:
capsule profile verify ~/.codex/profile-migrations/<migration-id> --home ~/.codex
capsule profile unschedule ~/.codex/profile-migrations/<migration-id> --home ~/.codex --executeThe one-shot LaunchAgent uses KeepAlive=false, removes its plist after the
attempt, and writes import-status.json. The profile allowlist excludes auth,
provider tokens, installation/device ids, cookies, Keychain data, managed
plugins, caches, logs, worktrees, and skills/.system.
For link sharing, Agent Capsule encrypts the capsule locally before upload. The
hosted service, Worker, R2 bucket, or S3-compatible bucket receives only the
encrypted capsule bytes and encrypted preview payload. Without the #k=...
fragment key, those services cannot decrypt the conversation content.
The decryption key is generated on the sender's machine and placed only in the URL fragment. Normal browser requests do not send URL fragments to the server, and the CLI importer removes the fragment before fetching the manifest and ciphertext.
The service can still see and store link metadata, including thread id, thread title, creation and expiry timestamps, ciphertext size, ciphertext hash, bundle URL, and operational request metadata.
The hosted preview page decrypts the preview in the browser with WebCrypto. If you do not trust the page host to serve honest JavaScript, use the CLI import path instead; it fetches the manifest and ciphertext directly and decrypts locally.
capsule export defaults to --service official and uses the hosted endpoint
https://agent-capsule.z2z23n0.workers.dev. In local development, override it
with CAPSULE_OFFICIAL_ENDPOINT:
export CAPSULE_OFFICIAL_ENDPOINT=https://...
capsule export --thread currentFor a self-hosted Cloudflare Worker:
capsule export --thread current \
--service worker \
--endpoint https://example.workers.devFor S3-compatible storage such as R2:
capsule export --thread current --service s3 \
--s3-endpoint https://<account>.r2.cloudflarestorage.com \
--s3-bucket agent-capsule \
--s3-prefix shares \
--s3-access-key-id "$CAPSULE_S3_ACCESS_KEY_ID" \
--s3-secret-access-key "$CAPSULE_S3_SECRET_ACCESS_KEY" \
--s3-public-base-url https://pub.example/capsulesThe Worker template lives in deploy/cloudflare-worker/.
cd deploy/cloudflare-worker
npm install
cp wrangler.toml.example wrangler.toml
npm run devBefore deploying, bind:
- a private R2 bucket as
CAPSULE_BUCKET - the
BudgetGateDurable Object - optional upload auth with
CAPSULE_WORKER_TOKEN
Deploy with:
npm run deployDo not commit real wrangler.toml files or secrets.
A .capsule.zip contains:
manifest.json
AGENT_README.md
codex/session.jsonl # Codex source capsules
codex/index-entry.json # Codex source capsules
codex/thread-row.json # Codex source capsules
codex/assets/images.json # optional Codex images
codex/assets/images/<sha256>.<ext> # optional Codex images
claude/session.jsonl # Claude source capsules
claude/session-index-entry.json # optional Claude index entry
agent/neutral.json
agent/restore.md
safety/scan.json
checksums.json
manifest.json records source_agent, target support, payload inventory, and
the lossless level. Legacy Codex capsules without those fields still import as
Codex capsules.
Image asset files are present only when the Codex session references local
images. During import, those images are written under
$CODEX_HOME/agent-capsule-assets/<new-thread-id>/images/, and the imported
session rewrites local image paths to that new location.
Cross-agent imports also write a raw source sidecar under the target agent home,
for example $CODEX_HOME/agent-capsule-sources/<new-thread-id>/ or
$CLAUDE_CONFIG_DIR/agent-capsule-sources/<new-session-id>/.
The root AGENT_README.md exists so a receiving agent can inspect an ordinary
zip file and understand how to restore it before installing anything.
Capsules can contain sensitive conversation content, local paths, tool output, prompts, images or screenshots, and accidental secrets.
Agent Capsule runs a best-effort secret scan during export and share. If it finds high-confidence secrets, export fails unless you explicitly pass:
--unsafe-include-secretsOnly use that flag when you have reviewed the capsule and intentionally want to share it.
The secret scan covers session text. It does not OCR images or scan image pixels, so review screenshots and uploaded images before sharing.
Link sharing uploads encrypted bytes, but anyone with the full URL including
#k=... can decrypt the capsule.
Run the Go tests:
go test ./internal/capsule ./internal/codexRun Worker checks:
npm --prefix deploy/cloudflare-worker test
npm --prefix deploy/cloudflare-worker run checkApache-2.0. See LICENSE.