Agent Skills: Claude Code 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)