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

Command	Purpose	Example
`preflight`	Check `~/.claude/projects/` exists	`python3 scripts/main.py preflight`
`scan`	Show all Claude data for a path	`python3 scripts/main.py scan <path>`
`move`	Dry-run path migration	`python3 scripts/main.py move <old> <new>`
`move -x`	Execute migration	`python3 scripts/main.py move <old> <new> -x`
`move -x -d`	Execute + move actual directory	`python3 scripts/main.py move <old> <new> -x -d`
`batch`	Dry-run batch from manifest	`python3 scripts/main.py batch <manifest.txt>`
`batch -x`	Execute batch	`python3 scripts/main.py batch <manifest.txt> -x`

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

Symptom	Resolution
"No Claude data found"	Path may never have been opened in Claude Code, or already migrated
Merge conflicts	Tool skips existing files in target — check both dirs manually if needed
Nested projects not found	Ensure the old path is the exact prefix used when opening in Claude Code

migrate-sessions