↝ session-migrate

Carry the conversation forward.

Move local coding-agent sessions between Claude Code, Codex, Pi, OpenCode, GitHub Copilot CLI, Antigravity CLI, and Cursor Agent.

Install

uv tool install session-migrate

No uv? Use the standalone installer:

curl -LsSf https://raw.githubusercontent.com/xhluca/session-migrate/main/install.sh | sh

pipx install session-migrate works too. Python 3.11+ and Linux are currently supported. The full command is session-migrate; smigrate is the shorthand. Already installed? Run uv tool upgrade session-migrate.

Quick start

Inspect any native transcript without printing its conversation:

smigrate inspect ~/.claude/projects/-work/SESSION.jsonl

Move a Claude session into Codex and resume it from the same project directory:

smigrate transfer SESSION_UUID --from claude --to codex --cwd "$PWD"
codex resume NEW_SESSION_UUID

Or find an older session by title first:

smigrate catalog refresh
smigrate catalog search "authentication refactor"
smigrate transfer --catalog-id RESULT_ID --to pi

catalog refresh is exhaustive inside the default, environment-selected, registered, and explicitly discovered roots. It does not crawl your whole disk.

Give it to your coding agent

Replace the bracketed values and paste this directly into Claude Code, Codex, or another coding agent with shell access:

Use session-migrate from https://github.com/xhluca/session-migrate to migrate my local coding-agent conversation. Read the current README.md and docs/cli-reference.md in that repository, install the released tool in an isolated way, refresh its catalog across the available default roots, and locate session [SESSION UUID OR DISTINCTIVE TITLE]. Show only content-free metadata; if the search is ambiguous, stop and ask me which result to use. Migrate it from [SOURCE AGENT] to [TARGET AGENT] now. Before the dry-run, generate one fresh target UUID yourself and pass it with --session-id to both the dry-run and the apply command; do not let either command generate a different UUID. Stop if their session IDs or resolved target paths differ. Review and summarize every warning or counted transformation before applying, then give me the exact native resume command and required working directory. Never print transcript bodies or credentials, never overwrite an existing target, and do not modify the source session.

This exact instruction is sandbox-tested with both Claude Code and Codex. See the agent workflow and verification.

Compatibility

✓ means a native portable rewrite. T means ordered user/assistant text only. Cursor support is experimental and pinned to one exact Linux build; it is not a vendor-supported import API. Same-format migration creates a new independent session—it is not a byte-for-byte clone or a live sync.

What survives

• User and assistant messages, in order, on every route
• Tool calls/results, supported images, and portable summaries where the target supports them
• A new native identity, target discovery/picker metadata, and resume state

Anything target-specific is counted in a content-free migration manifest. The source session is never modified. Cursor intentionally accepts text only; private/model-bound thinking is not migrated. See Pi thinking traces.

How it works

native session → validated event timeline → native target → resume

Each reader projects a versioned native transcript into a small ordered model. Each writer then emits only structures verified against the target CLI. This is session migration, not text export: the target receives a discoverable, resumable native session.

More

• CLI reference
• Coding-agent instruction
• Session catalog
• Compatibility details
• Troubleshooting
• Format research and validation
• Data handling and architecture
• Antigravity format
• Experimental Cursor format

The Antigravity and Cursor adapters are clean-room, unofficial, and version-pinned. Their independently observed formats are published separately: Antigravity research and Cursor research.

The demo above shows the native Claude conversation before migration, runs the real conversion and inspection commands, then shows the equivalent native Codex history. Conversation playback is accelerated to 2.5×; terminal usage remains at 1×. It uses synthetic, credential-free fixtures. Watch the MP4 or reproduce it.

Compare the native session before and after

Claude Code source	Codex target

Contributing

git clone https://github.com/xhluca/session-migrate.git
cd session-migrate
uv sync --dev
uv run pytest

See the development guide before changing a native adapter. New formats need sanitized fixtures and a real native-resume oracle.

License

MIT