Migrate Sessions

Language

Match user's language: Respond in the same language the user uses.

Overview

When a project directory is moved or renamed, Claude Code loses the link to its sessions and memory because ~/.claude/projects/ uses path-encoded directory names. This skill remaps that data to the new path.

Supports: exact match, prefix/nested matching, dry-run, merge (when target already exists), batch operations, and optional directory move.

Workflow

Progress:

• Step 1: Preflight — verify ~/.claude/projects/ exists
• Step 2: Ask user for operation: scan / move / batch
• Step 3: Dry-run — show plan, ask for confirmation
• Step 4: Execute with -x flag after user confirms
• Step 5: Present completion report

Runtime

Preflight

python3 {SKILL_DIR}/scripts/main.py preflight

If ready is false, ~/.claude/projects/ does not exist. Fix: open any project in Claude Code at least once (cd /some/project && claude) to initialize the directory structure.

Script Commands

All commands output JSON to stdout. Errors go to stderr as JSON.

Scan Output

{
  "status": "ok",
  "path": "/resolved/path",
  "encoded_prefix": "-resolved-path",
  "matches": [
    {"dir": "dir-name", "reason": "exact match", "sessions": 3, "session_dirs": 1, "has_memory": true, "memory_files": 5}
  ]
}

Move Output (dry-run)

{
  "status": "ok",
  "mode": "dry-run",
  "ops": [
    {"from": "old-encoded", "to": "new-encoded", "reason": "exact", "sessions": 3, "has_memory": true, "target_exists": false}
  ],
  "warnings": []
}

Move Output (execute)

{
  "status": "ok",
  "mode": "execute",
  "results": [
    {"from": "old-encoded", "to": "new-encoded", "action": "MOVED|MERGED|SKIP", "detail": "..."}
  ],
  "dir_status": "DIR MOVED|null",
  "warnings": []
}

Completion Report

After execution, present:

[Migrate Sessions] Complete!

Operation: move (execute)
From: /old/path → /new/path
Results: 2 moved, 1 merged, 0 skipped
Directory: MOVED

⚠ Warnings: (if any)

For batch, show per-line results and a summary.

Troubleshooting

<!-- Keep under 200 lines. Move detailed docs to references/. -->