session-migrate

Migrate your sessions to any harness.

Move coding agent sessions among Claude Code, Codex, Pi, OpenCode, GitHub Copilot CLI, Antigravity CLI, Cursor Agent, Mistral Vibe, Muse Code, Qwen Code, and Kimi Code.

Install

curl -LsSf https://session-migrate.github.io/install.sh | sh

Or install with uv:

uv tool install session-migrate

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 its native title/name first:

smigrate catalog refresh
smigrate catalog search "oauth refresh" --format claude
smigrate transfer --title "oauth refresh" --from claude --to pi

Search is case-insensitive and every word must match, in any order. It searches
native titles, names, and IDs—not conversation bodies. A few useful patterns:

# “Fix flaky PostgreSQL timeout” also matches this reversed keyword order.
smigrate catalog search "timeout postgres"

# Find a release conversation among archived Codex sessions from this month.
smigrate catalog search "release notes" --format codex \
  --lifecycle archived --since 2026-08-01T00:00:00Z

# Opt in to matching a project directory when the title is vague.
smigrate catalog search "checkout api" --include-paths

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

Choose the route on the project website,
or replace the three bracketed values yourself:

Follow https://session-migrate.github.io/llms.txt to migrate a session from
[SOURCE] to [TARGET]. Session: [UUID OR TITLE]

The linked procedure is sandbox-tested with both Claude Code and Codex. See the
agent workflow and verification.

Compatibility

• Claude Code
• Codex CLI
• Pi
• OpenCode
• GitHub Copilot CLI
• Antigravity CLI
• Mistral Vibe
• Muse Code
• Qwen Code
• Kimi Code
• Cursor Agent (experimental, pinned, text only)

Every listed format can be a source or target: 121 ordered routes, including
same-format portable rewrites. Cursor deliberately transfers only ordered
user/assistant text and is 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

Session data	Result	Notes
User and assistant messages	✓	Preserved in order on every route
Tool calls and results	✓ / partial	Preserved when both adapters support the native shape
Images	✓ / partial	Supported image blocks move; other media is format-dependent
Compaction summaries	✓ / partial	Recreated where the target has a portable equivalent
Readable reasoning	Vibe-only portable rewrite	Vibe keeps its explicit readable field when rewritten to Vibe; other/private/signed traces never move
Session name, ID, and picker entry	Recreated	The target gets a new native identity and resume state
Branches, forks, and subagents	Not flattened	Cataloged separately where detectable; migrate the parent session
Private or signed thinking	No	Model/provider-bound traces are deliberately omitted
Auth, hooks, policies, MCP, and runtime config	No	These remain with the source client

Every omission or transformation is counted in a content-free migration
manifest. The source session is never modified. Cursor intentionally accepts
text only. 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
• Mistral Vibe format
• Muse, Qwen Code, and Kimi Code formats

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 uses real native casts recorded with the same tmux + asciinema
approach as agent-talk. Claude diagnoses a boundary bug in a small project; the
migrated session is reopened in Pi, which applies the proposed patch and runs
the regression test. It shows the source TUI, the migration command, the shared
history, and the continued target session. The website plays those casts
directly in JavaScript; the README animation is rendered from that same scene.
The same source session is also continued in
Claude → Codex.
Watch the larger-text Pi video,
watch the larger-text Codex video,
or reproduce both.
The recorder uses disposable credential copies only to drive the native clients;
the published assets contain only the controlled demo project and omit account
status.

Compare Claude Code → Pi inside the native clients

Before · Claude Code TUI	After · Pi TUI

Compare Claude Code → Codex inside the native clients

Before · Claude Code TUI	After · Codex TUI

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