Add environment variable to configure .claude config directory location

Please also consider the file ~/.claude.json. For example it has its value when using a docker container and we want to mount claude config, without mounting the whole home directory

+1 for this. This behavior is really annoying. At the very least, XDG_CONFIG_DIR should be used for the config - as is the convention on Linux!

CLAUDE_CONFIG_DIR already exists and works — I built a CLI that makes it easy to manage:

npm install -g @synth1s/cloak

cloak create work    # saves current session to ~/.cloak/profiles/work/
cloak create home    # saves another to ~/.cloak/profiles/home/
cloak switch work    # sets CLAUDE_CONFIG_DIR for you

Each profile is a complete, isolated directory. Works in Docker too — just mount the profile directory as CLAUDE_CONFIG_DIR.

https://github.com/synth1s/cloak

+1.

~/.claude/CLAUDE.md is just too much noise for things not related to programming. So while my home directory needs to be defaulting to programming, I need an alternate one for non-programming tasks.

@goulartfs thanks for pointing out the existence of the env variable.
Also, appreciate the work you've done, but do we really need to install an untrusted nodejs program to simply change an env variable?

CLAUDE_CONFIG_DIR - Aha, I guess I missed that! So should this ticket be closed?

Fair point! You absolutely can use CLAUDE_CONFIG_DIR directly — no tool needed.

Cloak just wraps the manual steps: creating profile directories, copying config files, switching the env var across shell sessions, and handling the shell integration (since a child process can't modify the parent's env).

If you're comfortable managing that yourself, the env var alone works perfectly. Cloak is for those who prefer not to think about it.

claude /context shows that if you have a ~/.claude/CLAUDE.md even when CLAUDE_CONFIG_DIR=$HOME/.claude-raw/ it still uses ~/.claude/CLAUDE.md and (as far as I can tell) ignores the one in CLAUDE_CONFIG_DIR.

This is probably a separate bug - It means that if you have ~/.claude/CLAUDE.md it will always work in place of any $CLAUDE_CONFIG_DIR/CLAUDE.md you might have.

To work around that I've done the following, which allows you to separate CLAUDE.md by instance and still share the rest of the state:

DISCLAIMER: I have tested this procedure on my system, but not verbatim. I hand typed the following and have not tested it directly, so you're on your own for making this work right.

_If you break things it's not my fault!_ Verify my work before you perform any changes.

mkdir .claude-code
cd .claude-code

# Symlink all of the files and hidden files. 
ln -s ../.claude/* .
ln -s ../.claude/.* .

# CLAUDE_CONFIG_DIR directories put the claude.json config in that directory, but normal `claude` use lives outside the directory in your home directory still. 
ln -s ../.claude.json 

# remove the .claude-code/ symlink and put the instructions where they go. 
# this is the magic. 
# Be careful not to delete your instructions if you're not in the right directory.
# You should only be deleting a symlink and then moving the existing file to the new directory:
rm CLAUDE.md #<< This is a simlink!
mv ../.claude/CLAUDE.md . # This is a file. 

In .bashrc - update Claude so it sees the correct files:

export CLAUDE_CONFIG_DIR=$HOME/.claude-code

Try it:

claude /context
...
Memory files · /memory
└ ~/.claude-code/CLAUDE.md: 9.2k tokens

# now make .claude-raw
cd ~/
mkdir .claude-raw
cd .claude-raw
ln -s ../.claude/* .
ln -s ../.claude/.* .
ln -s ../.claude.json 
# rm CLAUDE.md - This shouldn't exist since we moved it earlier. 

Write a script to run the claude-raw instance if you don't want to have your default CLAUDE.md. You could probably do this with an alias if you prefer.

#!/bin/sh

export CLAUDE_CONFIG_DIR=$HOME/.claude-raw/
exec claude "$@"

Try it:

claude-raw /context
...
# These lines are absent: 
Memory files · /memory << 
└ ~/.claude/CLAUDE.md: 9.2k tokens # << not listed!

If you did this right, then you can run claude-raw /context and it will not reference ~/.claude-code/CLAUDE.md but claude /context will.

If you want any other separation between the instances, all you have to do is break the symlinks. The nice thing about this is that all the configurations, settings, and state exist across all instances. The only thing we've overwritten here are the instructions.

Hello, I had Claude write out the feature request from my pain points:

Feature Request: Make Claude Desktop Project Storage Location Configurable

Problem Statement

Claude Desktop currently saves all projects, artifacts, schedules, and metadata to a hardcoded default location: ~/Documents/Claude/Projects/ (on macOS/Linux) or C:\Users\[username]\Documents\Claude\ (on Windows).

Users cannot change this default location, which creates friction in several scenarios:

• Permission issues: Storing projects outside the default location causes permission conflicts during development and plugin/skill building
• File organization: Users with different organizational needs can't consolidate their Claude projects with other work directories
• Cross-machine workflows: Users with portable home directories or shared filesystems can't easily point all machines to a single project location
• Workspace separation: Teams or power users managing multiple workspace directories have no way to set a persistent default for each use case

Current Impact

• Users experience unexpected permission errors when building skills or plugins stored outside the default location
• The only workaround is symbolic links/junctions, which is fragile and not discoverable
• New users may accidentally create projects in non-standard locations, leading to confusion and support questions
• There's no way to set up reliable multi-machine project synchronization to a custom location

Additional context - Cowork use case:

This issue is particularly acute when using Claude Desktop's Cowork feature. Because Cowork executes code and file operations directly, permission conflicts from non-standard project locations cause task failures and make it unreliable for building and testing skills/plugins in custom directories.

Suggested Solution

Add a Settings option in Claude Desktop UI (e.g., Settings > Projects > Default Project Location) that allows users to:

1. View the current default location
2. Browse and select a custom directory
3. Optionally migrate existing projects to the new location

Alternatively, support configuration via:

• claude_desktop_config.json with a defaultProjectPath field
• Environment variable like CLAUDE_PROJECTS_DIR (similar to how other tools like CLAUDE_CONFIG_DIR work)

Suggested Config Format

{
  "defaultProjectPath": "/Users/username/my-claude-projects",
  "mcpServers": { ... }
}

Or via environment variable:

export CLAUDE_PROJECTS_DIR="$HOME/my-claude-projects"

Use Cases

1. Developer building Claude skills/plugins: Needs projects in a workspace directory with proper permission inheritance to avoid build errors
2. Knowledge worker: Wants all Claude projects alongside other work (research, notes, etc.) in a unified workspace
3. Cross-machine setup: Uses Dropbox/OneDrive/iCloud to sync a single projects folder across Mac, Windows, and Linux machines
4. Team workspace: Manages shared Claude projects in a centralized location accessible to team members
5. Portable environment: Works from a portable home directory or network-mounted home and needs predictable project paths

Backwards Compatibility

• Default behavior should remain unchanged (projects still save to ~/Documents/Claude/Projects/)
• If a custom path is set for the first time, optionally offer to migrate existing projects
• If the custom path becomes inaccessible, Claude Desktop should fall back to the default with a clear warning

Related Issues

Users have requested similar configurability for:

• Cowork output directories ([Issue #47179](https://github.com/anthropics/claude-code/issues/47179))
• Cowork default workspace folder ([Issue #34604](https://github.com/anthropics/claude-code/issues/34604))
• Claude Code config directory ([Issue #25762](https://github.com/anthropics/claude-code/issues/25762))

This suggests a broader need for path configurability across Claude's product family.

Expected Benefit

• Reduces permission errors and build failures
• Enables cleaner workspace organization
• Supports power users and teams with complex setups
• Aligns with how other developer tools (VS Code, Git, etc.) handle configuration
• Unlocks cross-machine synchronization workflows

Hello, I had Claude write out the feature request

The feature already exists. See CLAUDE_CONFIG_DIR and comment above: https://github.com/anthropics/claude-code/issues/25762#issuecomment-4101143324

I sort of think this should be closed unless there's some other issue people are trying to solve.

You could also use a symbolic link to solve the problem, but just removing the entire claude directory is probably sufficient.

I just realized you're asking about the project's directory specifically, in which case there isn't a feature for that, but moving the dot claud directory is probably enough for most users. The report that you provided above should probably be in a new ticket.

Use case: solo developer, multiple personal machines, no multi-account need

I'm not after multi-account isolation or Docker mounts — just running Claude Code on more than one of my own machines (a primary workstation and a secondary laptop) and having my customizations follow me. Same user, same OS, same source tree (via git). The only thing that breaks the two-machine workflow is ~/.claude/: agents, slash commands, hooks, settings, and memory all stay on whichever machine I touched last.

What I've actually built around this: my project memory under ~/.claude/projects/<project>/memory/ is a Windows directory junction pointing at a git-backed location in the project repo. git pull on either machine and memory follows. It works because it's plain Markdown and the path is stable. But it doesn't help with agents/, commands/, hooks/, settings.json, or keybindings.json — all of which are also customizations I'd want shared.

CLAUDE_CONFIG_DIR would be the obvious answer, except the open bugs on this repo (#47056, #55065, #55249, #55456, #42217, #30538) make it clear it's not consistently honored across the CLI, subagents, MCP loading, and the VS Code extension. So in practice the env var doesn't yet provide a path to "put .claude somewhere portable and have everything just work." #50886 (.claude symlinked into a OneDrive-synced folder breaks with EEXIST) closes off the obvious cloud-sync workaround on Windows too.

What would unblock the two-machine workflow (in priority order):

Make CLAUDE_CONFIG_DIR consistently relocate everything Claude Code writes — including ~/.claude.json, subagent state, MCP config, IDE lock files. Treat the open bugs above as the implementation checklist.
Document which subdirectories are designed to be portable across machines vs. which are explicitly machine-local (auth, transcripts, telemetry). Without that, building a dotfiles-style sync repo is guesswork.
Stretch: a first-class claude config sync or similar that handles the safe-vs-local split explicitly.
The friction is real enough today that I've effectively pinned all my Claude Code work to one machine, even though my second machine is otherwise capable and I'd otherwise use it daily. I'd guess the population of "developers with a side machine" is non-trivial.