@lovstudio/cc-mv

Move a project folder and migrate all its Claude Code state in one command.

When you mv /old/project /new/project, claude --resume stops finding your history — CC keys its store by a path-slug, so sessions still sit at ~/.claude/projects/<old-slug>/ while CC looks in <new-slug>/.

cc-mv does the move and migrates the state:

1. mv FROM TO on disk (fs.renameSync — instant, preserves mtime/perms; falls back to shell mv for cross-device)
2. Rewrites ~/.claude/projects/<slug>/*.jsonl — including every sub-directory slug
3. Rewrites ~/.claude/history.jsonl — the prompt up-arrow recall index
4. Rewrites ~/.claude/sessions/<pid>.json — running-session records

After it runs, cd TO && claude --resume shows the full history.

Install / Use

Zero install — just run with npx:

npx -y @lovstudio/cc-mv /old/project /new/project

It previews the plan and asks for confirmation. Add --yes to skip the prompt, or --dry-run to see what it would do without writing.

Options

Flag	Purpose
-y, --yes	Skip interactive confirmation
--dry-run	Print the plan, don't write
--no-mv	Skip the filesystem mv (only migrate CC state — post-move recovery)
--json	Machine-readable output (used by the CC skill)
--projects-dir <dir>	Override ~/.claude/projects
--session <id>	Session-level mode: migrate only this session id (repeatable)
--grep <pattern>	Session-level mode: migrate sessions whose first user prompt matches the regex (case-insensitive)
--pick	Session-level mode: interactively pick sessions from a numbered list
--list-sessions	Print session summaries for FROM (id, mtime, size, first user prompt) and exit — use with --json for scripting
--delete-source	Delete migrated source sessions after copy+rewrite (default keeps them as a safety net)
-h, --help	Show help

Session-level migration

By default cc-mv migrates everything under the FROM slug — including all sub-directory sessions. If you only want specific sessions (e.g. you ran many unrelated chats in one dir and only want to move the ones about topic X to a dedicated project), use session-level mode:

# List sessions + first-prompt summaries (read-only — pick ids from this)
npx -y @lovstudio/cc-mv ~/old --list-sessions

# Migrate specific session ids
npx -y @lovstudio/cc-mv ~/old ~/new --session abc-def-... --session 123-... --yes

# Regex-match on first user prompt
npx -y @lovstudio/cc-mv ~/old ~/new --grep 'command vs skill' --yes

# Interactive picker
npx -y @lovstudio/cc-mv ~/old ~/new --pick

In session-level mode:

• fs mv is always disabled (you're moving a subset of sessions, not the whole project folder). Passing --mv is an error.
• Sub-directory slugs are ignored (session-level is root-slug-only by design).
• Source sessions are kept by default; pass --delete-source to remove them after migration.
• history.jsonl is not rewritten (your prompt up-arrow history for FROM stays at FROM, since the project wasn't actually moved).

Examples

# Move + migrate in one shot
npx -y @lovstudio/cc-mv ~/old-repo ~/new-repo

# Post-move recovery (folder already moved externally — FROM doesn't exist on disk)
npx -y @lovstudio/cc-mv /old /new --no-mv

# Dry-run
npx -y @lovstudio/cc-mv /a /b --dry-run

# Session-level: migrate one specific chat to a new project, delete source
npx -y @lovstudio/cc-mv ~/old ~/new --session <uuid> --delete-source --yes

Sub-directory handling

If you've run CC in sub-directories of the project (/old/pkg-a, /old/pkg-b, ...), each has its own slug dir. cc-mv discovers and migrates them all in one pass.

It works by listing ~/.claude/projects/ and matching any slug where slug === <fromSlug> or slug.startsWith(<fromSlug> + "-"). That catches FROM and all descendants without traversing your filesystem — fast and exact.

Backwards-compatible alias

cc-migrate-session is also a bin in this package. Same code, but defaults to --no-mv (only migrates CC state, doesn't move anything on disk). Use it when the folder has already been moved externally and you just need CC to catch up.

npx -y @lovstudio/cc-migrate-session /old /new

Safety

• Copy, don't clobber. Old slug dirs are never deleted. If anything goes wrong, the old state is still there.
• cc-mv refuses if TO already exists on disk — no silent overwrite of the project folder.
• When the destination slug dir already exists, session files are merged (conflicts overwrite); you'll get a warning.
• Malformed jsonl lines are passed through unchanged.

Verify claude --resume works at the new location before rm -rf ~/.claude/projects/<old-slug>*.

How it works

CC stores each session at:

~/.claude/projects/<slug>/<session-uuid>.jsonl

where <slug> is the project's absolute path with every non-[A-Za-z0-9] character replaced by -:

Path	Slug
/Users/mark/my-project	-Users-mark-my-project
/Users/mark/.claude	-Users-mark--claude (. → -)
/Users/mark/@手工川	-Users-mark----- (@ + 3 CJK chars)

Each jsonl line also embeds "cwd": "<absolute path>". Both the dir name and the per-line cwd must be updated — plus the other two indices (history.jsonl, sessions/*.json) that also carry absolute paths. This tool handles all four places.

Companion CC skill

The skill/lovstudio-cc-mv/ dir in this repo is a Claude Code skill. Symlink it:

ln -s $(pwd)/skill/lovstudio-cc-mv ~/.claude/skills/lovstudio-cc-mv

Then when you tell Claude "move this project to /new/path" or "I moved the folder and --resume is gone", CC will auto-invoke this CLI.

License

MIT