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

[liuguangyong93]

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

• Support /add-dir in IDE extensions (VS Code / JetBrains) #36123 — Support /add-dir in IDE extensions
• Feature: Workspace-level session save/restore (multi-session persistence) #43262 — Workspace-level session save/restore (multi-session persistence)
• [FEATURE] enable "/add-dir" to be used outside the agent loop like "/btw" #36761 — Enable /add-dir outside the agent loop

[github-actions]

Found 3 possible duplicate issues:

1. [FEATURE] Isolated multi-repo environments for Claude Code #44656
2. Allow user-defined named projects that map to multiple directories #24980
3. Feature request: /add-folder command for multi-folder workspace support #38309

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

[github-actions]

This issue has been automatically closed as a duplicate of #44656.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.