claude-relocate: move Claude Code sessions with the project folder

The problem

Claude Code files every session under a folder in ~/.claude/projects/ whose name is derived from the working directory. When the project folder is renamed or moved, or the project is cloned to another machine, claude --resume no longer shows the old sessions. The project settings (allowed tools, trust) and the prompt history stay attached to the old path as well.

Several issues ask for a fix, and most of them were closed without one (reaction counts as of 2026-10-20):

• anthropics/claude-code#33636, "Sessions lost when project directory is moved or renamed", closed as not planned, 6 reactions.
• anthropics/claude-code#79215, "Sessions should follow a renamed/moved project folder", closed as not planned, 8 reactions.
• anthropics/claude-code#53225, the desktop app shows no recovery option when the working directory was moved, closed as not planned, 6 reactions.
• anthropics/claude-code#96323, the open successor issue, 2 reactions.
• anthropics/claude-agent-sdk-python#264, "Portable session snapshots (export/import across machines)", open, 11 reactions.

How it works

claude-relocate updates the four places where Claude Code stores the path: the session folder under ~/.claude/projects/ (including subagent transcripts and the project's auto memory), the cwd field in every line of every session file, the project entry in .claude.json, and the project field in history.jsonl.

The folder name cannot be decoded reliably, because Claude Code replaces every character that is not a letter or digit with -, so /a-b and /a/b give the same name. The tool therefore reads the real path from the cwd field inside the session files. Subfolders that were used as separate projects move along. Before any change it writes a backup archive to ~/.claude/backups/. It refuses to run when the target already has a session with the same ID or when Claude Code is running inside the old folder, unless --force is given. --dry-run shows the plan, and --rewrite-paths also replaces the old path inside messages and tool calls. For a move to another machine, export writes an archive and import --to unpacks it under a new path without overwriting existing sessions or settings.

This is the example from the README:

$ 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`.

$ 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

It is written in Python without dependencies.

Testing

The tests build a Claude Code profile in a temporary directory, selected with CLAUDE_CONFIG_DIR. It contains four projects: /work/app, its subfolder /work/app/sub, a sibling /work/application with the same prefix, and /other. Moving /work/app must rewrite the session folder, the cwd fields, the settings entry and the history, carry the subfolder along, leave the sibling and the message text unchanged, and produce a backup archive that contains the session file and .claude.json. Further tests cover --rewrite-paths, the dry run, a conflicting session ID, a merge into an existing folder, an export and import round trip to a different path, a folder that only holds memory, subagent transcripts, and the running-session check against a fake /proc tree.

CI runs the tests on Python 3.10 to 3.13, runs ruff, and calls the tool against an empty profile. The tool was also checked end to end with Claude Code 2.1.304: a session was created, its folder moved, claude-relocate move run, and claude --resume <id> in the new folder continued with the old context.

Limitations

• The session file format is undocumented (anthropics/claude-code#53516) and may change. The README advises keeping the backup until a moved session has been resumed once.
• Very long paths, whose folder names Claude Code shortens, are reported as conflicts and not moved.
• Claude Code sessions that are still open in the old folder keep writing to the old location, so they have to be closed first.
• It is tested on Linux. On macOS everything except the running-session check works.

The code and installation instructions are at github.com/Jwrede/claude-relocate.