Cc-skills project-directory-migration

Migrate Claude Code project sessions when renaming directories. TRIGGERS - directory rename, move project, migrate sessions, project path change, workspace reorganization, rename folder.

install

source · Clone the upstream repo

git clone https://github.com/terrylica/cc-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/terrylica/cc-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/devops-tools/skills/project-directory-migration" ~/.claude/skills/terrylica-cc-skills-project-directory-migration && rm -rf "$T"

manifest: plugins/devops-tools/skills/project-directory-migration/SKILL.md

source content

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 "<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 (mise, uv, direnv, asdf)

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: mise trust, 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 (mise trust, 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

# 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

Pre-flight validation — 7 checks (paths, Claude Code dir, python3, no running sessions)

Backup — Timestamped copy to

~/.claude/migration-backup-YYYYMMDD-HHMMSS/

Move project directory — Rename in
```
~/.claude/projects/
```
Rewrite sessions-index.json — Update projectPath, fullPath, originalPath
Rewrite history.jsonl — Update project field (JSON-safe, preserves Unicode)
Backward-compatibility symlink — Old encoded path symlinks to new
Rename repo directory —
```
mv /old/path /new/path
```
Environment fixups — mise trust, venv recreate, direnv/asdf warnings
Post-flight verification — Sessions count, memory, symlink, env health

Reference Documentation

Session Storage Anatomy — How Claude Code stores project data
Troubleshooting Guide — Common post-migration issues and fixes
Evolution Log — Skill improvement history

Troubleshooting

Issue	Auto-fixed?	Manual Solution
mise trust error after rename	Yes (Phase 8)	`mise trust <new-path>`
`(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:

Locate yourself. — Find this SKILL.md's canonical path before editing.
What failed? — Fix the instruction that caused it.
What worked better than expected? — Promote to recommended practice.
What drifted? — Fix any script, reference, or dependency that no longer matches reality.
Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.