Docs about user config directory `~/.claude` appear to contradict actual CLI app behavior

Confirmed this was broken in @1.0.28

For those of you who might be struggling to get your environment to work try the following:

npx @anthropic-ai/claude-code@1.0.27

@joshuadavidthomas hope this works for you too!

Hi! We recently got rid of the /user: and /project: prefixes. Your commands should still be available. eg.

$ cat ~/.claude/commands/abc.md
a test command

$ claude
> /abc  # before: /user:abc

Can folks confirm this works ok? Docs incoming.

No, nothing is being loaded from ~/.claude/, not user commands and /status isn’t showing ~/.claude/CLAUDE.md as being loaded. 1.0.27 has the removal of the prefix that you’re referencing and works ok. 1.0.28 and 1.0.29 are broken for me.

Hi! We recently got rid of the /user: and /project: prefixes. Your commands should still be available. eg. $ cat ~/.claude/commands/abc.md a test command $ claude > /abc # before: /user:abc Can folks confirm this works ok? Docs incoming.

@joshuadavidthomas @johnhampton ~This (at least the bit where \~/.claude was not being read afaict) seems to be fixed in 1.0.30 fyi!~

@bcherny I believe there were several aspects to the issue here but the trouble I was experiencing seems to be fixed. Thanks to the team behind Claude Code it really is a great product.

Update: it seems claude code now reads \~/.config/claude instead of \~/.claude my apologies for the confusion.

@joshuadavidthomas @johnhampton ~This (at least the bit where \~/.claude was not being read afaict) seems to be fixed in 1.0.30 fyi!~ @bcherny I believe there were several aspects to the issue here but the trouble I was experiencing seems to be fixed. Thanks to the team behind Claude Code it really is a great product. Update: it seems claude code now reads \~/.config/claude instead of \~/.claude my apologies for the confusion.

Not sure if you're talking about several aspects in regard to my original issue or yours, but to be clear there's only one aspect to mine. Before I updated, I had a bunch of custom commands and a CLAUDE.md in the place the docs said to put my personal user config ~/.claude and everything was working fine. After updating they seemed to no longer be visible to the application. That's it.

If they've decided to move the folder the standard XDG location under the ~/.config directory, that's fine I suppose. It's pretty disappointing though the lack of communication or the simple act of keeping the docs up to date with the actual behavior of the application. The official docs still list ~/.claude directory as the location to put user settings.

I moved ~/.claude to ~/.config/claude and my user slash commands were accessible and my user CLAUDE.md was loaded. But as @joshuadavidthomas noted, the docs still indicate that ~/.claude is the correct location for these files.

I moved ~/.claude to ~/.config/claude and my user slash commands were accessible and my user CLAUDE.md was loaded. But as @joshuadavidthomas noted, the docs still indicate that ~/.claude is the correct location for these files.

Excellent! thank you.

Edited the issue title and body with a more accurate description.

If this is intentional, this is a pretty poor handling of it. Introducing a breaking change in a patch version update with no documentation updates or deprecation warning.. why even use SemVer at that point? Just switch to CalVer or, hell, just a single incrementing v1, v2, v3 versioning scheme.

For me neither keeping commands under ~/.claude/commands/foo.md nor ~/.config/claude/commands/foo.md work

version: 1.0.31 (Claude Code)

Been having this issue for a week. Seems bizarre that Anthropic haven't updated their official docs about it.

Setting CLAUDE_CONFIG_DIR=$HOME/.claude in my shell seems to return the old behavior. I ended up adding this as a fish alias:

alias claude="env CLAUDE_CONFIG_DIR=$HOME/.claude $HOME/.claude/local/claude"

And it breaks again without warning. Now the commands in ~/.config/claude/commands stopped showing up. I can't get it to work from either directory ~/.config/claude/commands/ or `~/.claude/commands/.

EDIT:
@joshuadavidthomas solution of exporting config using CLAUDE_CONFIG_DIR env var worked for me.

Ah, looks like this issue has been bubbling as issue for a while! #1455 was opened a month ago and seems related to this issue (as well as many others).

Frustrating because out of all the agentic CLI tools, Claude Code is clearly the best at the moment, but the actual software development practices around it feel lacking (misuse of SemVer, confusing/misleading/potentially-out-of-date docs, inconsistently updated and incomplete CHANGELOG, etc.). Sorry to the devs behind the tool for that blunt assessment, but well, it's how I feel. 🤷‍♂️

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.