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

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.

Global settings file

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

~/.claude/settings.json

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

.claude/settings.json

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

.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.

Key settings fields

Field	Type	Description
model	string	Model to use for this session. See model names 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.

{
  "model": "claude-sonnet-4-6"
}

API key configuration

Claurst resolves your API key in this order:

1. Config field

   Reads apiKey from the active settings (any layer).

2. Environment variable

   Falls back to the ANTHROPIC_API_KEY environment variable.

export ANTHROPIC_API_KEY="sk-ant-..."

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.

Custom API endpoint

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

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

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

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

MCP server configuration

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

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

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