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

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] 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

1. 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!

1. 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

1. Exit Claude Code completely (close terminal)
2. Open a new terminal and start Claude Code:

claude

1. Type / to see available commands
2. Expected: /test appears in the list

Actual: Only built-in commands appear, /test is missing

1. Try to invoke the command:

/test

1. 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.

1. 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

1. 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