[FEATURE] Cross-machine session portability (relative path resolution for project contexts)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I work across two machines (company laptop + personal laptop) with the same Claude account and need to continue conversations seamlessly between them.

Claude Code stores project contexts using absolute paths as folder names:

~/.claude/projects/-Users-alex-kumar-Desktop-api-gateway/

Inside sessions-index.json and .jsonl files, paths are also hardcoded:

{
  "fullPath": "/Users/alex.kumar/.claude/projects/-Users-alex-kumar-Desktop-api-gateway/abc123.jsonl",
  "projectPath": "/Users/alex.kumar/Desktop/api-gateway"
}

If I copy my .claude/ folder to another machine with a different macOS username (e.g. alexk instead of alex.kumar), all sessions break — Claude can't find or resume any conversations because the encoded paths don't match the new system.

Memory files (markdown) are already fully portable across machines. Session data is not, solely because of hardcoded absolute paths in folder names and JSON references.

The current workflow requires me to either:

• Ensure both machines have the exact same username and project paths (fragile)
• Manually rename 100+ project folders and find-replace paths in hundreds of JSON files
• Give up on session continuity and only sync memory (losing conversation history)

Proposed Solution

Option A (Preferred): Store paths relative to $HOME

Instead of encoding the full absolute path in the folder name:

-Users-alex-kumar-Desktop-api-gateway

Use a home-relative path:

-Desktop-api-gateway

And resolve the full path at runtime using the current $HOME. Same for references inside sessions-index.json and .jsonl files — store as ~/Desktop/api-gateway and resolve at runtime.

Option B: Add a migration command

claude sessions migrate --old-home /Users/alex.kumar --new-home /Users/alexk

This would:

1. Rename all project folders under ~/.claude/projects/
2. Find-replace path references inside all .json and .jsonl files
3. Allow users to move their .claude/ folder between machines with different usernames

Option C: Path aliases in config

Allow users to define path mappings in settings:

{
  "pathAliases": {
    "/Users/alex.kumar": "/Users/alexk"
  }
}

Claude resolves these at runtime when looking up project contexts.

Alternative Solutions

1. Same username on both machines — Works but requires planning ahead. Not possible if one machine is company-managed with a fixed username.

1. Only sync memory files — Memory is portable and captures ~80% of useful context, but conversation history and session state are lost. You can't /resume on the other machine.

1. Manual folder rename + sed — Technically works but fragile, unsupported, and tedious with 100+ project folders and hundreds of JSON files to rewrite.

1. Remote Control — Controls Machine A from Machine B, but requires Machine A to be running. Doesn't work when Machine A is off or sleeping.

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

1. I'm working on a Go microservice (~/Desktop/api-gateway) on my work laptop (username: alex.kumar)
2. Over several weeks, I've had 100+ Claude Code sessions building deep project context
3. Claude has project-specific memory (patterns, API contracts, architecture decisions)
4. I need to continue the same work on my personal laptop (username: alexk)
5. I clone the repo to the same relative path (~/Desktop/api-gateway)
6. I copy ~/.claude/ to the personal laptop
7. All sessions break because the project folder is named -Users-alex-kumar-Desktop-api-gateway but the new machine expects -Users-alexk-Desktop-api-gateway
8. With this feature, paths would resolve relative to $HOME, and I could claude --resume on my personal laptop and pick up exactly where I left off
9. This would save me from losing weeks of accumulated conversation context every time I switch machines

Additional Context

What's already portable (works great)

• ~/.claude/CLAUDE.md — global rules
• ~/.claude/settings.json — permissions, plugins, hooks
• ~/.claude/plans/ — implementation plans
• ~/.claude/projects/*/memory/ — project-specific memories (just .md files)
• ~/.claude/hooks/ and ~/.claude/commands/ — custom hooks and commands

What breaks

• ~/.claude/projects/ folder names (encode absolute path with username)
• sessions-index.json → fullPath, projectPath, firstPrompt fields
• .jsonl session files → file path references in conversation transcripts