- Project Directory Migration
- Safely migrate Claude Code project context (sessions, memory, history) when renaming a project directory.
- When to Use This Skill
- Use this skill when:
- Renaming a project directory (e.g.,
- my-old-name/
- to
- my-new-name/
- )
- Moving a project to a different path
- User says "No conversations found" after a directory rename
- Reorganizing workspace directories
- Package rename requires matching directory name to GitHub repo name
- Recovering sessions that became orphaned after a directory move
- Interactive Workflow
- Phase 1: Gather Facts
- Use AskUserQuestion to collect source and target paths.
- Question 1 (header: "Source"): "What is the current project directory path?"
- Options:
- - "Use current directory: $PWD" (Recommended)
- - "Specify a different path"
- Question 2 (header: "Target"): "What should the new directory path be?"
- Options:
- - (User provides via "Other" free text)
- Phase 2: Dry-Run Audit
- Run the migration script in
- --dry-run
- mode to discover what needs migrating:
- bash
- "
/claude-code-migrate.sh" - --dry-run
- "
- $OLD_PATH
- "
- "
- $NEW_PATH
- "
- Present findings to user:
- Number of session files found
- Number of history.jsonl entries to rewrite
- Whether auto-memory (MEMORY.md) exists
- Environment tooling detected (mise, uv, direnv, asdf)
- Phase 3: Scope and Confirm
- Question 3 (header: "Scope", multiSelect: true):
- "What should be included in migration?"
- Options:
- - "Claude Code sessions + history (Recommended)"
- - "Auto-memory (MEMORY.md) (Recommended)"
- - "Backward-compatibility symlink (Recommended)"
- - "Auto-fix environment: mise trust, venv recreate (Recommended)"
- Question 4 (header: "Execute"):
- "Ready to migrate? The script creates a timestamped backup first."
- Options:
- - "Execute migration now (Recommended)"
- - "Export copy-paste commands for manual execution"
- - "Cancel"
- If user chooses "Export copy-paste commands"
- Generate the exact commands they can paste into their terminal after closing Claude Code. This is the safest option since Claude Code won't be accessing the project files during migration. Phase 4: Post-Migration Report After migration completes, report: Sessions migrated, history entries rewritten Environment fixups applied (mise trust, venv recreated) Remaining manual steps (git remote update, etc.) Rollback command if anything goes wrong Quick Reference Claude Code Path Encoding Claude Code encodes directory paths by replacing / with - : /Users/alice/projects/my-app --> -Users-alice-projects-my-app Storage Locations Asset Location Sessions ~/.claude/projects/{encoded-path}/*.jsonl Memory ~/.claude/projects/{encoded-path}/memory/MEMORY.md Session index ~/.claude/projects/{encoded-path}/sessions-index.json History ~/.claude/history.jsonl Subagents ~/.claude/projects/{encoded-path}/{session-id}/subagents/ What Contains Path References File Fields with paths Needs rewriting? sessions-index.json originalPath , entries[].projectPath , entries[].fullPath Yes history.jsonl project field per entry Yes Session .jsonl files None No MEMORY.md None (content only) No Migration Script Located at scripts/claude-code-migrate.sh . Usage
Dry run (preview what would happen)
bash scripts/claude-code-migrate.sh --dry-run /old/path /new/path
Execute migration
bash scripts/claude-code-migrate.sh /old/path /new/path
Rollback from most recent backup
bash scripts/claude-code-migrate.sh --rollback
Show help
bash
scripts/claude-code-migrate.sh
--help
9-Phase Execution
Pre-flight validation
— 7 checks (paths, Claude Code dir, python3, no running sessions)
Backup
— Timestamped copy to
~/.claude/migration-backup-YYYYMMDD-HHMMSS/
Move project directory
— Rename in
~/.claude/projects/
Rewrite sessions-index.json
— Update projectPath, fullPath, originalPath
Rewrite history.jsonl
— Update project field (JSON-safe, preserves Unicode)
Backward-compatibility symlink
— Old encoded path symlinks to new
Rename repo directory
—
mv /old/path /new/path
Environment fixups
— mise trust, venv recreate, direnv/asdf warnings
Post-flight verification
— Sessions count, memory, symlink, env health
Reference Documentation
Session Storage Anatomy
— How Claude Code stores project data
Troubleshooting Guide
— Common post-migration issues and fixes
Evolution Log
— Skill improvement history
Troubleshooting
Issue
Auto-fixed?
Manual Solution
mise trust error after rename
Yes
(Phase 8)
mise trust