claudepath 1.1.2

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

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

File / Directory	What changes
~/.claude/projects/{encoded-dir}/	Renamed to match new path
sessions-index.json	originalPath, projectPath, fullPath updated (proper JSON parsing)
{session}.jsonl files	cwd and file path references updated (line-by-line, handles large files)
Subagent .jsonl files	Same as above, recursive
~/.claude/history.jsonl	project field updated for all matching entries
usage-data/session-meta/*.json	project_path updated (token usage & analytics)

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

Options

Flag	Description
--dry-run	Preview all changes without writing anything
--no-backup	Skip creating a backup before modifying files
--yes / -y	Skip the confirmation prompt
--merge	Merge sessions when destination already has Claude data
--verbose / -v	Show detailed file-by-file processing output
--claude-dir <path>	Override the Claude data directory (default: ~/.claude)

Environment Variables

Variable	Description
NO_COLOR	Disable colored output (set to any value)
FORCE_COLOR	Force colored output even when not a TTY

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