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