agent-migrator

# agent-migrator

A CLI tool for migrating conversation history between AI coding tools. Supports bidirectional migration between **Cursor** and **Claude Code**, with an interactive CLI for selecting conversations and tracking progress.

---

## Setup

Requires [uv](https://docs.astral.sh/uv/).

**Install globally** (recommended — makes `agent-migrator` available on your PATH):

```bash
uv tool install agent-migrator
```

**Or run without installing:**

```bash
uvx agent-migrator
```

---

## Usage

Run from inside a project directory:

```bash
agent-migrator
```

Or pass a path explicitly:

```bash
agent-migrator /path/to/project
```

The CLI walks you through:

1. **Tool selection** — choose which tool to migrate from and which to migrate to.
2. **Conversation selection** — pick individual conversations or migrate all of them. Conversations are sorted most-recent-first and show the name, date, and size.
3. **Migration progress** — each conversation is processed in sequence. Press `Ctrl+C` at any time to cancel; any in-progress conversation is rolled back.
4. **Summary** — a results table shows what succeeded and any errors.

**Note:** For Cursor, the project path must be a directory that has been opened as a workspace in Cursor at least once. Cursor tracks conversations per workspace, so use the exact subdirectory you opened in Cursor (e.g. `my-repo/feature-branch`), not a parent directory.

---

## What gets migrated

### Cursor → Claude Code

| Feature | Status |
|---|---|
| Text messages (user and assistant) | ✓ |
| Tool calls (Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch) | ✓ |
| Bash mode commands and output | ✓ |
| Plan (most recent plan associated with the conversation) | ✓ |

### Claude Code → Cursor

| Feature | Status |
|---|---|
| Text messages (user and assistant) | ✓ |
| Tool calls (Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, MCP) | ✓ |
| Bash mode commands and output | ✓ |
| Plan | Partial — the plan document is migrated and