agent-migrator
A CLI tool for migrating conversation history between AI coding tools.
Supported Coding Agents
- Claude Code (Anthropic)
- Codex (OpenAI)
- Gemini CLI (Google)
- Cursor
All pairs are supported bidirectionally.
Setup
Requires uv.
Install globally (recommended):
uv tool install agent-migrator
Or run without installing:
uvx agent-migrator
Usage
Interactive
Run from inside a project directory:
agent-migrator
The CLI walks you through:
- Tool selection — choose source and destination.
- Conversation selection — pick conversations to migrate, sorted most-recent-first.
- Migration progress — each conversation is processed in sequence;
Ctrl+Ccancels and rolls back. - Summary — a results table shows successes and errors.
Cursor: the project path must be a directory that has been opened as a workspace in Cursor at least once.
Non-interactive
Two subcommands expose the same engine for scripting and agentic use. Both accept --dir <path> (defaults to cwd) and print JSON to stdout; errors go to stderr as {"error": "..."} with exit 1.
List conversations:
agent-migrator list --from claude-code --dir /path/to/project
[{"id": "63ec7bb1-...", "name": "pwa-capabilities-demo", "updated_at": "2026-05-21T23:23:00", ...}]
Migrate a conversation:
agent-migrator move --from claude-code --to codex --id 63ec7bb1-... --dir /path/to/project
[{"source_id": "63ec7bb1-...", "destination_id": "019e51f7-...", "name": "pwa-capabilities-demo"}]
Omit --id to migrate all conversations for the project. Run agent-migrator list --help or agent-migrator move --help for full options.
What gets migrated
All pairs support:
| Feature | Status |
|---|---|
| Text messages (user and assistant) | ✓ |
| Tool calls (Read, Write, Edit, Bash, Glob, and equivalents) | ✓ |
| Plan (presented natively in the destination tool's plan UI) | ✓ |
(Any) → Cursor is the one exception: plans are migrated as context documents but are not surfaced in Cursor's native plan mode UI.
(Any) → Cursor also requires a server upload to Cursor's ConvertOALToNAL endpoint to make all models available. If that fails (e.g. not logged in), the CLI offers a local fallback that provides full context but restricts model selection to Anthropic models.
How it works
Conversations are read into a tool-agnostic normalized format (TextMessage and ToolCallMessage turns) and written out in the destination format. Each tool is implemented as a AgentAdapter subclass in agent_migrator/agents/. This decouples all source/destination pairs — adding a new tool requires only a new adapter; all existing migration paths continue to work unchanged.
Extensibility
To add support for a new coding agent, implement the AgentAdapter interface in agent_migrator/agents/ and register it in cli.py:
class MyAgentAdapter(AgentAdapter):
name = "My Agent"
tool_id = "myagent"
def is_available(self) -> bool: ...
def list_conversations(self, project_path: Path) -> list[ConversationInfo]: ...
def read_conversation(self, conv_id: str, project_path: Path) -> Conversation: ...
def write_conversation(self, conv: Conversation, project_path: Path, *, use_local_backend: bool = False) -> str: ...
def delete_conversation(self, conv_id: str, project_path: Path) -> None: ...
Storage locations
| Tool | Location |
|---|---|
| Claude Code | ~/.claude/projects/<encoded-path>/<session>.jsonl |
| Codex | ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl |
| Gemini CLI | ~/.gemini/tmp/<project-slug>/chats/session-<timestamp>-<id>.jsonl |
| Cursor | %APPDATA%/Cursor/User/globalStorage/state.vscdb (SQLite) |
Metadata
Release files for agent-migrator 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_migrator-0.1.1.tar.gz | 73.7 kB | Without provenance | Details for agent_migrator-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_migrator-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agent_migrator-0.1.1-py3-none-any.whl |
Total release size: 139.0 kB
Release files / agent_migrator-0.1.1.tar.gz
| Download URL | agent_migrator-0.1.1.tar.gz |
|---|---|
| Size | 73.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
70bf7221a97f0489fa5f7698b2dca942975e94afc352fcf787554253f48bed42
|
|
BLAKE2b-256 checksum How to use checksums |
566a370396892d297e5aff89d06360c04d7a483898a3f44d6f5e4e293af8cbad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / agent_migrator-0.1.1-py3-none-any.whl
| Download URL | agent_migrator-0.1.1-py3-none-any.whl |
|---|---|
| Size | 65.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac9fa5bc5980057bde3387b2b3ee3730ac3456901df13fe9f001dfc8d8778fc8
|
|
BLAKE2b-256 checksum How to use checksums |
111646cb1eab6d3b407465b5c03eb2f76ec58c771794dd17288f13e5312c3915
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for agent-migrator 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.