Configuration Reference
Cloche uses two configuration files: a per-project config and a global user config.
Project Configuration (.cloche/config.toml)
Created by cloche init. Controls orchestration behavior, evolution, and per-agent settings for a single project.
Top-level
| Key | Default | Description |
|---|---|---|
active |
true |
Set to true to auto-start the orchestration loop when the daemon starts. |
[orchestration]
| Key | Default | Description |
|---|---|---|
concurrency |
1 |
Maximum concurrent container runs. |
stagger_seconds |
1.0 |
Delay (seconds) between consecutive run launches. |
dedup_seconds |
300 |
Window (seconds) to suppress re-assigning the same task ID. |
stop_on_error |
false |
Halt the orchestration loop on the first unrecovered error. |
max_consecutive_failures |
3 |
Stop the loop after this many consecutive failed runs. Run cloche loop to restart. |
[evolution]
Controls the self-evolving prompt system. Requires CLOCHE_LLM_COMMAND to be set; evolution is silently disabled when it is not.
| Key | Default | Description |
|---|---|---|
enabled |
true |
Enable or disable evolution for this project. |
debounce_seconds |
30 |
Seconds to wait after a run completes before triggering an evolution pass (debounces rapid successive completions). |
min_confidence |
"medium" |
Minimum lesson confidence to include in prompts. One of "low", "medium", "high". |
[agents.<name>]
Per-agent configuration. The section name matches the agent command (e.g. [agents.codex]).
| Key | Default | Description |
|---|---|---|
usage_command |
(unset) | Shell command run after each step using this agent to capture token usage. Output must be JSON: {"input_tokens": N, "output_tokens": N}. |
Example:
active = true
[orchestration]
concurrency = 2
stagger_seconds = 1.0
dedup_seconds = 300
stop_on_error = false
max_consecutive_failures = 3
[evolution]
enabled = true
debounce_seconds = 30
min_confidence = "medium"
[agents.codex]
usage_command = "codex usage --last --json"
User Configuration (~/.config/cloche/config)
The global daemon configuration file. Created automatically by cloche init if it does not already exist.
[daemon]
| Key | Default | Description |
|---|---|---|
http |
localhost:8080 |
HTTP address for the web dashboard. The dashboard is not started if this is unset (and CLOCHE_HTTP is not set). |
Example:
[daemon]
http = "localhost:8080"
Choose any available port. To bind to a specific interface:
[daemon]
http = "127.0.0.1:9090"
The CLI commands cloche tasks and cloche health also require http to be set, since they talk to the daemon’s HTTP API.
You can also pass the dashboard address as an environment variable instead of using the config file:
CLOCHE_HTTP=localhost:8080 cloched