Claude Code project history lost after renaming local root directory

[ceetity]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

I encountered a critical issue where all conversation history in Claude Code becomes inaccessible after renaming the local project root folder. Even though the files remain identical, Claude Code seems to treat the renamed folder as a completely new, empty project.
Interestingly, if I rename the folder back to its original name, all previous chat sessions reappear immediately. This suggests that session indexing is strictly hard-coded to the absolute local path rather than a persistent project identifier.

What Should Happen?

Claude Code should be able to maintain project session continuity even if the root directory is moved or renamed. There should be a mechanism (e.g., a persistent .claude ID or a CLI command like claude link) to re-associate an existing session history with a renamed directory.

Error Messages/Logs

Steps to Reproduce

Open a terminal and navigate to a project directory (e.g., /path/to/my-project).

Run claude and start a conversation with several messages.

Exit Claude and close the terminal.

Rename the local root folder from my-project to my-project-v2.

Navigate into my-project-v2 and run claude again.

Observe that the previous conversation history is gone.

Rename the folder back to my-project and run claude again; notice the history is restored.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

ALL

Platform

Other

Operating System

Windows

Terminal/Shell

Windows Terminal

Additional Information

No response

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[idx]

Proposal / RFC: Path-independent project identity for session history (with an eventual-consistency sync path)

Scope note: This is a design proposal that consolidates several existing reports of the same root cause. It is not a duplicate bug report — the goal is to give maintainers a concrete, incremental spec to react to.

Related issues (same underlying cause): #33634 (closed), #48394 (open, stale), #41344, #27473, #65399, #47926.

Summary

Claude Code keys all session history on the absolute filesystem path of the project (~/.claude/projects/<encoded-path>/, plus hardcoded absolute paths inside the *.jsonl transcripts and sessions-index.json). Any move, rename, drive migration, or even a case-only change orphans the entire history, and there is no first-party way to re-link it.

This proposal replaces "absolute path = primary key" with a path-independent project identity, and — because the resulting data model is almost entirely append-only — makes multi-machine synchronization a natural, low-risk extension rather than a separate feature.

The design is deliberately staged so that Phase 1 alone fixes the reported bug, and later phases are optional.

Problem recap

• Session store path is derived from the absolute path (/ → -).
• On path change, Claude Code creates a new, empty project dir and cannot associate it with the old one.
• The *.jsonl files and sessions-index.json themselves embed absolute paths, so simply renaming the encoded directory is insufficient.
• Real-world triggers: repo reorganization, monorepo restructuring, moving between drives, renaming for a rebrand, working across machines/VMs/containers where the home path differs.

Proposed spec

Phase 1 — Portable project identity (fixes the bug on its own)

1. On first claude launch in a directory, write a stable identifier to the project itself:

   <project-root>/.claude/workspace.json
   { "projectId": "<UUIDv7>", "schema": 1 }
   

2. Make projectId — not the encoded path — the key under ~/.claude/projects/.
3. Demote the absolute path to mutable metadata. Maintain ~/.claude/project-index.json mapping projectId → currentPath (plus last-seen timestamp).
4. On launch, read the projectId from cwd. If the recorded path differs, auto-update the binding silently. No history is lost because the key never changed.

Resolution / fallback order when workspace.json is absent (legacy projects, fresh clones):

1. Match by git remote URL + repo-root relative position.
2. Match by the legacy encoded absolute path (backward compatibility).
3. If still unmatched, mint a new projectId.

When an orphaned history matching the old path is detected, prompt:

"Found session history previously stored for <old-path>. Re-link it to this project?"

Edge cases to specify explicitly

• cp -r duplicating a projectId → detect collision on next launch and fork a new id, so two copies don't clobber one history.
• git worktree → each worktree gets its own projectId but stores a back-reference to the parent repo id.
• Case-only rename on case-insensitive FS → resolved by id, not path, so it just works.

Phase 2 — Relative paths inside transcripts

Record file references inside *.jsonl and sessions-index.json relative to the project root, resolved against the current root at load time. This removes the last absolute-path dependency and is the precondition that makes Phase 3 clean. (Ships a one-time migration that rewrites existing absolute references to relative.)

Phase 3 — Optional eventual-consistency sync (weak sync is sufficient)

Once identity is path-independent and transcripts are relative, the data model is essentially a set of CRDTs, so no strong consistency is needed:

Data	Nature	CRDT type
Session *.jsonl	per-session, single-writer, append-only	G-Set (grow-only) — union merge, conflicts impossible by construction
Project metadata (name, current path, last access)	last edit wins	LWW-Map
Global history.jsonl prompt log	multi-writer, append-only	line-wise union + dedupe

A minimal spec: a synced object is a set of (projectId, deviceId, sessionUuid)-tagged session logs merged by set union, with metadata merged by LWW. This is exactly what claude.ai already does conceptually for chat threads across devices (see #47926), but applied to on-disk session state so it also works offline / weakly connected across heterogeneous machines (different OS, different CPU arch, containers/VMs).

Must be excluded from any sync, for correctness and size:

• plugins/ caches (bundle node_modules / Python .venv — large, machine-/arch-specific, regenerated on demand)
• shell-snapshots/, lock files, other caches
• ~/.claude.json auth / credentials (must stay per-device)

Note: transcripts can contain secrets (a tool reading .env, a command printing a credential ends up in projects/<id>/<session>.jsonl), so any first-party sync should be end-to-end encrypted and default to a private scope.

Why staged

• Phase 1 alone closes the reported bug and unblocks Sessions lost when project directory is moved or renamed #33634 / Claude Code project history lost after renaming local root directory #48394 / Project path migration: moving a directory breaks all sessions #41344 / Session resume should support moved/renamed project directories #27473 with modest surface area.
• Phase 2 is a mechanical migration.
• Phase 3 is optional and additive; the CRDT shape means it can ship as eventual-consistency without touching the strong-consistency parts of the product (there essentially are none in this domain).

Interim CLI surface (useful even before Phase 1)

• claude project relink <old-path> <new-path> — re-associate orphaned history (first-party equivalent of today's community tools).
• claude project id — print/emit the workspace.json id for the current project.
• claude project purge already exists for cleanup; a relink counterpart would round out lifecycle management.

Prior art / existing workarounds (evidence this is real and solvable)

• Community CLIs already remap paths and rewrite *.jsonl references (e.g. claudepath, claude-mv), and a sync tool already implements exactly the "translate paths during sync + G-Set-style union" approach with age encryption. These prove the data model supports the proposed design; the point of this RFC is to make it first-party and identity-based rather than path-patching after the fact.

Requested outcome

1. Reopen Sessions lost when project directory is moved or renamed #33634 (or adopt Claude Code project history lost after renaming local root directory #48394 as the tracking issue) and label as design/enhancement.
2. Consider Phase 1 as a standalone fix.
3. Feedback on the identity resolution order and the cp -r / worktree edge cases before implementation.