claude-relocate

Claude Code files every session under the folder it was started in. Rename or move that folder, or clone the project to another machine, and claude --resume no longer shows the old sessions. Project settings (allowed tools, trust) and prompt history stay behind too.

claude-relocate moves all of it to the new path:

• the session folder under ~/.claude/projects/ (the folder name is derived from the path), including subagent transcripts and the project's auto memory
• the cwd recorded in every session line
• the project entry in .claude.json
• the project field of the prompt history in history.jsonl

Subfolders that were used as separate projects (/old/app/api) move along. Before any change it writes a backup archive to ~/.claude/backups/.

Why

Users keep running into this, and the requests were closed without a fix:

Issue	State	Reactions
claude-code#33636 Sessions lost when project directory is moved or renamed	closed, not planned	6
claude-code#79215 Sessions should follow a renamed/moved project folder	closed, not planned	8
claude-code#53225 Desktop app shows no recovery option when the working directory was moved	closed, not planned	6
claude-code#88903 Desktop app: workflow for moved or renamed project folders	closed, duplicate	0
claude-code#96323 Sessions should follow a moved or renamed project folder (successor)	open	2
claude-agent-sdk-python#264 Portable session snapshots (export/import across machines)	open	11

(Reaction counts as of 2026-10-20.)

Install

pipx install git+https://github.com/Jwrede/claude-relocate

Python 3.10+, no dependencies. Tested on Linux; on macOS everything except the running-session check works.

Usage

Find sessions whose folder is gone:

$ claude-relocate list --missing
missing    5 session(s)  /home/dev/old-name

1 project(s) point to folders that no longer exist. Use `claude-relocate move OLD NEW`.

Move a project (run it before or after moving the folder itself):

$ claude-relocate move ~/old-name ~/code/new-name
sessions  -home-dev-old-name -> -home-dev-code-new-name
settings  /home/dev/old-name -> /home/dev/code/new-name
history   146 prompt(s) in history.jsonl

Moved 1 project folder(s), rewrote 2279 session line(s), 1 settings entr(y/ies), 146 history line(s).
Backup: /home/dev/.claude/backups/claude-relocate-20261020-040217.tar.gz

Options for move:

• --dry-run shows the plan and changes nothing.
• --rewrite-paths also replaces the old path inside messages and tool calls, so file paths in the transcript point to the new location.
• --force skips conflicts. Without it, the tool refuses when the target already has a session with the same ID, or when Claude Code is running inside the old folder.

Move sessions to another machine, where the project may live at a different path:

# old machine
claude-relocate export ~/code/app -o app-sessions.tar.gz

# new machine
claude-relocate import app-sessions.tar.gz --to /Users/dev/src/app

Import does not overwrite existing sessions or settings.

--config-dir (or CLAUDE_CONFIG_DIR) selects another Claude Code profile.

How it works and limits

Claude Code names the project folder after the working directory, with every character that is not a letter or digit replaced by -. That name cannot be decoded reliably (/a-b and /a/b give the same name). claude-relocate therefore reads the real path from the cwd field inside the session files. A folder without session files (for example only memory/) is matched by its name and only for the exact path given.

• The session file format is undocumented (claude-code#53516). Claude Code may change it, so keep the backup until you have resumed a moved session once.
• Very long paths, whose folder names Claude Code shortens, are reported as conflicts and not moved.
• Quit Claude Code sessions in the affected folder first. They keep writing to the old location.

License

MIT