Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill project-directory-migration -a claude-code
Open on GitHub

What 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-name to my-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-code

2Manually: put the files in place

~/.claude/skills/project-directory-migration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/project-directory-migration/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set79

The whole set →
evolutionary-metric-ranking evolutionary-metric-ranking is a Claude Code skill that ranks and filters model and strategy configurations across multiple metrics using percentile cutoffs, intersection rules, and evolutionary search. CX Codex +1 121installs pre-ship-review The pre-ship-review skill runs structured quality checks before a pull request, release, or milestone. It catches integration failures where contracts, examples, and tests must align across files. CX Codex +1 120installs pueue-job-orchestration pueue-job-orchestration manages long-running tasks and batch processing using pueue queue orchestration, parallelism groups, and detailed CLI logs. CX Codex +1 120installs distributed-job-safety The distributed-job-safety skill helps prevent file collisions and unsafe concurrency in pipelines using pueue, moon, and systemd-run. Use it when jobs share files or compete for host resources. CX Codex +1 120installs infra-deploy infra-deploy deploys self-hosted Cal.com to GCP Cloud Run on a Supabase PostgreSQL database, or runs it locally with Docker Compose. CX Codex +1 119installs email-triage email-triage sorts recent Gmail messages into three categories and ranks their urgency. Use it to request an email digest through the bot’s /digest command. CX Codex +1 117installs bot-process-control bot-process-control maintains process control rules for Gmail Commander bot instances in Restate and blocks duplicate Telegram pollers on workstations. CX Codex +1 117installs interactive-bot interactive-bot is a Claude Code skill that documents the Gmail Commander Telegram bot. It covers email slash commands, AI routing of free text through MCP, and compose/reply sessions. CX Codex +1 114installs

Project sponsors

Companies that keep this analytics open