project-directory-migration

Original：🇺🇸 English

Translated

1 scripts

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

1installs

Sourceterrylica/cc-skills

Added on2026-02-20

NPX Install

npx skill4agent add terrylica/cc-skills project-directory-migration

SKILL.md Content

View Translation Comparison →

Project Directory Migration

Safely migrate Claude Code project context (sessions, memory, history) when renaming a project directory.

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 (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