Multi-folder workspace support in Claude Desktop for cross-repo dev

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported in this form
• [x] This is a single feature request (please file separate requests for different features)
• [x] I am using the latest version of Claude Code

Searched related: #38309 (closed not_planned, /add-folder command — lighter scope, didn't address Desktop GUI), #51276 (open Desktop bug confirming the multi-repo workspace layout is in active use), #52956 (closed — references userSelectedFolders in Cowork as evidence Anthropic already prototypes multi-folder concepts).

Problem Statement

Claude Desktop's single-folder-per-session model is a hard ceiling for cross-repo development workflows that coordinate multiple sibling git repositories under one parent directory. The pattern looks like:

~/Development/my-workspace/         ← parent (own .git, holds shared AI config)
├── service-a/                      ← own .git, gitignored at parent
├── service-b/                      ← own .git, gitignored at parent
├── frontend/                       ← own .git, gitignored at parent
├── .claude/                        ← shared rules, skills, agents, settings.json
├── CLAUDE.md
└── workspace/                      ← coordination metadata, group definitions

This layout is widely used by teams for monorepo-adjacent workflows where related services need shared AI context (skills, agents, conventions) but remain independent repos with their own branching, CI, and ownership.

When Desktop opens this parent folder:

• ✅ Files in all sub-repos are readable/editable
• ✅ Bash tool can run per-sub-repo git commands (git -C service-a status)
• ❌ Desktop's git UI sidebar shows the outermost git only — sub-repo branches, diffs, and SCM status are invisible
• ❌ No per-sub-repo branch indicator
• ❌ "Source Control" panel is empty when the parent has no .git (see #51276)

When Desktop opens a sub-repo folder directly:

• ✅ Sub-repo's own git UI works
• ❌ Loses access to the parent's .claude/ skills, agents, rules
• ❌ CLAUDE.md @import walk-up to parent is undocumented in Desktop and may not work

The result: Desktop is unusable as a primary surface for cross-repo coordination. Users must run VS Code (with multi-folder .code-workspace and the Anthropic.claude-code extension) in parallel as a passive git monitor, while driving Claude in Desktop. This split-brain workflow defeats Desktop's polish and forces a two-tool dependency for any cross-repo task.

Proposed Solution

Add VS-Code-style multi-folder workspace support to Claude Desktop:

1. Workspace file format — accept a .claude-workspace.json (or reuse .code-workspace) listing multiple folder roots. Open all roots in one Desktop session.

1. Per-folder git UI — Source Control sidebar groups changes by root folder, with a separate branch indicator per folder. Mirror VS Code's behavior.

1. Merged primitive discovery — when multiple roots are loaded, .claude/ settings, skills, agents, and rules from every root are merged at session start. Workspace-style coordination repos contribute their .claude/ to all sibling roots they list.

1. Per-folder CLAUDE.md — each root's CLAUDE.md is loaded and @imports resolve relative to that root. A "primary" root can be designated (the one whose .claude/settings.json provides hooks/permissions for the session).

1. Optional: split-pane per root — extend the existing Cmd+\ split primitive so each pane can be pinned to a different root, with that pane's working directory set accordingly. Each pane's tool calls operate in its assigned root by default.

1. Nice-to-have: TUI parity — once the multi-folder primitive exists in Desktop, expose the same root list in CLI interactive (TUI) mode so users on terminal can also operate across multiple roots in one session. CLI users wouldn't get the per-folder SCM sidebar (no GUI), but would get merged primitive discovery, per-folder CLAUDE.md loading, and the ability to scope a pane (when in split mode) to a specific root. Lower priority than the Desktop work since CLI users have terminal multiplexers as a workaround, but the underlying primitive should be designed surface-agnostic so this comes naturally.

The minimum viable version is items 1–3. Items 4–6 are progressive enhancements.

Alternative Solutions

• /add-folder command (filed as #38309, stale): a lighter-weight CLI-side approach to adding a second folder mid-session. Doesn't address per-folder git UI, which is the load-bearing piece for Desktop visibility.
• Symlink-based workarounds: symlinking a sub-repo's .claude/ to the parent's so opening the sub-repo gives skill access. Brittle, requires per-machine setup, doesn't solve coordination.
• Hybrid Desktop + VS Code: works today but requires two tools, two windows, and manual sync. Negates Desktop's value as a primary surface.
• Multiple Desktop windows on different sub-repos with file-based handoff: works today, but loses skill access in sub-repo windows and requires extensive scaffolding (per-sub-repo .claude/ mirrors, SessionStart hook detection of pending tasks). Multi-folder support eliminates the scaffolding entirely.
• Cowork's existing userSelectedFolders mount mechanism (referenced in #52956) — already supports multiple folders in a Cowork session; could potentially be the foundation for general multi-folder support outside Cowork.

Priority

High - Significant impact on productivity

Feature Category

Other

Filed under "Other" because the available categories (CLI commands, Interactive TUI, File operations, etc.) target the CLI; this request is for the Claude Desktop GUI's "Code" panel and SCM sidebar.

Use Case Example

Concrete scenario from a real workspace:

1. Engineer receives a Jira ticket: "Implement feature X requiring changes to both service-frontend (React Native) and service-backend (Fastify BFF)."

1. Both repos live as gitignored sub-folders under a parent coordination repo with shared .claude/ skills, agents, and group-based context selection rules.

1. Engineer wants to:

• Run a workspace-defined skill (e.g. /feature-dev) in Desktop, which auto-detects cross-repo scope and routes to a parallel-fan-out variant
• See branch creation, commits, and PR opens per sub-repo in the SCM sidebar as Claude works
• Review per-sub-repo diffs in Desktop's diff panel without switching windows
• Land coordinated PRs (one per sub-repo, cross-linked)

1. Today this requires either:

• VS Code as a passive git monitor alongside Desktop (works but defeats single-tool UX)
• Multiple separate Desktop windows with file-based handoff between them (works but requires scaffolding to give sub-repo windows access to workspace skills, and the orchestrator window has no visibility into sub-repo work in real time)
• Bash-tool-only git visibility (Claude reports per-sub-repo state via git -C but the user has no UI to verify)

1. With multi-folder support: one Desktop window. SCM sidebar shows three folders. Branch indicators per folder. Diff panel per folder. Skills, agents, and rules from the parent's .claude/ apply throughout. Cross-repo coordination becomes natively observable.

This pattern is also used by:

• Microservices monorepos (one repo per service, shared .claude/ for cross-service conventions)
• Team-wide AI workspace repos (a coordination repo holds team conventions; engineers mount their feature repos as siblings)
• Plugin / SDK ecosystems (a parent repo with shared review skills, plus N independent SDK repos as siblings)

Additional Context

• Related stale request: #38309 (lighter-weight /add-folder command, closed not_planned)
• Related open bug confirming the layout: #51276 (Desktop sidebar shows no diff when CWD has no .git — repro is "a multi-repo workspace folder containing several sub-repos as siblings")
• Related closed bug referencing partial multi-folder support: #52956 (userSelectedFolders rejection in Cowork — confirms multi-folder mounts already exist in some Anthropic surfaces)
• VS Code .code-workspace reference: https://code.visualstudio.com/docs/editor/multi-root-workspaces — the proven model

The existence of userSelectedFolders in Cowork suggests the multi-folder primitive is already prototyped internally. Surfacing it as a first-class Desktop feature would unlock a workflow that is currently impossible in a single tool.