project-directory-migration — Claude Code skill
project-directory-migration — a skill that transfers Claude Code sessions, history, and context when you rename or move a project folder. Runs interactively with dry-run preview and rollback support.
MIT 119 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill project-directory-migration -a claude-codeWhat project-directory-migration does
When a project moves to a new location, Claude Code loses track of old sessions — they stay bound to the old path. This skill rewrites metadata in ~/.claude/projects/ and ~/.claude/history.jsonl, recodes paths (slashes become hyphens), and creates a symlink for backward compatibility.
The workflow has four phases: ask for old and new paths, show a dry-run with session and history entry counts, let you choose what to migrate (sessions, MEMORY.md, symlink, venv recreation), then execute or export commands for manual run. The script backs up with a timestamp before making changes and supports rollback if needed.
Requires Bash, Read, Glob, Grep tools and user input capability. Works across all listed platforms; some may require you to open the SKILL.md file path after install.
What it helps with
- locate and transfer Claude Code sessions when renaming a directory
- restore conversation history after moving a project
- recreate a virtual environment with a new path
- preserve context and memory during workspace reorganization
- roll back to a timestamped backup if migration fails
Example prompts for the agent
- Rename your project from
my-old-nametomy-app, and the skill will transfer all sessions - After moving a project folder to a new location, run the migration to restore access to sessions
- Export migration commands and run them manually while Claude Code is closed
How to install project-directory-migration
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill project-directory-migration -a claude-code2Manually: put the files in place
~/.claude/skills/project-directory-migration/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/project-directory-migration/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill project-directory-migration -a codex2Manually: put the files in place
.agents/skills/project-directory-migration/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill project-directory-migration -a cursor2Manually: put the files in place
.cursor/skills/project-directory-migration/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/devops-tools/skills/project-directory-migration2Manually: put the files in place
.github/skills/project-directory-migration/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill project-directory-migration -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/devops-tools/skills/project-directory-migrationManually: put the files in place
.devin/skills/project-directory-migration/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill project-directory-migration -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about project-directory-migration
How do I install project-directory-migration in Claude Code?
Run npx skills add terrylica/cc-skills --skill project-directory-migration -a claude-code, then open ~/.claude/skills/project-directory-migration/SKILL.md.
What does project-directory-migration do?
Transfers Claude Code sessions, history, and context when you rename or move a project folder. Shows a dry-run preview, lets you choose what to migrate, creates a timestamped backup, and supports rollback.
Do I need to close Claude Code before running migration?
The skill checks for running sessions during validation. For maximum safety, export the commands and run them manually in your terminal while Claude Code is closed.
Source text
SKILL.md · MIT
---
name: project-directory-migration
description: Migrate Claude Code project sessions when renaming directories. TRIGGERS - directory rename, move project, migrate sessions
allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
---
# 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
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 (uv, direnv, asdf; a leftover mise config is flagged as retired)
### 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: 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 (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
```bash
# 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** — venv recreate, direnv/asdf warnings, leftover-mise-config warning
9. **Post-flight verification** — Sessions count, memory, symlink, env health
---
## Reference Documentation
- [Session Storage Anatomy](./references/session-storage-anatomy.md) — How Claude Code stores project data
- [Troubleshooting Guide](./references/troubleshooting.md) — Common post-migration issues and fixes
- [Evolution Log](./references/evolution-log.md) — Skill improvement history
---
## Troubleshooting
| Issue | Auto-fixed? | Manual Solution |
| ----------------------------- | -------------------- | -------------------------------------- |
| `(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 |
## 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.
© terrylica · MIT · terrylica/cc-skills