Project Directory Migration

Project Directory Migration

Safely migrate Claude Code project context (sessions, memory, history) when renaming a project directory.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

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 "<skill-scripts>/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

What Contains Path References

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

1. Pre-flight validation — 7 checks (paths, Claude Code dir, python3, no running sessions)
2. Backup — Timestamped copy to ~/.claude/migration-backup-YYYYMMDD-HHMMSS/
3. Move project directory — Rename in ~/.claude/projects/
4. Rewrite sessions-index.json — Update projectPath, fullPath, originalPath
5. Rewrite history.jsonl — Update project field (JSON-safe, preserves Unicode)
6. Backward-compatibility symlink — Old encoded path symlinks to new
7. Rename repo directory — mv /old/path /new/path
8. Environment fixups — mise trust, venv recreate, direnv/asdf warnings
9. 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

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path before editing.
1. What failed? — Fix the instruction that caused it.
2. What worked better than expected? — Promote to recommended practice.
3. What drifted? — Fix any script, reference, or dependency that no longer matches reality.
4. Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.