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

json

{
  "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:

json

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

vs. overly broad:

json

{
  "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:

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

Safe Alternative

Use wrapper scripts for legitimate compound commands:

bash

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

Then allow the script:

json

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

Common Permission Sets

Git Operations

json

{
  "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

json

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

Testing & Linting

json

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

Security Scanning

json

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

MCP Tools

json

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

Project Setup

1. Create Settings Directory

bash

mkdir -p .claude

2. Create Project Settings

bash

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

3. Gitignore Local Settings

bash

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

4. Create Local Overrides (optional)

bash

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

Validating Settings

Check JSON Syntax

bash

cat .claude/settings.json | jq .

View Permissions

bash

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

Merge Preview

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

bash

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)

settings-configuration

NPX Install

Tags

SKILL.md Content

Claude Code Settings Configuration

When to Use This Skill

Settings File Hierarchy

Permission Structure

Allow vs Deny

Wildcard Permission Patterns

Syntax

Pattern Examples

Specificity

Shell Operator Protections

Protected Operators

Behavior

Safe Alternative

Common Permission Sets

Git Operations

GitHub CLI

Testing & Linting

Security Scanning

MCP Tools

Project Setup

1. Create Settings Directory

2. Create Project Settings

3. Gitignore Local Settings

4. Create Local Overrides (optional)

Validating Settings

Check JSON Syntax

View Permissions

Merge Preview

Troubleshooting

Agentic Optimizations

Quick Reference

File Locations

Permission Syntax

Priority