claude-repath

claude-repath: migrate Claude Code state when folders move

Claude Code stores per-project state under ~/.claude/projects/<encoded-cwd>/, where the folder name encodes the project's absolute path. Moving or renaming that folder silently breaks four layers at once — session history, todos, memory, and worktree wiring all go stale because the absolute path is hardcoded inside each layer. claude-repath is a published CLI that patches all of them in one shot, with automatic backups and rollback support.

When to trigger

Match on any of these user signals, even without the tool name:

• "I moved my project from X to Y and Claude forgot everything"
• "I renamed my repo and my sessions are gone"
• "~/.claude/projects/ still has the old folder name"
• "my todos / history / memory disappeared after I reorganized"
• "Claude Code doesn't know this is the same project"
• "my git worktrees are broken after the move"
• Any ask about migrating, rewiring, or fixing Claude Code state after a folder move

The symptoms are the cue — users usually do not know this tool exists.

Tool availability check

claude-repath is on PyPI. Before suggesting commands, verify the user can run it. Prefer uvx for zero-install trial:

# Zero-install (recommended for trial — no permanent install)
uvx --from claude-repath claude-repath --version

# Global install via pipx (for daily use)
pipx install claude-repath

# Inside an existing venv
pip install claude-repath

Pick the method matching the user's existing toolchain. If they have uv, default to uvx.

Decision tree — which subcommand?

User already physically moved the folder?
├── NO  → claude-repath move OLD NEW          (moves folder + rewires state)
└── YES → claude-repath rewire OLD NEW        (only rewires state)

User wants to inspect what is broken without changing anything?
  → claude-repath doctor PATH                 (read-only diagnostic)

User wants to see every project Claude Code tracks?
  → claude-repath list

Previous migration went wrong?
  → claude-repath list-backups                (find the timestamp)
  → claude-repath rollback TIMESTAMP          (restore)

User does not remember the exact old path, or prefers UI?
  → claude-repath move                        (no args → interactive TUI picker)

Standard migration workflow

Always preview before applying. Destructive operations should never be the first run:

# 1. Diagnose (optional but informative)
claude-repath doctor /absolute/old/path

# 2. Preview — NO changes made
claude-repath move /absolute/old/path /absolute/new/path --dry-run

# 3. Apply for real (auto-backs-up first)
claude-repath move /absolute/old/path /absolute/new/path

Both paths must be absolute. Windows paths with drive letters (D:\dev\myproj) are first-class — the path matcher normalizes \ and / separators automatically, because ~/.claude.json stores keys with forward-slashes even on Windows.

Flags reference

Flag	Applies to	Purpose
--dry-run / -n	move, rewire	Show migration plan without applying
--no-move	move	Skip physical folder move (equivalent to rewire)
--yes / -y	move, rewire, rollback	Skip interactive confirmation
--scope narrow	move, rewire	Default. Touch only main project + its worktrees
--scope broad	move, rewire	Also rewrite cross-project references in unrelated .jsonl files

Use --scope broad only when the old path is referenced by other projects' sessions (rare — e.g., shared paths across monorepo branches). The narrow default is safer.

Safety rules to enforce every time

Before running move or rewire, always:

1. Tell the user to close all Claude Code sessions. The tool refuses to run if any claude process is holding state files, but warning upfront saves a retry.
2. Run --dry-run first unless the user has already seen the plan in the same session.
3. Mention automatic backups — they are saved to ~/.claude/.repath-backups/<timestamp>/ and can be restored with claude-repath rollback <timestamp>. This lowers user anxiety.

If the user seems nervous, suggest doctor first — it makes zero changes and shows exactly what state exists.

Platform notes

All three platforms work identically, with state under ~/.claude/:

OS	Shell hints
Windows	Works in Git Bash, PowerShell, and cmd. D:\... and D:/... both accepted.
macOS	Standard ~/.claude/ path.
Linux	Standard ~/.claude/ path.

Claude Code Desktop stores additional state in Chromium Local Storage/leveldb. claude-repath doctor reports whether this exists on the user's machine but does not auto-migrate it (out of scope — Anthropic's leveldb schema is private and shifts between Desktop releases). If the user relies on Desktop, advise them to open the new folder via Desktop's File menu after migration to re-register it.

What gets migrated

Six layers, automatically:

1. Physical project folder (the mv itself — skippable with --no-move)
2. ~/.claude/projects/<encoded>/ directory name (renamed to match new path)
3. Every .jsonl session file's inline "cwd" field
4. ~/.claude.json — the projects key
5. Worktree-derived project folders (auto-discovered by name prefix)
6. ~/.claude/git-worktrees.json when present

Not migrated (out of scope as of current version):

• Chromium Local Storage for Claude Code Desktop (diagnosed only)

Common user phrasings → exact command

User says...	Run
"I moved proj from A to B"	claude-repath move A B --dry-run, confirm, then apply
"I already moved it manually, just fix Claude"	claude-repath rewire A B --dry-run, then apply
"what does Claude think is wrong with this project?"	claude-repath doctor /path
"which projects does Claude know about?"	claude-repath list
"undo the last migration"	claude-repath list-backups → pick latest → rollback TS
"my worktrees are broken too"	Same move — worktrees auto-discovered inside the main migration
"I forget the exact old path"	claude-repath move (no args → interactive TUI picker)
"does this work on Windows?"	Yes, first-class — drive letters and backslashes fully supported

Edge cases

• Path case mismatches on Windows (D:\Dev\X vs d:\dev\x): Windows filesystem is case-insensitive but ~/.claude.json stores the literal string. Use the exact case the user originally registered with if known; otherwise doctor will show which case is currently stored.
• Old path no longer exists but state remains: use rewire (not move), which only touches state files.
• Target path already exists: move will refuse — tell the user to pick a different target or move the existing folder out of the way first.
• Multiple worktrees under one project: handled automatically by --scope narrow. No special flags needed.
• Python venv / node_modules will break after move (v0.4.2+): move emits a non-blocking warning listing any .venv / venv / node_modules in the source. The physical move still succeeds, but the user must rebuild with their package manager (uv sync / pip install -e . / npm ci / etc.) — claude-repath cannot reliably auto-rebuild across every toolchain. Tell the user before they run move so they can plan the rebuild step.