claude-migrator

A CLI + GUI tool to organize, back up, and migrate the local data behind Claude Code and Claude Cowork — with planned cross-platform (Windows ⇄ macOS) conversion.

⚠️ This tool reads Claude's undocumented internal file layout. It is deliberately conservative: it never reads or copies credentials or runtimes, and every destructive action supports a dry run. Formats may change between Claude versions.

What it touches

Data	Location	Action
Conversation transcripts	~/.claude/projects/<encoded-cwd>/<id>.jsonl	back up / migrate
Memory	~/.claude/projects/.../memory/*.md	back up / migrate
Settings	~/.claude/settings.json	back up
Cowork session metadata	<app-dir>/claude-code-sessions/.../local_*.json	back up / migrate

<app-dir> is %APPDATA%\Claude on Windows and ~/Library/Application Support/Claude on macOS. ~/.claude is shared.

Never touched: .credentials.json, the OAuth token in config.json (machine-bound — re-login on the new machine), and the claude-code/ / claude-code-vm/ runtimes (hundreds of MB, auto-refetched).

Status

• Phase 1 (done): locate, scan, backup, restore (same-OS round-trip).
• Phase 3 (done): cross-platform path remapping. A backup made on one OS restores onto the other via --map rules: project folder names are re-encoded and Cowork metadata paths (cwd / originCwd / planPath) are rewritten. Transcript bodies are copied as-is (they are history; the effective working directory comes from the rewritten Cowork metadata).
• Phase 2 (done): prune — select sessions by orphan / archived / age / size and remove them. Dry-run by default; deletion needs --yes.
• GUI (done): a Tauri desktop app over the same core — scan the session list, back up, preview/run prune, and restore (incl. cross-OS) from a window.

Cross-OS restore

# Restoring a Windows backup onto macOS:
claude-migrator restore --from ./claude-backup-... \
  --map "D:\GitHub=/Users/you/GitHub" \
  --map "C:\Users\you=/Users/you" \
  --dry-run

A folder with no matching rule is reported and skipped rather than restored to a wrong location.

CLI

claude-migrator locate              # show resolved data locations
claude-migrator scan                # list sessions, transcripts, orphans
claude-migrator scan --json         # machine-readable report
claude-migrator backup --dry-run    # plan a backup without writing
claude-migrator backup --dest ./backups
claude-migrator restore --from ./backups/claude-backup-... --dry-run
claude-migrator restore --from ./backups/claude-backup-... --overwrite
claude-migrator prune --orphans                 # report removable orphans
claude-migrator prune --larger-than 5MB --older-than 90
claude-migrator prune --archived --yes          # actually delete

Build

cargo build
cargo test
cargo run -p claude-migrator -- scan

GUI

A Tauri desktop app (Windows/macOS) lives in gui/. It wraps the same cmcore library — scan the session list, back up, and preview/run prune from a window.

cargo run -p claude-migrator-gui

Prerequisites: a Rust toolchain and a system WebView (WebView2 on Windows, WKWebView on macOS). No Node/bundler is required — the frontend is static and uses Tauri's global API.

Building installers

The GUI is bundled with Tauri. To produce a platform installer (.msi/.exe on Windows, .dmg/.app on macOS):

cargo install tauri-cli --version "^2.0" --locked   # one time
cargo tauri build                                   # from gui/src-tauri

On Windows this produces both an .msi and an NSIS -setup.exe under target/release/bundle/. Tauri downloads WiX/NSIS automatically on first run.

On macOS this produces a .app and a .dmg under target/release/bundle/. The bundle is not code-signed or notarized, so Gatekeeper blocks it on first launch. To open it anyway, either right-click the app and choose Open, or clear the quarantine attribute:

xattr -dr com.apple.quarantine "/Applications/claude-migrator.app"

License

MIT