settings-reference

Claude Code Settings Reference

Configure Claude Code behavior through settings files at different scopes.

Settings Hierarchy (Priority Order)

Priority	Location	Purpose
1 (highest)	Enterprise managed	Organization policies
2	.claude/settings.local.json	Project personal (gitignored)
3	.claude/settings.json	Project team (shared)
4	~/.claude/settings.json	User global

Higher priority settings override lower.

Settings File Locations

/Library/Application Support/ClaudeCode/settings.json  # Enterprise (macOS)
~/.claude/settings.json                                 # User global
.claude/settings.json                                   # Project team
.claude/settings.local.json                             # Project personal

Common Settings

Tool Permissions

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm test)",
      "Read",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf /)"
    ]
  }
}

Model Selection

{
  "model": "claude-sonnet-4-20250514",
  "preferredModels": {
    "default": "claude-sonnet-4-20250514",
    "agents": "claude-haiku-3-5-20240307"
  }
}

MCP Servers

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Hooks

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo 'Bash tool used'"
      }]
    }]
  }
}

Permission Patterns

Exact Match

"allow": ["Bash(npm test)"]

Wildcard

"allow": ["Bash(npm *)"]

Tool Only

"allow": ["Read", "Write"]

Regex (in matcher)

"allow": ["Bash(npm (test|build))"]

Settings Merging

Settings merge across files:

• Arrays: concatenated
• Objects: deep merged
• Primitives: higher priority wins

Environment Variables

{
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  }
}

These are set when Claude runs Bash commands.

Plugin Settings

Enable Plugins

{
  "enabledPlugins": {
    "formatter@marketplace": true,
    "linter@marketplace": true
  }
}

Add Marketplace

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "org/claude-plugins"
      }
    }
  }
}

Restrict Marketplaces

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "approved/plugins"
    }
  ]
}

Trust Settings

{
  "trust": {
    "autoTrustDirectories": [
      "~/projects"
    ]
  }
}

Editor Integration

{
  "editor": {
    "command": "code",
    "args": ["--wait", "$FILE"]
  }
}

Debugging Settings

View effective settings:

/settings

Check specific scope:

/settings user
/settings project

Settings Commands

Command	Description
/settings	View/edit settings
/config	Configuration wizard
/permissions	Tool permission management

Common Configuration Patterns

Development Project

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(git *)",
      "Read",
      "Write",
      "Edit"
    ]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write"
      }]
    }]
  }
}

Restricted Production

{
  "permissions": {
    "deny": [
      "Bash(rm *)",
      "Bash(git push *)"
    ]
  }
}

---

For complete documentation, see:

• settings-full.md - Complete settings reference