ccmv

Claude Code project directory migration tool.

When you move a project directory, Claude Code loses track of your conversation history because it's stored in ~/.claude/projects/ using path-encoded directory names.

ccmv moves your project and updates all Claude Code and/or Cursor references automatically. Works with:

• Projects with both Claude Code and Cursor data
• Claude Code-only projects (no Cursor)
• Cursor-only projects (no Claude Code history)

# Using npm (recommended)
npm install -g ccmv

# Or using npx (no installation required)
npx ccmv --help

ccmv [OPTIONS] <old-path> <new-path>

Options:
  --refs-only    Only update references (don't move directory)
  --dry-run      Preview changes without executing
  --keep-backup  Keep backup after successful migration
  --no-cursor    Skip Cursor editor data updates
  --quiet        Suppress detailed output
  --help         Show help

# Move project to new location
ccmv ~/projects/myapp ~/work/myapp

# Or using npx
npx ccmv ~/projects/myapp ~/work/myapp

# Preview what would happen
ccmv --dry-run ~/old-project ~/new-project

# Already moved? Just update refs
ccmv --refs-only /old/path /new/path

1. Detects Claude Code and/or Cursor data for the project
2. Creates backup of existing data
3. Moves project directory (unless --refs-only)
4. Updates Claude Code data (if exists):
   • Renames ~/.claude/projects/{encoded-path}/
   • Updates cwd field in all JSONL files
   • Updates project field in ~/.claude/history.jsonl
   • Updates cwd in ~/.claude/sessions/*.json
   • Updates sessions-index.json (fullPath, projectPath, originalPath)
5. Updates Cursor workspace data (if exists):
   • Renames workspaceStorage/{hash}/ directory
   • Updates storage.json (profile associations)
   • Updates state.vscdb (global SQLite database)
   • Updates workspaceStorage/*/workspace.json
   • Updates workspaceStorage/*/state.vscdb
6. Verifies migration success
7. Auto-rollback on any failure

Note: Migration requires at least one of Claude Code or Cursor data to exist. If neither exists, use regular mv command.

~/.claude/
├── projects/
│   └── -Users-jane-myproject/    # Encoded from /Users/jane/myproject
│       ├── session-abc.jsonl     # Contains "cwd":"/Users/jane/myproject"
│       ├── sessions-index.json   # Session index with fullPath, projectPath
│       └── subagents/
│           └── agent-xyz.jsonl
├── sessions/                      # Active session metadata
│   └── 12345.json                 # Contains "cwd":"/Users/jane/myproject"
└── history.jsonl                  # Global history with "project" field

Path encoding: /Users/jane/foo bar → -Users-jane-foo-bar

If Cursor is installed, ccmv also updates:

~/Library/Application Support/Cursor/User/
├── globalStorage/
│   ├── storage.json          # Profile workspace associations
│   └── state.vscdb           # SQLite: history, repository paths
└── workspaceStorage/
    └── {hash}/
        ├── workspace.json    # Workspace folder URI
        └── state.vscdb       # Workspace-specific data

Note: Cursor must be closed during migration to prevent data corruption.

• Node.js 18.0.0 or later
• macOS or Linux

MIT