claudepath

Move or rename Claude Code projects without losing session history, memory, and context.

The Problem

When you move or rename a project directory, Claude Code loses all your session history because sessions are keyed to the absolute path of your project. You end up with orphaned data in ~/.claude/projects/ and a fresh start.

claudepath fixes this by updating all path references in Claude Code's data files after a move.

Installation

# With pipx (recommended — isolated install)
pipx install claudepath

# With pip
pip install claudepath

Homebrew (macOS/Linux)

brew tap Mahiler1909/tools
brew install claudepath

Usage

Move a project

Moves the directory on disk and updates all Claude Code references:

claudepath mv ~/old/location/my-project ~/new/location/my-project

Remap after a manual move

If you already moved the directory yourself, just update Claude's references:

claudepath remap ~/old/location/my-project ~/new/location/my-project

Preview changes (dry run)

See exactly what would change without modifying anything:

claudepath mv ~/old/path ~/new/path --dry-run

List tracked projects

claudepath list

Update claudepath

Update to the latest version — auto-detects whether you installed via Homebrew or pipx:

claudepath update

You can also force a specific method:

claudepath update --brew
claudepath update --pipx
claudepath update --pip

Restore from backup

List and restore from automatic backups:

claudepath restore --list       # see available backups
claudepath restore              # restore the latest backup
claudepath restore 20260227_145300  # restore a specific backup

Merge sessions when destination already has Claude data

If you opened Claude Code at the new location before running claudepath remap, Claude Code will have already created a new project directory there. Use --merge to combine the sessions from both directories:

claudepath remap ~/old/path ~/new/path --merge

Without --merge, claudepath will fail with a clear error suggesting you add the flag.

Full help

claudepath help
claudepath mv --help

What it updates

Note: file-history/, todos/, tasks/, and shell-snapshots/ are keyed by session UUID, not by project path — they don't need updating.

Options

Environment Variables

Backup & Rollback

By default, claudepath creates a backup before making any changes:

~/.claude/backups/claudepath/{timestamp}/

The backup includes:

• The full project data directory (~/.claude/projects/{encoded}/)
• ~/.claude/history.jsonl
• Affected usage-data/session-meta/*.json files (token usage & analytics)
• When using --merge: both the source and destination project directories

If any step fails, claudepath automatically restores from the backup. Use --no-backup only if you already have your own backup or want to skip the extra time.

How Claude Code encodes paths

Claude Code stores project data in ~/.claude/projects/ using an encoded directory name: every character that isn't an ASCII letter or digit (/, ., _, ~, spaces, non-ASCII, …) is replaced with -. Names longer than 200 characters are truncated and suffixed with a base-36 hash of the original path.

/Users/foo/my-project      →  -Users-foo-my-project
/Users/foo/local.tmp/proj  →  -Users-foo-local-tmp-proj

This means moving /Users/foo/old-name to /Users/foo/new-name requires:

1. Renaming -Users-foo-old-name to -Users-foo-new-name
2. Updating all path strings inside the data files

License

MIT