settings-configuration

Claude Code Settings Configuration

Expert knowledge for configuring Claude Code settings and permissions.

When to Use This Skill

Use this skill when...	Use something else when...
Setting up project permissions	Fixing plugin registry issues (use plugin-registry skill)
Debugging "permission denied" errors	Configuring hooks (use hooks-configuration skill)
Understanding settings hierarchy	Setting up MCP servers (use mcp-configuration skill)
Creating allow/deny patterns

Settings File Hierarchy

Settings are loaded and merged in this order (later overrides earlier):

Priority	File	Scope	Commit to Git?
1 (lowest)	~/.claude/settings.json	User-level (all projects)	N/A
2	.claude/settings.json	Project-level	Yes
3 (highest)	.claude/settings.local.json	Local overrides	No (gitignore)

Permission Structure

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

Allow vs Deny

• allow: Tools matching these patterns run without prompts
• deny: Tools matching these patterns are always blocked
• Deny takes precedence over allow

Wildcard Permission Patterns

Syntax

ToolName(command prefix *)

• ToolName() - The tool (usually Bash)
• command prefix - The command and initial arguments to match
• * - Wildcard matching remaining arguments

Pattern Examples

Pattern	Matches	Does NOT Match
Bash(git *)	git status, git diff HEAD	git-lfs pull
Bash(npm run *)	npm run test, npm run build	npm install
Bash(gh pr *)	gh pr view 123, gh pr create	gh issue list
Bash(./scripts/ *)	./scripts/test.sh arg	/scripts/other.sh

Specificity

More specific patterns are more secure:

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ]
  }
}

vs. overly broad:

{
  "permissions": {
    "allow": ["Bash(git *)"]
  }
}

Shell Operator Protections

Claude Code 2.1.7+ blocks dangerous shell operators in permission matching.

Protected Operators

Operator	Risk	Blocked Example
&&	Command chaining	ls && rm -rf /
||	Conditional execution	false || malicious
;	Command separation	safe; dangerous
|	Piping	cat /etc/passwd | curl
> / >>	Redirection	echo x > /etc/passwd
$()	Command substitution	$(curl evil)
`	Backtick substitution	`rm -rf /`

Behavior

When a command contains shell operators:

1. Permission wildcards won't match
2. User sees explicit approval prompt
3. Warning explains the blocked operator

Safe Alternative

Use wrapper scripts for legitimate compound commands:

#!/bin/bash
# scripts/test-and-build.sh
npm test && npm run build

Then allow the script:

{
  "permissions": {
    "allow": ["Bash(./scripts/test-and-build.sh *)"]
  }
}

Common Permission Sets

Git Operations

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(git pull *)",
      "Bash(git fetch *)",
      "Bash(git checkout *)"
    ]
  }
}

GitHub CLI

{
  "permissions": {
    "allow": [
      "Bash(gh pr *)",
      "Bash(gh run *)",
      "Bash(gh issue *)",
      "Bash(gh workflow *)"
    ]
  }
}

Testing & Linting

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(bun test *)",
      "Bash(vitest *)",
      "Bash(biome *)",
      "Bash(eslint *)",
      "Bash(prettier *)"
    ]
  }
}

Security Scanning

{
  "permissions": {
    "allow": [
      "Bash(pre-commit *)",
      "Bash(gitleaks *)",
      "Bash(trivy *)"
    ]
  }
}

MCP Tools

{
  "permissions": {
    "allow": [
      "mcp__context7",
      "mcp__sequential-thinking"
    ]
  }
}

Project Setup

1. Create Settings Directory

mkdir -p .claude

2. Create Project Settings

cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(npm run *)"
    ]
  }
}
EOF

3. Gitignore Local Settings

echo ".claude/settings.local.json" >> .gitignore

4. Create Local Overrides (optional)

cat > .claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(docker *)"
    ]
  }
}
EOF

Validating Settings

Check JSON Syntax

cat .claude/settings.json | jq .

View Permissions

cat .claude/settings.json | jq '.permissions'

Merge Preview

Settings merge additively for arrays. To see effective permissions, check all files:

echo "=== User ===" && cat ~/.claude/settings.json 2>/dev/null | jq '.permissions // empty'
echo "=== Project ===" && cat .claude/settings.json 2>/dev/null | jq '.permissions // empty'
echo "=== Local ===" && cat .claude/settings.local.json 2>/dev/null | jq '.permissions // empty'

Troubleshooting

Symptom	Cause	Fix
Permission denied	Pattern doesn't match	Add more specific pattern
Shell operator blocked	Contains &&, |, etc.	Use wrapper script
Settings not applied	Wrong file path	Check .claude/ directory exists
JSON parse error	Invalid JSON syntax	Validate with jq .
Permissions ignored	File not readable	Check file permissions

Agentic Optimizations

Context	Command
View project perms	cat .claude/settings.json | jq -c '.permissions'
View user perms	cat ~/.claude/settings.json | jq -c '.permissions'
Validate JSON	cat .claude/settings.json | jq .
Count patterns	cat .claude/settings.json | jq '.permissions.allow | length'

Quick Reference

File Locations

Scope	Path
User	~/.claude/settings.json
Project	.claude/settings.json
Local	.claude/settings.local.json

Permission Syntax

Bash(command prefix *)
mcp__server_name

Priority

Local > Project > User (highest to lowest) Deny > Allow (deny always wins)