claude-repath

claude-repath

Rewire Claude Code's local state when your project folder moves.

When you move or rename a project directory, Claude Code loses track of its sessions, memory, todos, and worktrees — because the absolute path is hardcoded in four different places. claude-repath patches all of them in one shot.

---

Why this exists

Claude Code stores per-project state under ~/.claude/projects/<encoded-cwd>/, where the folder name is derived from the project's absolute path. Moving the project folder breaks:

1. ~/.claude/projects/<encoded>/ — the encoded folder name no longer matches
2. ~/.claude/projects/<encoded>/*.jsonl — each session file has "cwd" hardcoded inside
3. ~/.claude.json — the projects key is indexed by absolute path
4. Git worktree sub-projects — each has its own encoded folder AND internal cwd fields

Anthropic has no official migration command (as of 2026-04), and existing community tools cover at most 6 of the needed layers. claude-repath aims to handle all of them, with special care for Windows paths and worktrees.

---

Install

Pick whichever matches your workflow — they're all equivalent:

Method	Command	When to use
uvx (zero-install)	uvx --from claude-repath claude-repath <subcommand>	Try or use without installing — uv caches it transparently
pipx (global CLI)	pipx install claude-repath	Daily use, isolated from system Python
pip (in a venv)	pip install claude-repath	Already inside a project venv

💡 First time? Run uvx --from claude-repath claude-repath --version — no commitment, just see if it works on your box. Upgrade later with uvx --refresh ….

---

Install as a Claude Code plugin (optional)

In addition to the CLI, this repo ships a Claude Code plugin so your AI assistant can recognize symptoms — "I moved my project and Claude forgot everything", "sessions gone after rename", "~/.claude/projects has the old folder name" — and suggest claude-repath automatically, without you having to remember the tool's name.

From inside Claude Code:

/plugin marketplace add xPeiPeix/claude-repath
/plugin install claude-repath@claude-repath-marketplace

Or, from any terminal (uses the open skills.sh ecosystem — Claude Code, Cursor, Codex, and ~40 more agents):

npx skills add xPeiPeix/claude-repath

The plugin only ships a skill (a ~200-line guidance document). It does not bundle the CLI — you still install that via uvx/pipx/pip above, or let the skill guide Claude to run it via uvx on first use.

---

Quick start

# INTERACTIVE mode — pick from a list, no path typing needed
claude-repath move

# Explicit mode — preview changes first (ALWAYS recommended)
claude-repath move D:\dev_code\time-blocks D:\dev_code\Life\time-blocks --dry-run

# Actually perform the migration (auto-backs-up first)
claude-repath move D:\dev_code\time-blocks D:\dev_code\Life\time-blocks

# Broader scan — also rewrite cross-project references (use with care)
claude-repath move <old> <new> --scope broad

# Override pre-flight lock check (still bounded by OS-level runtime locks
# — see --force note in Safety section). v0.4.1+ uses atomic os.rename, so
# a runtime lock now fails loudly with the source directory intact; previously
# shutil.move could half-succeed on Windows.
claude-repath move <old> <new> --force

# If you already moved the folder manually, just rewire state
claude-repath rewire D:\dev_code\time-blocks D:\dev_code\Life\time-blocks

# Health check a project's Claude Code state
claude-repath doctor D:\dev_code\time-blocks

# List all projects Claude Code knows about
claude-repath list

# Roll back a previous migration
claude-repath rollback 20260419-155331

---

What gets migrated

Legend: ✅ fully handled · ⚠️ physically moved but needs manual rebuild · 🔍 diagnosed but not migrated