Settings Configuration

Claude Code Settings Configuration

Expert knowledge for configuring Claude Code settings and permissions.

When to Use This Skill

Settings File Hierarchy

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

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

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

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

Agentic Optimizations

Quick Reference

File Locations

Permission Syntax

Bash(command prefix *)
mcp__server_name

Priority

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