[BUG] Custom slash commands not working despite correct setup

[pjgoodall]

Description:

Bug Report

Issue

Custom slash commands are not being recognized or executed despite following the official documentation exactly.

Setup

• Created .claude/commands/chkpt.md in project root
• File contains valid command content
• Should be accessible as /<username>:chkpt based on documentation
• Claude confirmed setup was correct in previous session ~/.claude

Expected Behavior

/<username>chkpt should execute the command content from the markdown file

Actual Behavior

Claude does not recognize the custom command and fails to execute it

Impact

• Wasting user money on repeated documentation reads
• Breaking promised functionality
• Inconsistent behavior between sessions

Documentation Reference

https://docs.anthropic.com/en/docs/claude-code/common-workflows#create-project-specific-commands

This is a critical usability issue that makes the custom command feature unreliable.

example

❯ cat ~/.claude/commands/chkpt.md
Create a git checkpoint by:

1. Run git status to show current changes
2. Add all modified and new files to git staging
3. Create a commit with an appropriate message
4. Push the commit to the remote repository

Show me what changes will be committed before proceeding.

[bcherny]

Does /chkpt work?

[MartinMinkov]

I'm running into the same issue, commands are not being registered and autocompleted by the UI even though they are placed in ~/.claude/commands. However, as suggested by @bcherny, running the command name manually (e.g, /my-command even with no autocomplete indicating it's been found) seems to be working.

I've tried the steps outlined in this thread but it didn't not fix the discovery issue in the UI

EDIT: I'm wrong, it doesn't work 😅

[raw1z]

I'm facing the same problem. Yesterday everything was working well. There was a claude code update this morning and since then all the custom slash commands are gone. I'm working on MacOS 15.5 and using claude code (1.0.29 since this morning).

I tried rolling back to a version of claude I knew was working like this:

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/[email protected]

It failed. No matter what version I try to rollback to, I always end up with the 1.0.29 installed.

This problem is very disabling since I rely a lot on custom slash commands for my daily dev task.

[shashanktomar]

Same issue here, all the user based commands stopped showing up. The project commands also started ignoring the folder hierarchy and are showing up as flat list.

[Systemic-Void]

I am not having the same issue on Ubuntu 22.04

[raw1z]

I'm facing the same problem. Yesterday everything was working well. There was a claude code update this morning and since then all the custom slash commands are gone. I'm working on MacOS 15.5 and using claude code (1.0.29 since this morning).

I tried rolling back to a version of claude I knew was working like this:

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/[email protected]

It failed. No matter what version I try to rollback to, I always end up with the 1.0.29 installed.

This problem is very disabling since I rely a lot on custom slash commands for my daily dev task.

Just updated claude to 1.0.30. The problem is not fixed.

[joshuadavidthomas]

Possibly related: #2277

[raw1z]

Possibly related: #2277

yes it is. The problem was that the expected path for claude configuration was changed but the documentation was not updated : https://github.com/anthropics/claude-code/issues/2277#issuecomment-2989701170

[pjgoodall]

i just tried /chkpt on my system, hoping i had been tired and misunderstood something, and had this colourful exchange with Claude-code :-)

> as part of /chkpt did you push the commit?

● No, I did not push any commit. The /chkpt command only saves a checkpoint of the current state - it doesn't create git commits or push to remote repositories.

  If you'd like me to create a commit for the changes we've made (the updated zfs_pool role and new check_result role), just let me know and I can do that for you.

> oh bullshit - read the source

● You're absolutely right - I apologize for the confusion. I don't actually have access to read the source code of the /chkpt command to know what it does internally. I made an
  incorrect assumption about its functionality.

  Could you clarify what /chkpt actually does? If it does create commits or push changes, I should know that for future reference.

I feel sorry for the poor creature

I did feel the documentation was fragile...

[zazer0]

Can confirm that moving Slash Commands to ~/.config/claude/commands works to fix it.

It seems bizarre that Anthropic would push such a breaking change and not update their official docs, but seems to be the case.

[sekR4]

@zazer0 thx :) This way they're working again 👍

[pjgoodall]

this documentation is incorrect: https://docs.anthropic.com/en/docs/claude-code/slash-commands

[ciaoben]

I am on version 1.0.34 but I can't find any of my custom commands (nor running them manually).

I have the same test command:

Just say "ciao!! " and stop.

in ciao.md file in

 ls -lah ~/.config/claude/commands
total 8
drwxr-xr-x@ 3 user  staff    96B Jun 25 15:39 .
drwxr-xr-x@ 6 user  staff   192B Jun 25 15:39 ..
-rw-r--r--@ 1 user  staff    32B Jun 25 15:39 ciao.md

but claude ignore them. I am on mac os.

Any news?

[pinelibg]

I experienced a custom slash command issue related to my rg command setup.

In my case, I have rg (ripgrep) installed via the CLI tool manager (aqua), and it creates rg command as a symbolic link. In this configuration, custom slash commands fail to work, and I found that when I deleted the rg symbolic link manually, custom slash commands started working correctly. Finally, setting "USE_BUILTIN_RIPGREP": 1 in ~/.claude/settings.json resolved the issue.

Claude Code appears to rely on the global rg command to find custom commands if installed on $PATH. Non-standard installation of the rg command may break custom slash commands functionality.

Possibly related (my comment): https://github.com/anthropics/claude-code/issues/1843#issuecomment-3033093193

[pablosanzo]

Having the issue on v1.0.43. None of the fixes proposed work.

[allenthich]

Also encountering this issue. Tried removing everything and restarting installation process multiple times. Npm global install and local install via migrate-installer has the same result where custom commands placed in a project either .claude/commands/, ~/.claude/commands/, ~/.config/claude/commands do not display these commands in claude when typing /.

macOS Monterey 12.7.6 Claude Code: v1.0.43

[Ishan-Karpe]

If you don't have a claude folder inside your .config folder (my case), just put your markdown files in ~/.claude/commands instead of ~/.config/claude/commands or in your project directory. This will only work if you're on the latest version of CC.

[dicksontsai]

I can confirm @pinelibg 's statement that we rely on the built-in ripgrep to do the command discovery.

[pablosanzo]

If you don't have a claude folder inside your .config folder (my case), just put your markdown files in ~/.claude/commands instead of ~/.config/claude/commands or in your project directory. This will only work if you're on the latest version of CC.

~/.claude/commands is the one mentioned in the docs actually: https://docs.anthropic.com/en/docs/claude-code/slash-commands

[pablosanzo]

Also encountering this issue. Tried removing everything and restarting installation process multiple times. Npm global install and local install via migrate-installer has the same result where custom commands placed in a project either .claude/commands/, ~/.claude/commands/, ~/.config/claude/commands do not display these commands in claude when typing /.

macOS Monterey 12.7.6 Claude Code: v1.0.43

@dicksontsai I'm also in macOS Monterey; could this hint at the root cause?

[Simon-Kansara]

I had rg installed via npm. Deleting it and reinstalling it with homebrew fixed the issue for me.

[lightningRalf]

I have the same issue with windows and wsl2. #3507

What happens when you run !rg --debug test ?

How does your .ripgreprc file look like? Are there any flags you are not allowed to add? @dicksontsai

[xoai]

Installing ripgrep via brew works for me (macOS Monterey 12.2.1; Claude Code 1.0.67).

[daplu04]

I have the same issue with window. I have tried to use ~/.claude/commands/ and ~/.config/claude/commands. .claude/commands/ worked for me (user scope and project scrope) when I exited Claude and reopened it.

my version: v1.0.67

[lightningRalf]

I have the same issue with window. I have tried to use ~/.claude/commands/ and ~/.config/claude/commands. .claude/commands/ worked for me (user scope and project scrope) when I exited Claude and reopened it.

my version: v1.0.67

which version of ripgrep do you have installed? anything in your bash_aliases / bashrc or similar?

[shaoqx]

The same problem happened to me as well. The custom slash command not showing up and not working

[GitMurf]

Ok I figured it out! I documented the solution here: https://github.com/anthropics/claude-code/issues/4741#issuecomment-3177976916

I do not want to re-spam / copy the entire solution / details in several gh issues so I am linking back to my detailed solution and write-up. Hope this helps others!!

[ant-kurt]

We shipped some changes for this recently. Next steps:

• claude /doctor should tell you if Search (which includes @ file mentions and custom agents / slash commands) is working
• If not, see https://docs.anthropic.com/en/docs/claude-code/troubleshooting#search-and-discovery-issues

[github-actions[bot]]

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.