[BUG] Custom slash commands not discovered in ~/.claude/commands/ despite correct setup

[Dingzeefs]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Custom slash commands stored in ~/.claude/commands/*.md are not being discovered or
loaded by Claude Code 2.0.5. Commands do not appear in autocomplete.

Interestingly, hooks configured in ~/.claude/settings.json work perfectly, proving
that configuration loading works but the filesystem scanning mechanism for discovering
commands seems broken.

All command files are properly formatted with required frontmatter, correct filenames,
and proper permissions. Multiple restarts and troubleshooting steps have been
attempted with no success.

What Should Happen?

Custom commands in ~/.claude/commands/*.md should be:

1. Automatically discovered on Claude Code startup
2. Available as slash commands (e.g., /debug, /test, /analyze-codebase)
3. Listed in autocomplete when typing /
4. Executable when invoked

Error Messages/Logs

No error messages appear. Commands simply don't exist - typing / only shows built-in
  commands, and attempting to invoke custom commands results in "Unknown slash command"
  error.

  # When trying to invoke custom command:
  /debug
  Error: Unknown slash command: /debug

  Diagnostic output:
  Diagnostics
   └ Currently running: npm-local (2.0.5)
   └ Path: /Users/DINGZEEFS/.nvm/versions/node/v23.9.0/bin/node
   └ Invoked: /Users/DINGZEEFS/.claude/local/node_modules/.bin/claude
   └ Config install method: local
   └ Auto-updates enabled: default (true)
   └ Search: OK (vendor)

Steps to Reproduce

1. Create the commands directory:
   mkdir -p ~/.claude/commands
2. Create a test command file ~/.claude/commands/test.md:

---

description: Simple test command

Test Command

This is a test command. Arguments: $ARGUMENTS

The test command is working!
3. Verify the file exists and has correct permissions:
ls -la ~/.claude/commands/test.md

Should show: -rw-r--r-- 1 user staff 134 Oct 3 11:47 test.md

4. Exit Claude Code completely (close terminal)
5. Open a new terminal and start Claude Code:
   claude
6. Type / to see available commands
7. Expected: /test appears in the list
   Actual: Only built-in commands appear, /test is missing
8. Try to invoke the command:
   /test
9. Expected: Command executes
   Actual: "Unknown slash command: /test"

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

No response

Claude Code Version

2.0.5 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

1. Hooks work, commands don't: Hooks configured in ~/.claude/settings.json execute
   correctly, proving the ~/.claude/ directory is accessible and settings are being
   loaded. This isolates the issue to filesystem scanning for command files.
2. All setup verified correct:
   - ✅ Directory: ~/.claude/commands/ exists and is readable
   - ✅ Files: 8 command files with proper .md extension
   - ✅ Permissions: All files are rw-r--r-- (readable)
   - ✅ Format: All files have required description frontmatter
   - ✅ Content: Files contain instructions (not just command names)
   - ✅ Naming: Files use hyphens (e.g., debug.md, not debug md.md)
   - ✅ No subdirectories: Files are directly in commands folder
   - ✅ Ripgrep installed: rg --version shows 14.1.1
3. Troubleshooting attempted:
   - Restarted Claude Code multiple times (full terminal closure)
   - Removed duplicate npm-global installation
   - Verified no local project .claude/commands/ override
   - Checked for hidden characters (none found)
   - Confirmed directory is real (not a symlink)
   - Tried both ~/.claude/commands/ and ~/.config/claude/commands/

Example command file structure:

$ ls -la ~/.claude/commands/
total 96
-rw-r--r-- 1 user staff 6674 Oct 3 11:35 analyze-codebase.md
-rw-r--r-- 1 user staff 1679 Oct 3 11:51 debug.md
-rw-r--r-- 1 user staff 9723 Oct 3 11:41 pr-review.md
-rw-r--r-- 1 user staff 134 Oct 3 11:47 test.md

Example file content:

description: Debug and fix terminal errors automatically
allowed-tools: Bash(python:), Bash(uv:), Read, Write, Edit

Error Debugging and Fixing

Debugging Process

1. READ the terminal output to understand the error
2. ANALYZE the error - identify root cause
3. FIX the error by modifying code

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Slash Commands not found with Custom CLAUDE_CONFIG_DIR #5573
2. [BUG] Additional .claude dir prevents commands from being discovered #1339
3. Claude Code cannot detect new commands or deleted commands #4384

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[dicksontsai]

Did you try running /debug directly or try to have Claude run it through SlashCommand tool? SlashCommand tool only supports commands that have description populated: https://docs.claude.com/en/docs/claude-code/slash-commands#slashcommand-tool-supported-commands . You can use claude --debug to see which custom slash commands are available for SlashCommand tool.

[Dingzeefs]

@dicksontsai yeah I tried that and it confirmed my commands have the right format with descriptions etc

[jrogers-hedgeye]

👍 same for me when using the brew version of claude-code (2.0.13). I uninstalled that version and installed with NPM and now custom slash commands are found. See my initial issue for details: #9316

[Dingzeefs]

👍 same for me when using the brew version of claude-code (2.0.13). I uninstalled that version and installed with NPM and now custom slash commands are found. See my initial issue for details: #9316

I am on NPM unfortunatelly so that does not work for me