project-directory-migration_skill

Overview

This skill migrates Claude Code project sessions, history, and related artifacts when you rename or move a project directory. It performs a safe, auditable migration with a dry-run, timestamped backup, optional symlink compatibility, and environment fixups to minimize post-move breakage. Use it to recover orphaned sessions or to align directory names with repository or package names.

How this skill works

The skill asks for source and target paths, runs a dry-run audit to list sessions, history entries, and memory files affected, then prompts for scope and confirmation. The migration script creates a timestamped backup, renames the encoded project directory in Claude storage, rewrites path fields in sessions-index and history.jsonl, optionally creates a backward-compatibility symlink, moves the actual repo directory, and applies environment repairs (mise, venv, direnv/asdf) with a post-flight verification report.

When to use it

• After renaming or moving a project directory and Claude shows “No conversations found”
• When reorganizing workspace folders or changing project path structure
• When package or GitHub repo rename requires matching local directory name
• To recover sessions or history entries that became orphaned after a move
• Before pushing a renamed repo to ensure local agent context matches the new path

Best practices

• Run the dry-run first to review what will change and how many entries will be rewritten
• Include sessions, history, MEMORY.md, and symlink in scope unless you have a specific reason not to
• Choose “Export copy-paste commands” if you must run the commands manually outside Claude Code
• Keep backups: the script creates a timestamped backup and provides a rollback option
• Verify git remotes and authentication after migration; update credential helpers if needed

Example use cases

• Rename local folder from my-old-name to my-new-name without losing Claude sessions
• Move a project into a new workspace and rewrite history entries to the new path
• Restore conversations after a mistaken directory rename that made sessions disappear
• Align project directory name with package.json or repository slug during release
• Create a compatibility symlink so older encoded paths still resolve to the new project