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, intent tracking, attention thresholds, and per-agent settings for a single project.

Top-level

[orchestration]

[agent]

Controls how prompt steps are dispatched.

[agent]
mode = "mcp"   # "prompt" (default) or "mcp"

[agents.<name>]

Per-agent configuration. The section name matches the agent command (e.g. [agents.codex]).

[help]

Controls the help channel (clo ask / ask_user MCP tool / cloche threads).

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.

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.

[intent]

Controls requirement extraction and prompt injection for Intent Continuity. Requirements live in .cloche/intent/ and are prepended to agent-step prompts automatically; see the Intent Continuity page for the concepts, and the cloche intent command for the CLI.

[intent]
embedder = "onnx"        # "onnx" | "ollama" | "keyword"; unset = default chain
token_budget = 0         # 0 = ~2000-token default
scan_after_tasks = true
# inject = "off"         # disable injection project-wide

[attention]

Thresholds used to derive the “Needs you” set — items that require human action — shown by cloche status and the web console (via the /api/projects, /api/projects/{slug}/attention, and /api/projects/occupancy endpoints and the daemon’s GetAttention RPC).

The attention set is served from a per-project cache the daemon refreshes in the background; the refresh cadence is configured daemon-wide, not per project — see [attention] (daemon-wide) below.

[[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"

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

[intent]
scan_after_tasks = true

[attention]
repeat_failure_threshold = 3
long_poll_threshold = "2h"

[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]

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

[attention] (daemon-wide)

The “Needs you” set for every registered project is computed by a background cache rather than by running each project’s tracker on every request. The cache recomputes on a timer — and immediately after a run reaches a terminal state or a help thread changes — so a project that hasn’t been refreshed yet reports an empty set (with computed_at unset) instead of blocking. The per-project thresholds live in each project’s .cloche/config.toml; the cache cadence is set here.

# ~/.config/cloche/config
[attention]
refresh_interval = "60s"
max_parallel_refresh = 4

[[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"

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.