[BUG] CLAUDE_CONFIG_DIR environment variable behavior unclear - still creates local .claude/ directories

CLAUDE_CONFIG_DIR seems to work for me in all cases, aside from with the vscode ide. I'm getting the .claude/ide folder created regardless of whether this is set.

Hi, the current behavior of Claude Code with CLAUDE_CONFIG_DIR actually works quite well for XDG Base Directory compliance, but I believe the naming and documentation could be clarified. Here's what I'd propose:

Current Behavior (which I think is mostly correct!)

• User configuration files (skills, agents, commands) remain in ~/.config/claude-code/ - this is the correct location per XDG spec and allows version control
• State/runtime files (currently in ~/.claude/) can be relocated via $CLAUDE_CONFIG_DIR to follow XDG conventions (e.g., ~/.local/state/claude-code/)
• Project-specific files (.claude/settings.local.json) remain in project directories - this is correct for project-scoped configuration
• Exception: ~/.claude.json is hardcoded to the home directory and is not affected by CLAUDE_CONFIG_DIR

This separation is actually quite good and follows best practices, though the .claude.json location is problematic.

Proposed Improvements

1. Rename the environment variable

CLAUDE_CONFIG_DIR → CLAUDE_STATE_DIR

This better reflects what it actually controls: runtime state, not user configuration. The XDG Base Directory spec distinguishes between:

• $XDG_CONFIG_HOME (default: ~/.config) - user configuration files that should be preserved
• $XDG_STATE_HOME (default: ~/.local/state) - state data that can be regenerated but contains valuable user-specific state

What CLAUDE_CONFIG_DIR currently relocates (history, projects, shell-snapshots, statsig, etc.) clearly fits the "state" category per XDG.

2. Move settings.json to the config directory

Currently settings.json lives in the state directory (~/.claude/settings.json), but it should live in ~/.config/claude-code/settings.json alongside other user configuration files (skills, agents, commands). The settings.json file contains user preferences and configuration that should be:

• Preserved across reinstalls
• Version controlled
• Synced across machines

This is configuration, not state.

3. Make ~/.claude.json respect CLAUDE_STATE_DIR

Currently, ~/.claude.json is hardcoded to the home directory and doesn't respect CLAUDE_CONFIG_DIR. This file contains:

• API keys and authentication
• MCP server configurations
• Project history
• Approved/rejected API key responses

This is clearly state data (especially the auth tokens and project history), so it should be relocatable to $CLAUDE_STATE_DIR/claude.json (without the leading dot, since it's no longer in ~/).

Proposed structure:

~/.config/claude-code/
├── settings.json         # User settings (moved from state dir)
├── agents/
├── commands/
└── skills/

~/.local/state/claude-code/
├── claude.json           # Main state file (moved from ~/.claude.json, renamed)
├── claude.json.backup
├── history.jsonl
├── projects/
├── shell-snapshots/
└── ...

4. Document the intended behavior

Please officially document:

• The purpose of CLAUDE_STATE_DIR (or keep CLAUDE_CONFIG_DIR if you prefer that name)
• Which files/directories it affects (including ~/.claude.json → $CLAUDE_STATE_DIR/claude.json)
• The distinction between state (relocated) and config (stays in ~/.config/claude-code/)
• That project-local .claude/ directories are intentionally not affected
• Where settings.json should live (config directory)

5. Backward compatibility

For the transition:

• Support both CLAUDE_CONFIG_DIR (deprecated) and CLAUDE_STATE_DIR with a deprecation warning
• Check for claude.json in $CLAUDE_STATE_DIR first, fall back to ~/.claude.json if not found
• Auto-migrate settings.json from state to config directory with a one-time migration prompt
• Auto-migrate ~/.claude.json to $CLAUDE_STATE_DIR/claude.json on first run after update
• Provide migration guidance in the documentation

Why This Matters

XDG Base Directory compliance is important for:

• Backup strategies: State vs. config have different backup requirements
• Multi-machine sync: Config should sync, state typically shouldn't
• Clean home directories: Following XDG keeps ~/ uncluttered
• System integration: Many tools and scripts expect XDG compliance

The current behavior is very close to getting this right! It just needs:

1. Clearer naming (CLAUDE_STATE_DIR)
2. Moving settings.json to the config directory where it belongs
3. Making ~/.claude.json respect the state directory variable (currently hardcoded to ~/)
4. Official documentation to make it a supported feature rather than an undocumented implementation detail

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

the issue of "CLAUDE_CONFIG_DIR environment variable behavior unclear" is still very much "occurring": the only mention of it i could find in the docs is literally just this: _"Customize where Claude Code stores its configuration and data files"_. if nothing else, because it leaves out the fairly important matter of .claude.json file location undocumented - which is a shame, because that behaviour is... surprising, to say the least.

as of v2.0.42-74, when $CLAUDE_CONFIG_DIR is set - .claude.json ends up in the path $CLAUDE_CONFIG_DIR/.claude.json (_contrary_ to this report above), right next to settings.json, .credentials.json, etc., rather than in the usual $HOME/.claude.json which is _outside_ of $HOME/.claude/ dir, when that var is unset. that becomes outright confusing when CLAUDE_CONFIG_DIR=$HOME/.claude, because then you end up with some systems that use $HOME/.claude.json, some use $HOME/.claude/.claude.json while they both have the rest of the files in $HOME/.claude. not what i would call a very self-consistent behaviour, which adds to the confusion cause by it being undocumented.

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

This issue was closed incorrectly despite recent human comments. This behavior of the bot is reported at https://github.com/anthropics/claude-code/issues/16497. Please upvote that issue, so maybe it gets noticed.

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.