# settings.json Schema Reference

## File Locations

| Location | Precedence | Purpose |
|----------|------------|---------|
| `~/.claude/settings.json` | Lowest | User defaults |
| `.claude/settings.json` | Medium | Project shared |
| `.claude/settings.local.json` | High | Project local |
| CLI arguments | Highest | Session only |

## Schema

```json
{
  // Default model for the project
  "model": "sonnet",

  // Permission rules
  "permissions": {
    // Tools allowed without prompting
    "allow": [
      "Read",
      "Write",
      "Bash(npm*)",
      "Bash(git*)"
    ],
    // Tools that always require approval
    "deny": [
      "Bash(rm -rf*)"
    ]
  },

  // Environment variables to set
  "env": {
    "NODE_ENV": "development"
  },

  // Hooks configuration
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...]
  },

  // MCP server configuration (can also be in .mcp.json)
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem"],
      "env": {}
    }
  },

  // Custom agents path
  "agents": "./agents",

  // Plugins to load
  "plugins": [
    "~/plugins/my-plugin"
  ]
}
```

## Key Settings

### model

Default model for this project/user:

```json
{
  "model": "sonnet"  // or "opus", "haiku"
}
```

### permissions

Control tool access:

```json
{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Bash(npm *)",
      "Bash(git *)",
      "Task"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}
```

Patterns support wildcards:
- `*` matches any characters
- `Bash(npm*)` matches `npm install`, `npm test`, etc.

### env

Environment variables:

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

### hooks

Event-driven automation:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'About to run bash'"
      }
    ]
  }
}
```

## Merging Behavior

When multiple settings files exist:
- Objects are merged recursively
- Arrays are replaced, not merged
- Higher precedence wins for conflicts