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 |
0 |
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". |
max_prompt_bullets |
50 |
Maximum number of lesson bullets injected into agent prompts. |
population_enabled |
false |
Enable population-based candidate selection (experimental). |
max_candidates |
5 |
Maximum number of prompt candidates to evaluate per evolution pass. |
min_runs_to_promote |
5 |
Minimum completed runs before a candidate can be promoted to the active prompt. |
[agent]
Controls how prompt steps are dispatched.
| Key | Default | Description |
|---|---|---|
mode |
"prompt" |
Dispatch mode for prompt (agent-type) steps. "prompt" launches a headless claude -p process inside the container. "mcp" parks prompt steps until an interactive MCP client calls init, next, and submit-result on the daemon’s MCP server (/mcp). Script steps are unaffected by this setting. |
[agent]
mode = "mcp" # "prompt" (default) or "mcp"
[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}. |
[help]
Controls the help channel (clo ask / ask_user MCP tool / cloche threads).
| Key | Default | Description |
|---|---|---|
park_after |
"5m" |
Duration string. How long an ask blocks in place before parking the run: the container is committed and stopped, and the run’s state becomes parked until a reply resumes it. Overridable per ask with --no-park (clo ask) / no_park (ask_user), which disables parking and blocks in place instead. |
retention |
"720h" |
Duration string. How long archived threads (from completed tasks) are kept before the daemon’s daily sweep deletes them. |
Questions always flow via cloche threads, which needs no configuration. To also deliver them to a user-side integration, add one or more [[help.channel]] tables in the daemon (global) config — see User Configuration below.
[git]
Identity used for cloche-authored git commits: the extraction commit made when results are pulled out of a container, and the scaffolded rebase/merge scripts that run on the host. Per-project values override the same keys in the global config at ~/.config/cloche/config. When both are unset, commits attribute to cloche <cloche@local>.
Use a distinct identity (for example a dedicated GitHub bot account or a users.noreply.github.com email) to keep agent-authored commits separable from your own and to let GitHub treat agent PRs as reviewable by you.
| Key | Default | Description |
|---|---|---|
name |
(unset) | GIT_AUTHOR_NAME / GIT_COMMITTER_NAME for cloche-authored commits. Falls back to cloche when unset. |
email |
(unset) | GIT_AUTHOR_EMAIL / GIT_COMMITTER_EMAIL for cloche-authored commits. Falls back to cloche@local when unset. |
ssh_key |
(unset) | Path to a private key used for git push in workflow scripts. ~ is expanded. |
Host scripts receive the resolved identity and push credentials as env vars (CLOCHE_GIT_AUTHOR_NAME, CLOCHE_GIT_AUTHOR_EMAIL, CLOCHE_GIT_SSH_COMMAND) — see the CLI reference environment variables. Any workflow script that commits or pushes on the bot’s behalf should honor these env vars with a local fallback, so it still works when nothing is configured. The scaffolded merge.py script follows this pattern.
[[repositories]]
Declares the source-code repositories available to the project. Each entry is a TOML array-of-tables item:
[[repositories]]
name = "backend"
path = "./repos/backend"
[[repositories]]
name = "frontend"
path = "./repos/frontend"
| Key | Default | Description |
|---|---|---|
name |
(required) | Identifier used to reference this repository from workflow repos fields. |
path |
(required) | Path relative to the project root. |
url |
(unset) | Remote URL (informational; not used by the runtime). |
Repositories appear in cloche project output and in cloche project repos list. Workflows opt into a subset of repositories with the repos field, which the runtime enforces for container seeding and result extraction.
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 command cloche health also requires http to be set, since it talks to the daemon’s HTTP API. cloche tasks falls back to localhost:8080 when it is unset.
You can also pass the dashboard address as an environment variable instead of using the config file:
CLOCHE_HTTP=localhost:8080 cloched
[[help.channel]]
Delivers agent help-channel questions to a user-side integration in addition to cloche threads. Daemon config only — these tables are not read from project config.
# ~/.config/cloche/config
[[help.channel]]
type = "slack"
channel = "#cloche" # default Slack channel
token_env = "SLACK_BOT_TOKEN" # env var holding the bot token (xoxb-...)
app_token_env = "SLACK_APP_TOKEN" # env var holding the app-level token (xapp-...)
[help.channel.channel_map] # optional: route cloche channels to distinct Slack channels
mazd = "#mazd-cloche"
| Key | Default | Description |
|---|---|---|
type |
(required) | Channel integration type. "slack" is the only supported type so far; an unknown type fails daemon start. |
channel |
(unset) | Default Slack channel to post to. |
token_env |
(unset) | Env var holding the Slack bot token. |
app_token_env |
(unset) | Env var holding the Slack app-level token (Socket Mode). |
channel_map |
(unset) | Table mapping cloche-side channel names (project names) to distinct Slack channels; cloche channels absent from the map fall back to channel. |
A channel that fails to initialize (e.g. missing token env var) only logs a warning and is skipped — the CLI channel keeps working regardless.