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.
{
"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.
{
"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:
Config field
Reads apiKey from the active settings (any layer).
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"
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"
}
}
}
}
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
}
}
| 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
Settings struct in cc-core exposes Settings::load() and Settings::save(), which deserialize from and serialize to ~/.claude/settings.json.