> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Claurst uses a layered settings system — global, project, local project, and managed — that merge at runtime with later layers taking precedence.

Claurst reads configuration from up to four settings files, merged in priority order. Higher layers override lower ones.

## Settings layers

| Layer             | File                          | Scope           | Notes                                  |
| ----------------- | ----------------------------- | --------------- | -------------------------------------- |
| **Managed**       | Platform-managed path         | Read-only       | Enterprise/managed environments only   |
| **Local project** | `.claude/settings.local.json` | Current project | Gitignored — not shared with teammates |
| **Project**       | `.claude/settings.json`       | Current project | Committed to source control            |
| **Global**        | `~/.claude/settings.json`     | All projects    | User-level defaults                    |

<Info>
  The managed layer is read-only and cannot be overridden by user settings. It is intended for enterprise environments where administrators need to enforce policy.
</Info>

## Global settings file

`~/.claude/settings.json` applies to all projects. Use it for personal preferences such as your model choice, theme, and API key.

```json ~/.claude/settings.json theme={null}
{
  "model": "claude-sonnet-4-6",
  "apiKey": "sk-ant-...",
  "theme": "dark",
  "verboseOutput": false,
  "autoCompact": true,
  "permissions": {
    "allow": [
      "Bash(git *)",
      "FileRead(*)",
      "WebFetch(https://docs.anthropic.com/*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | sh)"
    ]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}
```

## Project settings file

`.claude/settings.json` at the root of your project is committed to version control and shared with your team. Use it to define project-specific permission rules, model overrides, and MCP server configurations.

```json .claude/settings.json theme={null}
{
  "model": "claude-opus-4-6",
  "permissions": {
    "allow": [
      "Bash(cargo *)",
      "Bash(make *)",
      "FileEdit(src/**)",
      "FileWrite(src/**)"
    ],
    "deny": [
      "Bash(cargo publish *)",
      "Bash(git push --force *)"
    ]
  },
  "mcpServers": {
    "project-db": {
      "command": "./scripts/mcp-db-server",
      "args": ["--read-only"]
    }
  }
}
```

<Note>
  `.claude/settings.local.json` follows the same schema as `.claude/settings.json` but is gitignored. Use it for personal overrides that should not be shared, such as local API keys or per-developer permission rules.
</Note>

## Key settings fields

| Field               | Type                                | Description                                                                             |
| ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------- |
| `model`             | `string`                            | Model to use for this session. See [model names](#model-selection) below.               |
| `apiKey`            | `string`                            | Anthropic API key. Prefer the `ANTHROPIC_API_KEY` environment variable instead.         |
| `theme`             | `"dark"` \| `"light"` \| `"system"` | Terminal color theme.                                                                   |
| `verboseOutput`     | `boolean`                           | Show extended debug output. Default: `false`.                                           |
| `autoCompact`       | `boolean`                           | Automatically compact the context window when it approaches the limit. Default: `true`. |
| `permissions.allow` | `string[]`                          | Tool call patterns that are always permitted without a prompt.                          |
| `permissions.deny`  | `string[]`                          | Tool call patterns that are always blocked.                                             |
| `mcpServers`        | `object`                            | MCP server definitions keyed by server name.                                            |
| `betaFeatures`      | `object`                            | Enable opt-in beta API features.                                                        |
| `spinnerVerbs`      | `object`                            | Customize or extend the spinner verb list.                                              |

## Model selection

Set the `model` field to any of the supported model IDs:

| Model ID                    | Description                                                      |
| --------------------------- | ---------------------------------------------------------------- |
| `claude-opus-4-6`           | Most capable model. Default in the Rust crate (`DEFAULT_MODEL`). |
| `claude-sonnet-4-6`         | Balanced performance and speed.                                  |
| `claude-haiku-4-5-20251001` | Fastest and most economical.                                     |

```json theme={null}
{
  "model": "claude-sonnet-4-6"
}
```

## API key configuration

Claurst resolves your API key in this order:

<Steps>
  <Step title="Config field">
    Reads `apiKey` from the active settings (any layer).
  </Step>

  <Step title="Environment variable">
    Falls back to the `ANTHROPIC_API_KEY` environment variable.
  </Step>
</Steps>

```bash theme={null}
export ANTHROPIC_API_KEY="sk-ant-..."
```

<Tip>
  Store your API key in the environment variable rather than a settings file. This prevents it from being accidentally committed to version control, even in `.claude/settings.local.json`.
</Tip>

## Custom API endpoint

Set `ANTHROPIC_BASE_URL` to route requests to a custom endpoint — useful for proxies, enterprise gateways, or local model servers:

```bash theme={null}
export ANTHROPIC_BASE_URL="https://my-proxy.example.com"
```

In the Rust config, `resolve_api_base()` checks this environment variable first, falling back to `https://api.anthropic.com`.

## Permission rules

Permission rules use glob-style patterns scoped to tool categories. Each rule matches `ToolName(argument_pattern)`.

**Tool categories:**

| Category    | Controls                      |
| ----------- | ----------------------------- |
| `Bash`      | Shell command execution       |
| `FileRead`  | Reading files and directories |
| `FileEdit`  | Editing existing files        |
| `FileWrite` | Creating new files            |
| `WebFetch`  | HTTP requests                 |
| `MCP`       | MCP server tool calls         |

```json theme={null}
{
  "permissions": {
    "allow": [
      "Bash(git log *)",
      "Bash(cargo test *)",
      "FileRead(**)",
      "WebFetch(https://docs.rs/*)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git push --force *)",
      "WebFetch(http://*)"
    ]
  }
}
```

<Warning>
  Rules in the `deny` list take precedence over `allow` rules. A tool call matching both lists will be blocked.
</Warning>

## MCP server configuration

Define MCP servers that Claurst should connect to at startup. Each entry in `mcpServers` launches a subprocess via stdio transport.

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/mcp-server"],
      "env": {
        "MY_SERVER_TOKEN": "abc123"
      }
    }
  }
}
```

The `McpServerConfig` struct in `cc-core` supports:

| Field     | Type       | Description                                          |
| --------- | ---------- | ---------------------------------------------------- |
| `command` | `string`   | Executable to launch.                                |
| `args`    | `string[]` | Arguments passed to the command.                     |
| `env`     | `object`   | Additional environment variables for the subprocess. |
| `url`     | `string`   | Optional: URL for network-based MCP servers.         |

## Beta features

Some API features must be explicitly opted into via beta headers. The `betaFeatures` field maps feature names to booleans:

```json theme={null}
{
  "betaFeatures": {
    "interleavedThinking": true,
    "extendedContext": true
  }
}
```

Known beta headers negotiated by Claurst include:

| Feature               | Header                             |
| --------------------- | ---------------------------------- |
| Interleaved thinking  | `interleaved-thinking-2025-05-14`  |
| 1M token context      | `context-1m-2025-08-07`            |
| Context management    | `context-management-2025-06-27`    |
| Structured outputs    | `structured-outputs-2025-12-15`    |
| Token-efficient tools | `token-efficient-tools-2026-03-28` |

## Reading and writing settings programmatically

The `ConfigTool` (available in internal builds) and the `/config` slash command allow reading and writing individual settings fields at runtime:

```
/config set model claude-sonnet-4-6
/config get model
```

The `Settings` struct in `cc-core` exposes `Settings::load()` and `Settings::save()`, which deserialize from and serialize to `~/.claude/settings.json`.