Follow XDG Base Directory specification properly - move runtime/cache files out of $XDG_CONFIG_HOME
Open 💬 20 comments Opened Jun 20, 2025 by choplin
Description
Claude Code currently places all its files in $XDG_CONFIG_HOME/claude, but this violates the XDG Base Directory specification. According to the spec, $XDG_CONFIG_HOME should only contain user-specific configuration files, not runtime data, cache files, or state.
This helps users to keep their configuration files separate from runtime data and cache, making it easier to manage backups and version control.
Current State
$XDG_CONFIG_HOME/claude/
├── CLAUDE.md ✓ (user config - correct location)
├── commands/ ✓ (user config - correct location)
├── settings.json ✓ (user config - correct location)
├── local/ ✗ (runtime data - should be in $XDG_DATA_HOME)
├── projects/ ✗ (state data - should be in $XDG_STATE_HOME)
├── statsig/ ✗ (cache/state - should be in $XDG_STATE_HOME or $XDG_CACHE_HOME)
└── todos/ ✗ (state data - should be in $XDG_STATE_HOME)Proposed Solution
Reorganize the directory structure to follow XDG Base Directory specification:
$XDG_CONFIG_HOME/claude/: Keep only user configuration
CLAUDE.mdcommands/settings.jsonscripts/(user-defined scripts)
$XDG_DATA_HOME/claude/: Runtime datalocal/(contains node_modules, package.json, etc.)$XDG_STATE_HOME/claude/: Persistent stateprojects/todos/statsig/
Benefits
- Follows standard Linux/Unix conventions
- Makes backup easier (users can backup only
$XDG_CONFIG_HOMEfor configurations) - Allows users to exclude runtime/cache data from version control
- Cleaner separation of concerns
20 Comments
Don't forget the claude.json and claude.json.backup files! Those belong in
$XDG_STATE_HOME/claude/alsoAny news on this? I was quite surprised to find claude just dumping everything in my home directory, not to mention the fact it cannot handle symlinks apparently...
+1
+1
This seems to have moved further away from XDG Base Directory standards. Claude is now creating top level ~/.claude.json and ~/.claude.json.backup files.
My poor home dir already has enough dot files from before the standard was common.
Also please split out user confgured things like color profile, permissions etc, slash commands, etc.. from data.
So that it's possible to manage common settings via nixos or chezmoi across machines.
Thank you!
+1
It should note that
settings.jsoncontains state/runtime data too, likealwaysThinkingEnabledwhich switches every time one doesshift+tab. I can't easily sync my config files across my machines without this polluting my diff every time.In my opinion not really the best design choice either... the xdg family of folders caters for these requirements: config, cache, and local etc...
+1
The link provided in the opening comment of this issue is returning a 404. There are other XDG variables that should be mentioned, they are described in links below.
One specifically that should be mentioned is
$XDG_RUNTIME_DIRto be used for "non-essential runtime files"https://specifications.freedesktop.org/basedir/latest/
https://wiki.archlinux.org/title/XDG_Base_Directory
@InSuperposition Thanks! I fixed the link.
any process?
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.
active
I think it was noted above, but CC no longer seems to use
XDG_CONFIG_HOMEor the XDG default, so the need is even more expansive now.It's worth noting the optics of this one. Claude Code is a tool that writes XDG-compliant configurations for other people's software on demand. Ask it to set up a CLI tool and it'll dutifully put config in ~/.config/, data in ~/.local/share/, and cache in ~/.cache/.
It knows the spec. It can explain the spec. It can refactor an entire project to follow the spec.
And then it drops .claude.json in $HOME right next to its own .claude/ directory.
This has been open since May 2025. The fix is trivial — respect XDG_CONFIG_HOME with ~/.claude/ as fallback, and move the loose root-level files inside the config directory. This is maybe 10 lines of code in a tool that generates thousands of lines a day.
Leaving this unfixed for 8+ months not so quietly says "we can't do for ourselves what we promise to do for you." That's not a great message for a product whose entire value proposition is writing good code.
This kind of hits the nail on the head for me. The entire issue screams January-2024-level vibe coding slop, which the entire industry is eye-rolling over. How hard can it? Why is this an issue in a supposedly professional-grade software?
Just stopping by to see if anything has happened, with 6,400 open issues you would think that cleaning up a backlog of issues would be a great candidate for, oh I don't know, maybe a browser aware coding agent to do some triage?
Recently started using calude-code and I'm very surprised that an issue like this needs to exist.
It is indeed strange, this would be
a) a non-issue if Anthropics would have just 100% vibe-coded claude-code. It would very likely have gotten this right from the get-go, and
b) instructing an agent to default to
$XDG_CONFIG_HOME/claudeand fall back to a pre-existing~/.claudewould probably be a 1h task now (actually, even without AI).Bonus points if they ask the agent to split out the runtime-state into where it belongs (would make proper config syncing between machines more feasible).
But not forcing 2 to 3 items into the users home folder would already be a huge win.
Maybe it's really the sheer amount of open issues here, they may not be able to keep up. Still unfortunate.
Sill waiting on this
that is ironic that leading AI coding tool is not intelligent enough to follow established standards :)
It's a shame!