# Settings

> Configure Claude Code with global and project-level settings, and environment variables.

Claude Code offers a variety of settings to configure its behavior. You can configure Claude Code by running the `/config` command in interactive mode.

## Configuration Scopes

| Scope       | Location                             | Who it affects                       | Shared with team?      |
| :---------- | :----------------------------------- | :----------------------------------- | :--------------------- |
| **Managed** | System-level `managed-settings.json` | All users on the machine             | Yes (deployed by IT)   |
| **User**    | `~/.claude/` directory               | You, across all projects             | No                     |
| **Project** | `.claude/` in repository             | All collaborators on this repository | Yes (committed to git) |
| **Local**   | `.claude/*.local.*` files            | You, in this repository only         | No (gitignored)        |

### Configuration Types and Locations

| Type            | User Level                | Project Level                      | Local Level                    |
| :-------------- | :------------------------ | :--------------------------------- | :----------------------------- |
| **Settings**    | `~/.claude/settings.json` | `.claude/settings.json`            | `.claude/settings.local.json`  |
| **Plugins**     | `~/.claude/settings.json` | `.claude/settings.json`            | `.claude/settings.local.json`  |
| **CLAUDE.md**   | `~/.claude/CLAUDE.md`     | `CLAUDE.md` or `.claude/CLAUDE.md` | `CLAUDE.local.md`              |

## Settings Files

### User Settings
`~/.claude/settings.json` - Apply to all projects.

### Project Settings
Saved in your project directory:
- `.claude/settings.json` - Checked into source control, shared with team
- `.claude/settings.local.json` - Not checked in, for personal preferences

### Managed Settings
For organizations needing centralized control:
- **macOS**: `/Library/Application Support/ClaudeCode/`
- **Linux/WSL**: `/etc/claude-code/`
- **Windows**: `C:\Program Files\ClaudeCode\`

These are system-wide paths requiring administrator privileges, designed for IT deployment.

## Permission Settings

### Permission Structure
```json
{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm:*)",
      "Task(dangerous-agent)"
    ]
  }
}
```

### Permission Rule Syntax

| Pattern           | Meaning                                                    |
| :---------------- | :--------------------------------------------------------- |
| `Bash`            | Allow/deny all Bash commands                               |
| `Bash(npm:*)`     | Allow/deny commands starting with `npm`                    |
| `Bash(git diff:*)` | Allow/deny commands starting with `git diff`              |
| `Read`            | Allow/deny file reading                                    |
| `Write`           | Allow/deny file writing                                    |
| `Edit`            | Allow/deny file editing                                    |
| `Task(name)`      | Allow/deny specific subagent                               |
| `Skill(name)`     | Allow/deny specific skill                                  |
| `Skill(name:*)`   | Allow/deny skills with prefix match                        |

### Settings Precedence

Settings are merged from all sources with priority:
1. Managed settings (highest)
2. Command line flags
3. Local project settings
4. Project settings
5. User settings (lowest)

For `allow` and `deny` arrays, entries are combined from all levels (not replaced).

## Plugin Settings

```json
{
  "plugins": {
    "installed": [
      "plugin-name@marketplace-name"
    ],
    "disabled": [
      "plugin-name@marketplace-name"
    ]
  }
}
```

## Hook Settings

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $FILE"
          }
        ]
      }
    ]
  }
}
```

## Environment Variables

### Model Configuration

| Variable                         | Description                                                    |
| :------------------------------- | :------------------------------------------------------------- |
| `ANTHROPIC_MODEL`                | Model alias or name to use                                     |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`   | Model for `opus` alias or `opusplan` in Plan Mode              |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model for `sonnet` alias or `opusplan` outside Plan Mode       |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL`  | Model for `haiku` alias or background functionality            |
| `CLAUDE_CODE_SUBAGENT_MODEL`     | Model to use for subagents                                     |

### Behavior Configuration

| Variable                              | Description                                              |
| :------------------------------------ | :------------------------------------------------------- |
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`| Set to `1` to disable background task functionality      |
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`     | Percentage threshold for auto-compaction (default: 95)   |
| `USE_BUILTIN_RIPGREP`                 | Set to `0` to use system ripgrep instead of built-in     |
| `SLASH_COMMAND_TOOL_CHAR_BUDGET`      | Character budget for skill descriptions (default: 15000) |

### Prompt Caching

| Variable                        | Description                                          |
| :------------------------------ | :--------------------------------------------------- |
| `DISABLE_PROMPT_CACHING`        | Set to `1` to disable caching for all models         |
| `DISABLE_PROMPT_CACHING_HAIKU`  | Set to `1` to disable caching for Haiku models       |
| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable caching for Sonnet models      |
| `DISABLE_PROMPT_CACHING_OPUS`   | Set to `1` to disable caching for Opus models        |

### Updates

| Variable                    | Description                                          |
| :-------------------------- | :--------------------------------------------------- |
| `DISABLE_AUTOUPDATER`       | Set to `true` to disable all automatic updates       |
| `FORCE_AUTOUPDATE_PLUGINS`  | Set to `true` to enable plugin updates when autoupdater is disabled |

## Tools Available to Claude

Claude Code has access to these internal tools:

| Tool             | Purpose                                          |
| :--------------- | :----------------------------------------------- |
| `Read`           | Read file contents                               |
| `Write`          | Write file contents                              |
| `Edit`           | Edit file contents                               |
| `Bash`           | Execute shell commands                           |
| `Grep`           | Search file contents                             |
| `Glob`           | Find files by pattern                            |
| `Task`           | Spawn subagents                                  |
| `Skill`          | Invoke skills                                    |
| `WebFetch`       | Fetch web content                                |
| `WebSearch`      | Search the web                                   |
| `AskUserQuestion`| Ask user for clarification                       |
| `NotebookEdit`   | Edit Jupyter notebooks                           |

Plus MCP tools from configured MCP servers.

## Status Line Configuration

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}
```

## Output Style Configuration

```json
{
  "outputStyle": "explanatory"
}
```

Or use a custom style file path.

## Configuration File Locations Summary

| File                          | Purpose                                                  |
| :---------------------------- | :------------------------------------------------------- |
| `~/.claude/settings.json`     | User settings (permissions, hooks, model overrides)      |
| `.claude/settings.json`       | Project settings (checked into source control)           |
| `.claude/settings.local.json` | Local project settings (not committed)                   |
| `~/.claude.json`              | Global state (theme, OAuth, MCP servers)                 |
| `.mcp.json`                   | Project MCP servers (checked into source control)        |
| `managed-settings.json`       | Managed settings                                         |
| `managed-mcp.json`            | Managed MCP servers                                      |

## Grid Integration Opportunities

<!-- Placeholder for Grid-specific integration notes -->