README
¶
codex-claude-transfer
Move local Codex and Claude Code sessions between machines.
The command is cct.
Unofficial. Not affiliated with or endorsed by OpenAI or Anthropic. These tools' internals can change at any time and break this tool. Use at your own risk. See the Disclaimer.
The problem it solves
Codex and Claude Code keep valuable project context in local session files. That is good for privacy, but painful when you switch machines, rebuild a laptop, or want to continue a thread in the other agent.
cct turns that local context into a simple handoff:
Machine A: cct export --project . -> project.codexbundle
copy it however you trust
Machine B: cct import ./project.codexbundle
No cloud account, hosted sync service, or background process by default. You move
one .codexbundle over a channel you trust, then import it after checksum
verification. The agents' indexes are left alone and re-scan the session files
themselves.
It works for Codex, Claude Code, and cross-agent handoff. The same flow is
available as a CLI, a terminal wizard (cct ui), and a local browser app
(cct app).
Demo
Export on one machine, then import or incrementally sync onto the other:
The optional local desktop UI uses the same engine:
More clips in demo/: LAN sync,
full-text search,
secret scan & redact,
Markdown export,
repair-times,
cross-agent handoff,
encryption,
conflict resolution & cwd remap,
export filters,
git handoff, the
interactive cct ui wizard, and
reading compressed .jsonl.zst sessions.
All recordings use throwaway demo sessions, never a real ~/.codex or
~/.claude.
Install
# From source (Go 1.23+)
go install github.com/ahmojo/codex-claude-transfer/cmd/cct@latest
Or download a prebuilt binary from Releases, or build from a clone:
git clone https://github.com/ahmojo/codex-claude-transfer.git
cd codex-claude-transfer && go build -o cct ./cmd/cct
Package manifests for Homebrew and Scoop live in
packaging/.
30-second use
cct doctor
cct export --project .
# copy project.codexbundle to the other machine
cct import ./project.codexbundle --dry-run
cct import ./project.codexbundle
Use --tool claude to export Claude Code sessions. Use import --to claude or
import --to codex to translate a session into the other agent. After importing,
restart the agent so it re-scans the files.
Docs
- Usage guide: quickstart, desktop app, common workflows, LAN sync, and optional external tools.
- Command reference: commands and flags.
- Internals: how bundles work, safety model, limitations, and versioning.
- Safety notes: detailed privacy and write-safety model.
- Roadmap: shipped features, never-planned features, and project notes.
Contributing
PRs welcome. Keep changes small, preserve the no-cloud / no-SQLite-writes
principles, test with fake Codex homes only, and run the documented Go checks.
See CONTRIBUTING.md.
Disclaimer
Unofficial and not affiliated with or endorsed by OpenAI or Anthropic. It
works against Codex's and Claude Code's local files based on their behavior at a
point in time, which may change and break it. .codexbundle files can contain
prompts, code, command output, paths, and secrets; treat them like sensitive local
history and encrypt them over untrusted channels. Provided "as is", without
warranty. Use at your own risk.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
cct
command
Command cct is an unofficial CLI for local Codex session portability: export sessions on one device, move the bundle manually, import on another.
|
Command cct is an unofficial CLI for local Codex session portability: export sessions on one device, move the bundle manually, import on another. |
|
internal
|
|
|
agent
Package agent names the coding agents whose local sessions cct can transfer.
|
Package agent names the coding agents whose local sessions cct can transfer. |
|
bundle
Package bundle creates and (later) reads .codexbundle archives: a ZIP containing a manifest, a checksum map, and the copied Codex rollout files.
|
Package bundle creates and (later) reads .codexbundle archives: a ZIP containing a manifest, a checksum map, and the copied Codex rollout files. |
|
cctpaths
Package cctpaths resolves cct's own on-disk locations, kept deliberately separate from any coding-agent home.
|
Package cctpaths resolves cct's own on-disk locations, kept deliberately separate from any coding-agent home. |
|
claudehome
Package claudehome resolves the location of the local Claude Code home directory (~/.claude) and the per-project session store inside it.
|
Package claudehome resolves the location of the local Claude Code home directory (~/.claude) and the per-project session store inside it. |
|
claudesessions
Package claudesessions discovers and defensively parses Claude Code session transcripts under ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl.
|
Package claudesessions discovers and defensively parses Claude Code session transcripts under ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl. |
|
cli
Package cli implements the cct command-line interface.
|
Package cli implements the cct command-line interface. |
|
codexhome
Package codexhome resolves the location of the local Codex home directory (~/.codex) and the session storage directories inside it.
|
Package codexhome resolves the location of the local Codex home directory (~/.codex) and the session storage directories inside it. |
|
config
Package config stores a few user defaults so power users stop retyping the same flags.
|
Package config stores a few user defaults so power users stop retyping the same flags. |
|
crypt
Package crypt provides optional bundle encryption by shelling out to the `age` CLI (https://github.com/FiloSottile/age).
|
Package crypt provides optional bundle encryption by shelling out to the `age` CLI (https://github.com/FiloSottile/age). |
|
doctor
Package doctor performs read-only health checks on the local Codex setup so users can confirm cct can see their sessions before exporting or importing.
|
Package doctor performs read-only health checks on the local Codex setup so users can confirm cct can see their sessions before exporting or importing. |
|
git
Package git provides best-effort discovery of git metadata for a project directory.
|
Package git provides best-effort discovery of git metadata for a project directory. |
|
handoff
Package handoff translates a coding-agent session from one agent's on-disk format into another's, via a small neutral intermediate representation (the AgentSession IR).
|
Package handoff translates a coding-agent session from one agent's on-disk format into another's, via a small neutral intermediate representation (the AgentSession IR). |
|
lansync
Package lansync implements cct's experimental device-to-device session sync over a local network.
|
Package lansync implements cct's experimental device-to-device session sync over a local network. |
|
meta
Package meta stores cct's own per-session annotations — a friendly name and a set of tags — keyed by the session's thread id.
|
Package meta stores cct's own per-session annotations — a friendly name and a set of tags — keyed by the session's thread id. |
|
repair
Package repair fixes the modification time of session files that were imported with a "wrong" (import-time) mtime, which makes a coding agent's index see them as newer than indexed and re-parse them on every open (Codex read-repair), a multi-second delay each time.
|
Package repair fixes the modification time of session files that were imported with a "wrong" (import-time) mtime, which makes a coding agent's index see them as newer than indexed and re-parse them on every open (Codex read-repair), a multi-second delay each time. |
|
safety
Package safety provides path validation and atomic file writes used when importing bundles.
|
Package safety provides path validation and atomic file writes used when importing bundles. |
|
search
Package search provides full-text search over local session transcripts.
|
Package search provides full-text search over local session transcripts. |
|
secrets
Package secrets detects (and optionally redacts) likely credentials in session content — API keys, tokens, private keys — so you can check a session before sharing or syncing it.
|
Package secrets detects (and optionally redacts) likely credentials in session content — API keys, tokens, private keys — so you can check a session before sharing or syncing it. |
|
sessions
Package sessions discovers and defensively parses Codex rollout files.
|
Package sessions discovers and defensively parses Codex rollout files. |
|
stats
Package stats aggregates a set of discovered sessions into a small summary — how many, where (by project), and when (by day) — for `cct stats`.
|
Package stats aggregates a set of discovered sessions into a small summary — how many, where (by project), and when (by day) — for `cct stats`. |
|
webui
Package webui serves cct's local desktop GUI: a small single-page app served over a loopback-only HTTP server, backed by the same core packages as the CLI.
|
Package webui serves cct's local desktop GUI: a small single-page app served over a loopback-only HTTP server, backed by the same core packages as the CLI. |
|
zstdcli
Package zstdcli recovers metadata from zstd-compressed Codex rollout files by shelling out to the `zstd` CLI (https://github.com/facebook/zstd).
|
Package zstdcli recovers metadata from zstd-compressed Codex rollout files by shelling out to the `zstd` CLI (https://github.com/facebook/zstd). |