Das Problem
Claude Code legt jede Session in einem Ordner unter ~/.claude/projects/ ab,
dessen Name aus dem Arbeitsverzeichnis abgeleitet ist. Wird der Projektordner
umbenannt oder verschoben oder das Projekt auf einem anderen Rechner geklont,
zeigt claude --resume die alten Sessions nicht mehr an. Auch die
Projekteinstellungen (erlaubte Werkzeuge, Vertrauen) und der Prompt-Verlauf
bleiben am alten Pfad hängen.
Mehrere Issues verlangen eine Lösung, die meisten wurden ohne eine geschlossen (Reaktionen Stand 2026-10-20):
- anthropics/claude-code#33636, "Sessions lost when project directory is moved or renamed", geschlossen als not planned, 6 Reaktionen.
- anthropics/claude-code#79215, "Sessions should follow a renamed/moved project folder", geschlossen als not planned, 8 Reaktionen.
- anthropics/claude-code#53225, die Desktop-App bietet keine Wiederherstellung an, wenn das Arbeitsverzeichnis verschoben wurde, geschlossen als not planned, 6 Reaktionen.
- anthropics/claude-code#96323, das offene Nachfolge-Issue, 2 Reaktionen.
- anthropics/claude-agent-sdk-python#264, "Portable session snapshots (export/import across machines)", offen, 11 Reaktionen.
Wie es funktioniert
claude-relocate ändert die vier
Stellen, an denen Claude Code den Pfad speichert: den Session-Ordner unter
~/.claude/projects/ (samt Transkripten der Subagenten und dem automatischen
Gedächtnis des Projekts), das Feld cwd in jeder Zeile jeder Session-Datei,
den Projekteintrag in .claude.json und das Feld project in
history.jsonl.
Der Ordnername lässt sich nicht zuverlässig zurückübersetzen, weil Claude Code
jedes Zeichen außer Buchstaben und Ziffern durch - ersetzt. /a-b und /a/b
ergeben denselben Namen. Das Werkzeug liest den echten Pfad deshalb aus dem
Feld cwd in den Session-Dateien. Unterordner, die als eigene Projekte genutzt
wurden, ziehen mit um. Vor jeder Änderung schreibt es ein Backup-Archiv nach
~/.claude/backups/. Es bricht ab, wenn am Ziel schon eine Session mit
derselben ID liegt oder Claude Code im alten Ordner läuft, außer mit --force.
--dry-run zeigt den Plan, --rewrite-paths ersetzt den alten Pfad auch in
Nachrichten und Werkzeugaufrufen. Für den Umzug auf einen anderen Rechner
schreibt export ein Archiv, und import --to entpackt es unter einem neuen
Pfad, ohne vorhandene Sessions oder Einstellungen zu überschreiben.
Das ist das Beispiel aus der 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.gzEs ist in Python ohne Abhängigkeiten geschrieben.
Tests
Die Tests bauen in einem temporären Verzeichnis ein Claude-Code-Profil auf, das
über CLAUDE_CONFIG_DIR ausgewählt wird. Es enthält vier Projekte:
/work/app, dessen Unterordner /work/app/sub, einen Nachbarn
/work/application mit demselben Präfix und /other. Beim Verschieben von
/work/app müssen Session-Ordner, cwd-Felder, Einstellungseintrag und
Verlauf umgeschrieben werden, der Unterordner muss mitziehen, Nachbar und
Nachrichtentext müssen unverändert bleiben, und es muss ein Backup-Archiv
entstehen, das die Session-Datei und .claude.json enthält. Weitere Tests
decken --rewrite-paths, den Probelauf, eine kollidierende Session-ID, das
Zusammenführen mit einem vorhandenen Ordner, einen Export und Import auf einen
anderen Pfad, einen Ordner nur mit Gedächtnis, Transkripte von Subagenten und
die Prüfung auf laufende Sessions gegen einen nachgebauten /proc-Baum ab.
Das CI führt die Tests auf Python 3.10 bis 3.13 aus, prüft mit ruff und ruft
das Werkzeug gegen ein leeres Profil auf. Zusätzlich wurde es mit Claude Code
2.1.304 von Anfang bis Ende geprüft: Session angelegt, Ordner verschoben,
claude-relocate move ausgeführt, und claude --resume <id> lief im neuen
Ordner mit dem alten Kontext weiter.
Grenzen
- Das Format der Session-Dateien ist nicht dokumentiert (anthropics/claude-code#53516) und kann sich ändern. Die README rät, das Backup zu behalten, bis eine verschobene Session einmal fortgesetzt wurde.
- Sehr lange Pfade, deren Ordnernamen Claude Code kürzt, werden als Konflikt gemeldet und nicht verschoben.
- Sessions, die im alten Ordner noch offen sind, schreiben weiter an den alten Ort. Sie müssen vorher beendet werden.
- Getestet ist es unter Linux. Unter macOS funktioniert alles außer der Prüfung auf laufende Sessions.
Code und Installationsanleitung liegen unter github.com/Jwrede/claude-relocate.