Configuration

Code CLI uses a 7-level cascading configuration system. Higher levels override lower ones.

Precedence (low to high)

PrioritySourceLocation
1 (lowest)Remote well-known.well-known/codecli on org domain
2Global config~/.config/codecli/codecli.json
3Custom configCODECLI_CONFIG env var path
4Project config./codecli.json in project root
5.codecli directory./.codecli/config.json
6Inline configCODECLI_CONFIG_CONTENT env var
7 (highest)Managed config/etc/codecli/codecli.json (enterprise)

Example Configuration

codecli.json
json
{
{"$"}schema: "https://codecli.ai/config.json",
"model": "anthropic/claude-sonnet-4-20250514",
"small_model": "anthropic/claude-haiku-4-5-20251001",
"default_agent": "build",
"theme": "dark",
"permission_mode": "default",
"agent": {
"build": {
"model": "anthropic/claude-sonnet-4-20250514",
"temperature": 0.3,
"steps": 10,
"permission": { "edit": "ask", "bash": "ask" }
}
},
"mcp": {
"filesystem": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."],
"enabled": true
}
},
"hooks": {
"post_tool_use": [{
"matcher": "write(*)",
"command": "npx prettier --write {"$"}1",
"timeout": 5000
}]
},
"permission": {
"read": "allow",
"glob": "allow",
"grep": "allow",
"edit": "ask",
"bash": "ask"
}
}

Key Sections

SectionDescription
modelDefault AI model in provider/model format
agentPer-agent model, temperature, permissions, system prompt
mcpMCP server configurations (local and remote)
hooksExtension hooks for pre/post tool use, session lifecycle
permissionPer-tool permission rules (allow, ask, deny)
providerPer-provider API keys, base URLs, model whitelists
compactionContext compaction thresholds and strategies
experimentalExperimental feature flags
PreviousQuick StartNextAuthentication