[FEATURE] Allow configuring the Cowork workspace base path (Documents/Claude)

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/54859
2. https://github.com/anthropics/claude-code/issues/54138
3. https://github.com/anthropics/claude-code/issues/52496

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

These are related but not duplicates. Each addresses a specific symptom:

#54859 covers the Scheduled path only
#54138 and #52496 cover the Artifacts path only

This issue (#57177) requests a single configurable base path setting that would resolve all three in one fix, rather than patching each hardcoded path individually. Closing this as a duplicate would lose the consolidated feature request. Please keep open.

The same hardcoded paths create problems on Windows platform too (discussed in https://github.com/anthropics/claude-code/issues/54138).
This issue should provide a fix for both platforms.

Proposal: configurable Cowork workspace paths (consolidates #57177, #54859, #54138, #52496)

Root cause (shared across all four issues)

Claude Desktop / Cowork resolves three storage roots from a single hardcoded base, ~/Documents/Claude/:

• ~/Documents/Claude/ — Cowork workspace base
• ~/Documents/Claude/Artifacts/ — Live Artifacts mount source
• ~/Documents/Claude/Scheduled/ — scheduled task definitions

There is no user-facing setting and no claude_desktop_config.json field to override any of these. The result is a class of failures on otherwise-supported setups: macOS TCC denial on ~/Documents, OneDrive-synced Documents on macOS/Windows, Windows Documents redirected to D:\, MDM-restricted corporate Macs, and user folders kept outside ~/Documents by preference.

Proposed fix

1. New default location (no config required)

Move the canonical storage out of the TCC-gated, user-redirectable Documents folder:

• macOS: ~/Library/Application Support/Claude/Cowork/
• Windows: %APPDATA%\Claude\Cowork\
• Linux: $XDG_DATA_HOME/Claude/Cowork/ (fallback ~/.local/share/Claude/Cowork/)

This is consistent with where Claude Desktop already stores vm_bundles/, MCP configs, and other app state. It eliminates the TCC, OneDrive, and cross-drive failure modes without any user configuration.

2. Single configurable base path in claude_desktop_config.json

{
  "cowork": {
    "workspaceRoot": "~/Documents/Systems/Claude",
    "artifactsRoot": "~/Documents/Systems/Claude/Artifacts",
    "scheduledTasksRoot": "~/Documents/Systems/Claude/Scheduled"
  }
}

Resolution rules:

• If cowork.workspaceRoot is set and the sub-roots are not, derive artifactsRoot and scheduledTasksRoot as <workspaceRoot>/Artifacts and <workspaceRoot>/Scheduled.
• Any sub-root explicitly set overrides the derived value.
• ~ and environment variables ($HOME, %USERPROFILE%, %APPDATA%) are expanded.
• Paths are validated at startup: must be writable, must not cross a virtiofs-incompatible mount (OneDrive/iCloud Drive cloud-only files, cross-drive on Windows). On failure, fall back to the default and surface a one-time notification.

3. Equivalent UI setting

Settings → Cowork → "Workspace location" with a folder picker, writing to the same config field. UI and config must be a single source of truth.

4. Per-session override (fixes #54138, #52496)

When the user selects a project folder via "Use an existing folder", Artifacts and any per-session storage MUST mount relative to that folder (e.g. <sessionFolder>/.claude-artifacts/), not the global artifactsRoot. The global root is only used for sessions without a selected folder.

5. Migration

On first launch after the change:

• If ~/Documents/Claude/ exists and the new default location does not, move contents and leave a symlink at the old path for backward compatibility.
• If the user has set cowork.workspaceRoot, migrate to that location instead.
• Existing scheduled-tasks.json entries with absolute filePath values are rewritten to point at the new location.

Why one PR instead of four fixes

The four issues are symptoms of one architectural choice (hardcoded base under a TCC/cloud-sync-prone folder with no override). Fixing each surface independently leaves the other three reachable through different code paths. A single resolution layer that reads claude_desktop_config.json, falls back to the platform-appropriate app-data location, and honours per-session folder selection closes all four.

Acceptance criteria

• Default install on macOS with Documents access denied → Cowork, Scheduled tasks, and Artifacts all work.
• Windows with Documents redirected to D:\ → same.
• macOS or Windows with OneDrive-synced Documents → same.
• User sets cowork.workspaceRoot to an arbitrary path → all three storage areas land under it.
• User opens a session with "Use an existing folder" → Artifacts mount inside the selected folder, not the global root.
• Existing users with content at ~/Documents/Claude/ see no data loss after upgrade.

This is fixed in the latest version, thank you!

+1 — and a variant worth flagging: because the Cowork working dir (~/Documents/Claude) is hardcoded AND contains protected children (Documents\Claude\Scheduled and Documents\Claude\Artifacts), the mounter hard-refuses to mount the parent Documents\Claude at all:

"Directory C:\Users\AlexLee\Documents\Claude overlaps a protected host location (…\Claude\Scheduled) and cannot be mounted."

I run an automation engine inside that folder (its scripts, top-level engine_integrity.json manifest, Outputs/, Artifacts/). With the parent unmountable, no interactive session can reach the engine root or its top-level manifest, so engine maintenance can't run.

Notes:

• /add-dir on subfolders doesn't help: subfolder grants mount as mnt/<name>, never mnt/Claude, and the top-level manifest file isn't inside any subfolder. Two needed dirs (Artifacts, Scheduled) are themselves protected and can't be added at all.
• symlinks/junctions are resolved to the real path and re-rejected (Windows).
• It worked until an app restart: pre-existing scheduled tasks keep their recorded full-Claude mount across restarts, but interactive sessions and newly-created/updated tasks only get the (now subfolder-only) grant — so ad-hoc maintenance is locked out.

Repro: put any project in ~/Documents/Claude (or any folder containing a protected child) → try to mount the parent → hard refusal; mounting a child yields mnt/<child>, not mnt/Claude.

Ask (either fixes it): (1) make the workspace base path configurable, or (2) allow mounting a parent with protected children auto-excluded.

Hitting this after the July 2026 Chat/Cowork merge. My setup keeps shared skill assets (a config JSON with API tokens, a service-account key, an SSH key) at the Cowork projects root, ~/Documents/Claude. Skills across several projects read those files via the connected-folder mount.
Post-merge the app now refuses to add ~/Documents/Claude as a connected folder to a project, rejecting it as a protected/overlapping location because it's the projects root itself. Only its subfolders can be mounted. Projects that had the root grandfathered in still work; any project created or re-configured after the merge can't reach the shared files, so those skills fail.
The symlink workaround doesn't help: the folder picker resolves the symlink back to the real path and re-blocks it (same as #24964).
Requesting either a configurable Cowork base path, or the ability to explicitly add the projects root (or an arbitrary chosen shared folder) as a connected folder to any project. Right now there's no supported way to share one folder of credentials across projects.
macOS, desktop app.