[FEATURE] Persist --add-dir workspace configuration (.claude-workspace file)

Problem

When working on cross-project tasks (e.g., a fullstack feature spanning frontend and backend repos), --add-dir is the right tool — it brings multiple directories into a single Claude Code session. However, the configuration is ephemeral:

# Every time I start a new session, I have to re-specify all directories
claude --add-dir ~/frontend --add-dir ~/backend --add-dir ~/shared-lib

There is no built-in way to save and reload a multi-directory workspace. Users resort to shell aliases or wrapper scripts, which are fragile and not shareable with teammates.

Proposed Solution

Introduce a .claude-workspace file (or similar) that persists the multi-directory configuration:

// .claude-workspace
{
  "directories": [
    { "path": "../frontend" },
    { "path": "../backend" },
    { "path": "../shared-lib" }
  ]
}

Usage

# Load workspace from file
claude --workspace ./my-project.claude-workspace

# Or auto-detect if .claude-workspace exists in current directory
claude

Key behaviors

• Relative paths — so the file is portable and can be checked into a repo or shared
• Auto-detection — if a .claude-workspace file exists in the current directory, load it automatically
• Per-directory CLAUDE.md — each added directory's CLAUDE.md should be respected (this is already a gap with --add-dir today)

Current Workarounds

1. Shell alias: alias claude-myproject="claude --add-dir ~/a --add-dir ~/b" — not shareable, not portable
2. /add-dir in session: manually type /add-dir after every session start — tedious
3. claude --resume: restores previous session including added dirs, but only works for continuing the same conversation

Why This Matters

Modern development often involves multiple repositories (microservices, monorepo packages, frontend + backend, shared libraries). The --add-dir feature already solves the "how" — this proposal just adds the "remember" part, similar to how VS Code's .code-workspace files persist multi-root workspace configurations.

Environment

• Claude Code 2.1.92+
• macOS / Linux / Windows
• CLI and IDE extensions

Related

• #36123 — Support /add-dir in IDE extensions
• #43262 — Workspace-level session save/restore (multi-session persistence)
• #36761 — Enable /add-dir outside the agent loop