Project-Specific Slash Commands Not Loading in Claude Code 2.0.69 (macOS)

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?

Claude Code 2.0.69 on macOS is not discovering or loading project-specific slash commands from .claude/commands/ directory.

Symptoms:

• ❌ Commands in .claude/commands/*.md do NOT appear in autocomplete when typing /
• ❌ Commands do NOT appear in /help output
• ❌ Commands are NOT included in SlashCommand tool context
• ❌ Attempting to execute commands (e.g., /my_command) fails - command not found
• ✅ Plugin commands from ~/.claude/plugins/ load and work correctly (67 plugin commands loaded successfully)

The same command files work correctly in Docker environment with identical Claude Code version 2.0.69, suggesting this is a macOS-specific bug.

What Should Happen?

Local project commands in .claude/commands/*.md should be:

1. Discovered automatically when Claude Code starts in a project directory
2. Available in autocomplete when typing /
3. Listed in /help output alongside plugin commands
4. Executable via SlashCommand tool when invoked
5. Included in system context for command execution

Plugin commands work correctly - project commands should work the same way.

Error Messages/Logs

# Plugin commands loaded successfully
2025-12-13T17:07:38.300Z [DEBUG] Loaded 4 commands from plugin cognitive-orchestration default directory
2025-12-13T17:07:38.303Z [DEBUG] Loaded 4 commands from plugin data-intelligence default directory
2025-12-13T17:07:38.304Z [DEBUG] Loaded 4 commands from plugin ux-product default directory
2025-12-13T17:07:38.309Z [DEBUG] Loaded 4 commands from plugin frontend-excellence default directory
2025-12-13T17:07:38.311Z [DEBUG] Loaded 4 commands from plugin backend-security default directory
2025-12-13T17:07:38.318Z [DEBUG] Loaded 15 commands from plugin dev-accelerator default directory
2025-12-13T17:07:38.319Z [DEBUG] Loaded 4 commands from plugin infra-pipeline default directory
2025-12-13T17:07:38.320Z [DEBUG] Loaded 8 commands from plugin interview-assist default directory
2025-12-13T17:07:38.320Z [DEBUG] Loaded 3 commands from plugin personalities default directory
2025-12-13T17:07:38.321Z [DEBUG] Loaded 3 commands from plugin insight-engine default directory
2025-12-13T17:07:38.322Z [DEBUG] Loaded 5 commands from plugin observability-ops default directory
2025-12-13T17:07:38.322Z [DEBUG] Loaded 4 commands from plugin queue-orchestrator default directory
2025-12-13T17:07:38.323Z [DEBUG] Loaded 5 commands from plugin project-delivery default directory
2025-12-13T17:07:38.323Z [DEBUG] Total plugin commands loaded: 67
2025-12-13T17:07:38.517Z [DEBUG] Loaded plugins - Enabled: 13, Disabled: 0, Commands: 67, Agents: 76, Errors: 0

# SlashCommand tool includes ONLY plugin commands (project commands missing)
2025-12-13T17:07:39.290Z [DEBUG] Slash commands included in SlashCommand tool: /cognitive-orchestration:constructive_dissent, /cognitive-orchestration:multi_perspective, /cognitive-orchestration:orchestrate, /cognitive-orchestration:ultrathink, /data-intelligence:analytics, /data-intelligence:data, /data-intelligence:etl, /data-intelligence:timeseries, /ux-product:journey, /ux-product:product, /ux-product:user-research, /ux-product:ux, /frontend-excellence:frontend, /frontend-excellence:react, /frontend-excellence:state, /frontend-excellence:ui, /backend-security:api, /backend-security:auth, /backend-security:llm, /backend-security:security, /dev-accelerator:workflows:feature-development, /dev-accelerator:workflows:security-hardening, /dev-accelerator:workflows:tdd-cycle, /infra-pipeline:automate, /infra-pipeline:deploy, /infra-pipeline:infra, /infra-pipeline:pipeline, /interview-assist:behavioral, /interview-assist:coding, /interview-assist:leadership, /interview-assist:mock, /interview-assist:side-effects, /interview-assist:strategy, /interview-assist:system-design, /interview-assist:whiteboard, /personalities:analyze, /personalities:debate, /personalities:evaluate, /insight-engine:assumption_audit, /insight-engine:guest_expert, /insight-engine:synthesis_engine, /observability-ops:audit, /observability-ops:incident, /observability-ops:monitor, /observability-ops:slo, /observability-ops:trace, /queue-orchestrator:async, /queue-orchestrator:backpressure, /queue-orchestrator:distributed, /queue-orchestrator:queue, /project-delivery:metrics, /project-delivery:plan, /project-delivery:retro, /project-delivery:roadmap, /project-delivery:stakeholder

# Command files were successfully written by Claude Code
2025-12-13T17:28:57.553Z [DEBUG] Writing to temp file: /Users/username/projectfolder/.claude/commands/my_command.md.tmp.78262.1765646937553
2025-12-13T17:28:57.560Z [DEBUG] Renaming /Users/username/projectfolder/.claude/commands/my_command.md.tmp.78262.1765646937553 to /Users/username/projectfolder/.claude/commands/my_command.md
2025-12-13T17:28:57.561Z [DEBUG] File /Users/username/projectfolder/.claude/commands/my_command.md written atomically
2025-12-13T17:28:57.571Z [DEBUG] FileHistory: Tracked file modification for /Users/username/projectfolder/.claude/commands/my_command.md

2025-12-13T17:29:11.435Z [DEBUG] Writing to temp file: /Users/username/projectfolder/.claude/commands/custom_workflow.md.tmp.78262.1765646951435
2025-12-13T17:29:11.440Z [DEBUG] Renaming /Users/username/projectfolder/.claude/commands/custom_workflow.md.tmp.78262.1765646951435 to /Users/username/projectfolder/.claude/commands/custom_workflow.md
2025-12-13T17:29:11.440Z [DEBUG] File /Users/username/projectfolder/.claude/commands/custom_workflow.md written atomically
2025-12-13T17:29:11.453Z [DEBUG] FileHistory: Tracked file modification for /Users/username/projectfolder/.claude/commands/custom_workflow.md

Steps to Reproduce

1. Create project with .claude/commands/ directory

``bash
mkdir -p /Users/username/projectfolder/.claude/commands
``

1. Add command file with correct frontmatter (e.g., .claude/commands/test.md)

```yaml
---
description: Test command to verify discovery
argument-hint: [arg1] [arg2]
allowed-tools: Bash(), Read(), Write(*)
---

This is a test command.
```

1. Verify file permissions

``bash
ls -la .claude/commands/test.md
# Should be readable: -rw-r--r--
``

1. Start Claude Code 2.0.69 in the project directory

``bash
cd /Users/username/projectfolder
claude
``

1. Test command discovery

• Type / to see autocomplete → only plugin commands appear
• Type /help → only plugin commands listed
• Try /test → command not found

Expected: /test command should appear and be executable
Actual: Command does not appear, only plugin commands load

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.69

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

⚠️ Important Clue: Commands Work with --debug Flag

Critical finding: Project commands DO appear and work correctly when starting Claude Code with the --debug flag:

claude --debug
# Commands in .claude/commands/ are discovered and functional

Comparison:

• ✅ claude --debug → Project commands load correctly
• ❌ claude (normal mode) → Project commands do NOT load

This suggests:

• Debug mode may use a different code path for command discovery
• There could be a timing issue that debug mode avoids
• Normal mode may have an optimization or caching mechanism that's broken
• The command discovery logic exists but isn't being triggered in normal mode

Key Findings from Debug Logs

Log analysis reveals:

• ✅ 67 plugin commands loaded successfully
• ❌ NO log entries for loading project commands from .claude/commands/
• ❌ SlashCommand tool context only includes plugin commands
• ✅ File write events confirm command files exist at correct location

Missing log entries (expected but not present):

• "Loaded commands from project"
• "Loaded X commands from .claude/commands"
• Any reference to discovering local command files

This confirms command files exist and are accessible, but project command discovery is completely skipped on macOS.

Version Testing

The break appeared to coincide with the auto-upgrade to version 2.0.69, leading to the initial suspicion of a regression. However:

• ❌ Reverted to version 2.0.65 - Commands still did not load
• ❌ Tested with 2.0.68 - Commands still did not load (if tested)

Conclusion: It's not clear if this is a regression or a pre-existing issue that was only recently discovered. The commands definitely work in Docker with 2.0.69, which points to a macOS-specific implementation issue rather than a recent breaking change.

Command File Details

Location:

/Users/username/projectfolder/.claude/commands/
├── my_command.md
├── custom_workflow.md
└── test.md

File Permissions:

-rw-r--r--  1 username  staff  27664 Dec 13 12:28 my_command.md
-rw-r--r--  1 username  staff   5615 Dec 13 12:29 custom_workflow.md
-rw-r--r--  1 username  staff    150 Dec 13 12:35 test.md

All files are readable and have correct permissions.

Sample Frontmatter (Verified Correct Format):

---
description: Execute one iteration - implement changes, validate, and document results
argument-hint: [scope] [iteration]
allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Task(*), SlashCommand(*)
---

Format verified against official documentation:

• ✅ No name field (derived from filename)
• ✅ No arguments array (not supported)
• ✅ Has description (required for discovery)
• ✅ Has argument-hint (optional)
• ✅ Has allowed-tools (optional)

Workarounds Tested

❌ Failed Attempts:

1. Restarting Claude Code - Commands still not discovered
2. Clearing macOS extended attributes - No effect
3. Using --dangerously-skip-permissions flag - Commands still not loaded
4. Checking file encoding - Files are UTF-8 (correct)
5. Verifying working directory - Correct (pwd matches .claude/ location)

✅ Working in Docker Environment:

The same command files work correctly when Claude Code runs in a Docker container:

Docker Configuration:

• Base Image: Ubuntu/Debian Linux
• Claude Code Version: Same (2.0.69, installed via npm)
• Volume Mounts:
• Project directory mounted at /workspace (read/write)
• ~/.claude directory mounted from host (contains same settings, plugins, etc.)
• ~/.gitconfig mounted (read-only)
• ~/.ssh mounted (read-only)
• Working Directory: Container starts in /workspace (project root)
• Commands: Same .claude/commands/*.md files (via volume mount from macOS host)

Result: When running claude inside the Docker container, project commands load and work correctly.

Key observations:

• Same Claude Code binary version (2.0.69)
• Same command files (mounted from host filesystem)
• Same ~/.claude settings directory (mounted from host)
• Different OS: Linux (Docker) vs Darwin (macOS host)

This strongly suggests a macOS-specific bug in command discovery, potentially related to filesystem operations or path resolution that behaves differently on Darwin vs Linux.

🔄 Untested Workarounds:

1. Global commands: Copy to ~/.claude/commands/ instead of .claude/commands/
2. Rollback to 2.0.68: Test if this is a regression in 2.0.69

Permissions Configuration

Commands are whitelisted in .claude/settings.local.json:

{
  "allow": [
    "SlashCommand(/my_command:*)",
    "SlashCommand(/custom_workflow:*)"
  ]
}

Docker vs macOS Comparison

| Aspect | Docker (✅ Works) | macOS (❌ Broken) |
|--------|------------------|-------------------|
| Claude Code Version | 2.0.69 | 2.0.69 |
| Command Files | Same (mounted) | Same |
| File Permissions | Readable | Readable |
| Commands Load | Yes | No |
| Platform | Linux | Darwin |

Impact

This bug prevents using project-specific workflow automation commands, forcing users to:

• Use Docker containers (workaround overhead)
• Use global commands (loses project isolation)
• Use agents instead (different UX)

Configuration Files

.claude/settings.local.json:

{
  "allow": [
    "SlashCommand(/my_command:*)"
  ]
}

Working directory structure:

/Users/username/projectfolder/
├── .claude/
│   ├── commands/
│   │   ├── my_command.md
│   │   └── test.md
│   └── settings.local.json
└── (project files)