Session identity should be path-independent, not tied to project directory

[Sets]

Problem

Claude Code currently ties session identity to the project directory path. This means that whenever the path changes — for any reason — you lose access to session history, `/resume`, `/rewind`, and all other session-based features.

Affected scenarios

This is not just a single edge case. The same root cause breaks the workflow in multiple situations:

• Renaming or moving a project folder — session history is gone even though nothing about the project actually changed
• Cloning the same repo on a different machine — new path, new session, lost context
• Continuing work on another computer — even with the same repo, same branch, same everything, sessions don't transfer
• Different users on the same machine — same project, different home directory, disconnected sessions

What should change

Session identity should be tied to something stable and portable rather than the filesystem path. Some concrete options:

• Git remote URL — a natural stable identifier already present in most projects
• Project UUID in .claude/ — Claude Code already uses this directory; a .claude/project-id file would be low-friction and work for non-git projects too
• Hybrid — prefer git remote URL when available, fall back to a generated UUID stored in .claude/

This would unlock:

• Bidirectional session teleport (see [FEATURE] Universal session teleporting (local → remote, SSH support) #14666)
• Cross-machine continuity without being forced to SSH into the original machine
• Safe project reorganization without losing session history
• Potential for team session sharing in the future

Current workarounds

• SSH into the original machine and use tmux to reattach (works, but defeats the purpose of portability)
• Maintaining detailed CLAUDE.md files to preserve project context (helps with context, not with history)

Why this matters

Right now, session portability is blocked at the architectural level, not the feature level. Bidirectional teleport, cross-machine continuity, and folder-move resilience are all symptoms of the same underlying issue: sessions are identified by path rather than by project.

Fixing the root cause would make all of these naturally solvable — and would also complement context continuity solutions like those proposed in #11455, #6553, and #9171, which address what Claude remembers between sessions but not the portability of the session itself.

Related issues

• [FEATURE] Universal session teleporting (local → remote, SSH support) #14666 — Bidirectional session teleport (a subset of this problem)
• Feature Request: Session Handoff / Continuity Support #11455 — Session handoff / continuity support (complementary: context loss, not portability)
• Implement Chat Session Transfer and Improved Session Management #6553 — Chat session transfer and improved session management
• [FEATURE] Manual Session Save/Load Commands for Multi-Day Projects #9171 — Manual session save/load commands for multi-day projects

[Sets]

Real-world scenario: distributed local development

I want to share a concrete workflow that illustrates why this matters beyond simple folder moves or machine transfers.

I develop across a small home network of machines: a Mac Mini (main development machine), a NUC, several Raspberry Pis, and a Windows machine. Services are distributed — database on one machine, different parts of the application running on others. This is a fairly common setup for anyone doing homelab, embedded, IoT, or service-oriented development.

My workflow:

• I do most development on the Mac Mini with Claude Code, iterating directly against live services on the network
• When I need to work away from home (café, office), I connect back via Tailscale — full network access, SSH available
• But sometimes I work locally on my MacBook — faster to just edit and test without the SSH hop

The problem: every time I switch to local MacBook development and back, I'm starting a new session. Same repo, same branch, same everything — but lost history, lost /resume, lost continuity.

The current "workaround" is to always SSH into the Mac Mini and work from there. That works, but it means I can never work truly locally on the MacBook without sacrificing session continuity. It also means the MacBook is just a dumb terminal — which defeats the point of having a capable local machine.

This isn't a niche case. A lot of developers work this way:

• Homelab / self-hosted environments
• Embedded and IoT development (code runs on devices, not in the cloud)
• Teams where the "real" environment is a shared dev server
• Anyone with both a desktop and a laptop who wants to work fluidly between them

For all of these, worktrees and cloud-based solutions don't help. The missing piece is exactly what this issue describes: a session identity that travels with the project, not the path.

[github-actions]

Found 3 possible duplicate issues:

1. Sessions should survive project directory renames #37954
2. Project config tied to directory path breaks on file reorganization #24789
3. Path encoding collision causes session loss on directory reorganization #21085

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[Sets]

The suggested duplicates (#37954, #24789, #21085) are all related but narrower in scope — they focus specifically on directory rename/move scenarios on a single machine.

This issue is broader: it frames cross-machine session portability as the primary motivation, and argues that path-based session identity is the root architectural cause behind all of these cases, not just folder renames.

The key scenario not covered by any of the suggested duplicates: same repo, same branch, cloned on a different machine → completely disconnected session, no way to resume, even with tools like Tailscale providing full network access between the machines.

Closing this as a duplicate of those issues would leave the cross-machine portability use case without a tracking issue.

[jakem68]

We built a working workaround for this on Windows and wanted to share the approach.

The root issue is that Claude Code uses the filesystem path as the project identifier. Our solution introduces a .claude/project-id file in each workspace that stores the stable project name (the ~/.claude/projects/ directory name). A lightweight wrapper script (claude.bat) runs this check before every Claude session:

• New workspace → seeds .claude/project-id immediately
• Path matches → proceeds silently
• Renamed/moved → renames the ~/.claude/projects/ directory to match, updates all references
• Conflict (both old and new exist) → warns the user, suggests manual merge

This makes history preservation fully automatic — users never think about it.

The key insight for a native fix: Claude Code could seed a stable identifier in .claude/project-id on first session. Before starting, it checks for a mismatch and migrates accordingly. The check is sub-second in the happy path.

Scripts and documentation: https://github.com/jakem68/claude-project-sync

Note: currently Windows-only (PowerShell + .bat wrapper). The concept is platform-independent — contributions for macOS/Linux are welcome.

[BasedGPT]

Adding a concrete Windows path-alias variant from #56173 that supports the broader point here.

In addition to ordinary folder moves, Windows junctions/symlinks can split session identity even when there is only one physical project directory:

C:\Projects\OldName  (junction → C:\Projects\NewName)
C:\Projects\NewName  (the real folder)

Sessions launched through each path land under different ~/.claude/projects/ slugs (C--Projects-OldName vs C--Projects-NewName) because the slug is derived from the literal cwd string, not the resolved path.

Runtime-binding trap

Desktop holds the literal cwd string from session start in memory and uses it for every filesystem operation during that session. Removing the junction while a session is running breaks tool calls — Desktop tries to read/write through the now-missing path and gets "system cannot find the path" on every tool call.

If you've already broken a session this way: restoring the junction usually recovers it. Desktop's in-memory state isn't reloaded from disk; path resolution starts working again as soon as the junction is back. Restore it, finish the session normally, then plan the removal properly.

Pre-removal checklist

Before removing any junction that Claude Desktop sessions might have used:

# 1. Find all live session cwds (last 60 minutes)
find ~/.claude/projects -name "*.jsonl" -mmin -60 -exec tail -c 4000 {} \; \
  | grep -oE '"cwd":"[^"]+"' | sort -u

# 2. Any cwd containing the junction path = a session bound to it.
#    Close those sessions/windows first.

# 3. Quit Desktop fully (window + tray). Verify:
#    tasklist /FI "IMAGENAME eq claude.exe"

# 4. Remove the junction.

# 5. Relaunch Desktop using the canonical path only.

Path-independent identity (the core proposal here) removes all of this — the junction trap only exists because path IS identity.

[0xbrainkid]

This is a useful distinction: path-independent project identity is not just a convenience feature, it is the base layer for durable agent/session reputation.

The strongest design constraint I would preserve is:

• path is mutable,
• machine location is mutable,
• runtime session is mutable,
• project/session identity should be stable.

For AgentFolio/SATP-style trust, that stable identity is what lets a future verifier connect the work history across moves, clones, machines, and restarts. Without it, the audit trail fragments every time the developer changes environment, even if the repo, branch, and project intent are the same.

A minimal native version could be very small: a project-scoped stable ID plus an append-only mapping of observed paths/machines/sessions. Then the agent can prove continuity without treating the filesystem path as the identity root.