Claude Code Custom Commands Not Working: 164 Issues Sorted

I typed /hello-probe into a headless Claude Code run and got back Unknown command: /hello-probe, exit code 0, in 20 milliseconds. The command file existed. It was at .claude/commands/ops/hello-probe.md, and a file one folder down no longer answers to its own name. Only one of the four failures I hit today printed a "Did you mean". None of them changed the exit code.

So when Claude Code custom commands are not working, the cause is often a naming rule rather than a bug. Sometimes it really is a bug, though. To find out which failures still happen, I did two things on September 17. I sorted 164 GitHub issues about custom commands that don't show up or don't run. Then I built 17 throwaway projects and made 19 runs through claude -p on Claude Code 2.1.271, checking the command list the session reported instead of trusting the model's reply.

Four ways a command still silently fails

Each fixture held one command whose whole instruction was "Reply with exactly CANARY-<id>". A run passed if the canary came back. Fifteen of the 19 runs passed, including several cases that GitHub issues once reported as broken. These four did not:

Fixture	What I typed	What came back
commands/ops/hello-probe.md	/hello-probe	Unknown command: /hello-probe, no suggestion. /ops:hello-probe worked
commands/Hello-Probe.md	/hello-probe	Unknown command: /hello-probe. Did you mean /Hello-Probe?
commands/hello-probe.txt	/hello-probe	Not listed at all. Unknown command
Command and a skill both named hello-probe	/hello-probe	The skill's canary. The command was never mentioned

All four follow the documentation. The Claude Code skills page names a command after its file, and a file in a subfolder gets the folder path with a colon, so frontend/component.md becomes /frontend:component, and it describes command files as Markdown. In my runs the name was also case-sensitive, and a .txt file was never listed. When a skill and a command share a name, the same page says the skill wins. I measured that collision in more detail in Claude Code slash commands vs skills. The rules are consistent, but only the capitalization error points you to them.

The exit code is the bigger problem for anyone scripting this. Every Unknown command run came back with "is_error": false, "subtype": "success" and "num_turns": 0, and the shell saw exit 0. The CHANGELOG for 2.1.147 says unknown slash commands in headless mode used to do "silently nothing" and "now show an error message". That text is what you get now. A scheduler that only watches exit codes still counts the run as a success, which is the same trap I found with Claude Code exit code 1, only reversed.

Two passes deserve a warning too. An empty command file loaded and ran. With no instructions, the model called the Skill tool, got nothing back, and wrote a friendly paragraph about my machine setup. A file with broken YAML frontmatter also loaded and ran its body without any warning. Neither one fails in a way you'd notice.

164 GitHub issues, sorted by cause

I ran nine title searches against issues in anthropics/claude-code, including "custom command", "slash commands", "commands directory" and "command file". That returned 1,379 unique issues. I kept the 183 whose titles named a user-written command along with a failure word, dropped 19 that turned out to be about something else, and sorted the remaining 164 by title. They were filed between March 2025 and August 2026: 90 in 2025 and 74 so far in 2026.

The largest group, 50 issues, are plain "not discovered" or "not loading" reports with no cause in the title. As of today, 60 of the 164 are closed as completed, 55 as not planned and 45 as duplicates. Four are open. One is #81156: the / menu never matches a command with a Korean file name, and a maintainer reproduced it on August 25. In my headless run the Korean-named command was listed and ran when typed in full. That fits a bug in the interactive menu's filtering, which a -p test can't reach.

The week every command disappeared

Eighteen of the 164 issues were filed between March 30 and April 3, 2026, and 15 of them describe one breakage. Version 2.1.88 went out on npm at 22:36 UTC on March 30, and 2.1.89 followed the next day. #41463 found the cause on Linux: the bundled vendor/ripgrep/x64-linux/rg binary shipped without its execute bit. Claude Code scans for command files with ripgrep, so every user command came back as Unknown skill. On #41864 a maintainer wrote that it was fixed in 2.1.91, released April 2. The CHANGELOG entry for 2.1.91 doesn't mention it.

The ripgrep and platform-scan group holds 7 more issues from other weeks. They include Termux on Android with no arm64 ripgrep binary, a Windows race that aborted the scan partway, and a user's ripgrep config file forcing colors and hyperlinks into the file list. If commands that worked yesterday are gone today and you changed nothing, check the version first. If your install doesn't update itself, Claude Code not updating covers why.

What no longer breaks

Several causes from older threads didn't reproduce on 2.1.271. In July 2025 a maintainer said on #3059 that ignoring command files listed in .gitignore was expected. Version 2.0.28 reversed that, and my three gitignore fixtures all ran: .claude/ ignored inside a git repo and outside one, and *.md ignored inside one. A symlinked commands directory and a symlinked single file both worked, even though symlinks account for 6 closed issues. A hyphenated file name worked, unlike #15852 on 2.0.76, and so did a project path with a space in it. Starting the session two folders below the project root found the root's commands with or without git.

I also checked reloading. In one long-lived headless session using --input-format stream-json, a command file created between turns ran on the next turn, and an edit to an existing file took effect too. Five issues describe stale command lists, from commands vanishing after their first use to a Windows desktop app that needed a full restart. I didn't test the interactive UI or the desktop app.

Make a missing command fail loudly

This guard caught the .txt fixture. An unknown command ends before the first turn, so zero turns plus that result prefix is a clear signal:

out=$(claude -p "/deploy-notes" --output-format json)
if jq -e '.num_turns == 0 and (.result | startswith("Unknown command"))' \
     <<<"$out" >/dev/null; then
  echo "command not loaded: $(jq -r .result <<<"$out")" >&2
  exit 1
fi

To see what a session actually loaded, read the init event rather than asking the model. This costs one short turn:

claude -p "hi" --output-format stream-json --verbose --max-turns 1 \
  | jq -r 'select(.subtype == "init") | .slash_commands[]'

If the command isn't in that list, work through the causes in this order. They're the ones I could reproduce, followed by the ones the issues point to:

1. The name you type must match the path. Use /folder:name for subfolders, keep the file name's capitalization, and use the .md extension.
2. Check .claude/skills/ for a skill with the same name, including user-level skills in ~/.claude/skills/.
3. Run claude --version and search the issues for it. A version jump that coincides with every command vanishing matches the 2.1.88 pattern.
4. On Linux, Termux or Windows, check that the bundled ripgrep can execute and that no ripgrep config file (RIPGREP_CONFIG_PATH) is changing its output.
5. If the command works in the terminal but not elsewhere, it's a client bug. 15 issues cover the IDE extensions, the desktop app, the SDK and Remote Control.

A command that loads but ignores model: or effort: in its frontmatter is a separate category, with 10 issues and fixes spread over several versions. Like Claude Code hooks that don't fire, it's a configuration you only notice when the output looks wrong.

FAQ

Why is my Claude Code custom command not showing up?

On current versions, the usual causes are a name mismatch or a skill with the same name. Commands in subfolders are named /folder:name, names are case-sensitive, and only .md files load. If commands vanished right after an update, check your version. In 2.1.88 and 2.1.89, a ripgrep binary without execute permission hid every command until 2.1.91.

Does Claude Code ignore command files in .gitignore?

Not anymore. Discovery stopped respecting .gitignore in version 2.0.28. On 2.1.271, commands inside a gitignored .claude/ folder loaded and ran in my tests, both inside and outside a git repository.

Does claude -p fail when a slash command doesn't exist?

No. It prints Unknown command: /name and exits with code 0. The JSON output reports is_error: false and num_turns: 0. Check for that result text or for zero turns if a script depends on the command running.

Sources and method: 17 fixtures in /tmp and 19 runs, each with claude -p "/<name>" --model haiku --output-format stream-json --verbose on Claude Code 2.1.271 on macOS, on 2026-09-17. Pass or fail was read from the init event's slash_commands list and a canary string in the result, not from the model's prose. The reload test was one extra stream-json session. I didn't test ~/.claude/commands, Windows, Linux, the IDE extensions or the interactive menu. The issue census is nine GitHub title searches run the same evening. Classification is mine, by title only, so a report whose title says "not loading" counts as a symptom even if its thread later found a cause. The raw list is kept with this post's research notes. Release times come from the npm registry, and doc quotes come from code.claude.com as fetched today. There are no affiliate links in this post.