Project Directory Migration Skill

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 "<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

| 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 <new-path> | | (old-name) in shell prompt | Yes (Phase 8) | Restart terminal or uv sync | | VIRTUAL_ENV path mismatch | Yes (Phase 8) | uv sync --dev recreates venv | | "No conversations found" | Yes (Phase 4) | Re-run migration script | | .envrc not allowed | Warned (Phase 8) | direnv allow | | Git push auth fails | No | Update credential helper or remote URL | | Session subdirs missing | No | Use --rollback, retry |

Agent Skills: Project Directory Migration

Install this agent skill to your local

Skill Files