claude-code-config

Claude Code Configuration Gotchas

Permission Path Syntax (Critical)

Single vs Double Slash:

• /path/to/file = relative to settings file location
• //path/to/file = absolute filesystem path
• ~/path = home directory (works in both)

Common mistake: Writing Read(/tmp/**) when you mean absolute path. Correct: Read(//tmp/**).

Pattern format must match tool signature:

• Correct: Read(//tmp/**), Bash(npm run:*)
• Wrong: Read(file_path://tmp/**) — tool name only, no parameter labels

Bash rules use :* for prefix matching: Bash(npm run:*) matches any command starting with npm run . Bash(npm run *) (space-star) is NOT the prefix syntax and matches unreliably.

Wildcard Matching

Recursive vs Single Level:

• * = matches single path segment (e.g., *.txt in current dir only)
• ** = matches recursively (e.g., **/*.txt in all subdirs)

Edge case: Bash(ls *) may not match ls -la ~/.claude/ due to tilde expansion timing and wildcard evaluation order.

Rule Evaluation Order

Deny always wins:

1. Deny rules checked first (block regardless of anything else)
2. Ask rules checked second (prompt user if matched)
3. Allow rules checked last (permit if matched)

First match wins within each category.

Common mistake: Adding allow rule but deny rule exists elsewhere (user settings, enterprise managed-settings.json, or higher in hierarchy). Deny always overrides allow, even if allow is more specific.

Settings File Hierarchy (Highest to Lowest Priority)

1. Enterprise managed-settings.json (cannot be overridden)
2. Command-line flags (--dangerously-skip-permissions)
3. Project .claude/settings.local.json (gitignored, per-developer)
4. Project .claude/settings.json (versioned, shared with team)
5. User ~/.claude/settings.json (global for your machine)

Gotcha: Local settings override shared settings. If permission works for you but not teammate, check if you have conflicting .local file.