[FEATURE] Session isolation: Use session ID instead of working directory for session storage

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

Problem Description

Currently, Claude Code organizes session data by working directory path:

~/.claude/projects/[encoded-working-directory]/
    ├── [session-id-1].jsonl
    ├── [session-id-2].jsonl
    └── sessions-index.json

This design causes session conflicts when running multiple Claude Code windows in the same directory. Multiple concurrent sessions in the same working directory share the same project space and may interfere with each other.

Steps to Reproduce

1. Open terminal window A and run claude in /path/to/project
2. Open terminal window B and run claude in the same /path/to/project
3. Both sessions write to the same project directory under ~/.claude/projects/
4. Session state and history can become mixed or corrupted

Current Architecture Issues

1. Lack of isolation: Multiple sessions in the same directory share project space
2. Concurrent access conflicts: Multiple processes may read/write sessions-index.json simultaneously
3. Semantic mismatch: Sessions should be independent entities, not grouped by working directory
4. Confusing behavior: Users expect each terminal window to have an isolated session

Proposed Solution

Proposed Solution

Reorganize session storage to use session ID as the primary dimension:

~/.claude/sessions/
    ├── [session-id-1]/
    │   ├── session.jsonl
    │   ├── metadata.json  (includes working_dir, created_at, etc.)
    │   └── env/
    └── [session-id-2]/
        ├── session.jsonl
        ├── metadata.json
        └── env/

Benefits

1. Complete isolation: Each session ID gets its own directory with zero conflicts
2. Better concurrency: Multiple windows naturally isolated, safe for parallel use
3. Clearer semantics: Session is the primary concept, working directory is just metadata
4. Easier cleanup: Delete a session by removing one directory
5. Better debugging: Session state is self-contained and easier to inspect

Backward Compatibility

• Keep a migration path from old structure to new structure
• Store working_dir in session metadata for reference
• Optionally maintain a reverse index: ~/.claude/projects-index.json mapping working directories to session IDs

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

Additional Context

Session IDs already exist in the current implementation (visible in .jsonl filenames), but they're organized under working directory paths. This proposal simply elevates session ID to be the primary organizational dimensi
on.

Related Use Cases

• Running multiple Claude Code instances for different tasks in the same project
• Parallel development workflows (e.g., one window for implementation, another for research)
• Team environments where multiple developers work in the same codebase

---

Environment:

• Claude Code version: 2.1.29
• OS: macOS 15 (Darwin 24.3.0)