# Migrate Sessions

> Migrate Claude Code session & memory data when project directories move. Use when user says 'migrate sessions', 'move project path', 'fix Claude data after move', 'scan Claude data', '迁移 session', '项目搬家', or reports lost sessions/memory after renaming a directory.

- Skill: `psylch/migrate-sessions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add psylch/migrate-sessions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/psylch/migrate-sessions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: psylch (https://skillmd.com/u/psylch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/psylch/migrate-sessions

---


# 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

```bash
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

```json
{
  "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)

```json
{
  "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)

```json
{
  "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 |

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