Configuration

Every section and key of speccoder.toml: checks, model, budget, commands, tests, acceptance, sandbox, mutation, monitor, executor, MCP servers and more.

speccoder is configured by speccoder.toml at the project root. It reads only the committed file, so a change is reviewed like code. speccoder init writes a commented one. Unknown sections and keys are errors (CONFIG-INVALID).

[checks.test]
argv = ["cargo", "nextest", "run", "--workspace", "--profile", "speccoder"]
junit = "target/nextest/speccoder/junit.xml"

[checks.clippy]
argv = ["cargo", "clippy", "--all-targets", "--", "-D", "warnings"]
tier = "full"

[model]
provider = "anthropic"
model = "claude-sonnet-5-5"

[commands]
allow = [["cargo", "test"], ["cargo", "check"]]

[sandbox]
network_allow = [["cargo", "fetch"]]

Changing it

Edit the file, or use speccoder config (or Settings in the web interface). Its edits are checked by every parser before they are written, and keep the file’s comments, order and layout. A change takes effect once committed.

speccoder config                                   # every key: its value, or its default
speccoder config get budget.max_turns
speccoder config set budget.max_turns 40
speccoder config set format.argv cargo fmt         # words, read by the key's kind
speccoder config set commands.allow '[["cargo", "check"]]'   # or JSON
speccoder config set checks.lint.argv -- cargo clippy -- -D warnings   # words starting with - after --
speccoder config unset budget.max_turns            # back to the default
speccoder config commit                            # commits speccoder.toml, and nothing else

[checks.<name>]

The commands that decide whether nothing regressed. A check’s command up to its first option is also a prefix the model may run (cargo nextest run … allows cargo nextest run with any arguments); when that leaves only the program (python3 -m pytest …), the check allows exactly itself.

[model]

The API key comes from the environment, never from this file. A local model must support tool calls and structured output; the evaluation suite tells whether it is good enough.

Amazon Bedrock

[model]
provider = "bedrock"
model = "global.anthropic.claude-sonnet-5-5"
region = "eu-central-1"

Credentials come from the AWS credential chain where you start speccoder: a Bedrock API key in AWS_BEARER_TOKEN_BEDROCK (it wins over everything else), or a profile (AWS_PROFILE, else default) — an aws login session, SSO, credential_process, static keys or a role — or keys, web identity or a container role from the environment. speccoder doctor names the source it will use and the region, never a value. Claude models get prompt caching; other families run without it. For exact costs, state all four prices (unstated cache-write prices for Claude follow Anthropic’s rule).

speccoder config set model.provider bedrock, then speccoder config set model.region <region>; the file is refused until the region is set.

[budget]

[commands], [approvals], [tests], [spec]

Prefix lists

[commands] allow and [sandbox] network_allow match exact argvs. A prefix in allow_prefix / network_allow_prefix lets every command that starts with it run without asking, including commands nobody has seen, so no approval ever writes one and a bare program is refused.

speccoder config coverage commands.allow_prefix npm run     # the preview only
speccoder config set commands.allow_prefix npm run          # shows it, then: type yes

• config coverage KEY PREFIX… lists every distinct command the project’s journal recorded that the prefix would newly allow: how often, when last, how it was decided, and which a fixed rule (shells, privilege, network tools, remote git) still asks for or denies.
• config set (and Save Prefix in Settings) saves the prefix only as the confirmation of that list: yes at a terminal, --yes without asking; otherwise it exits needing a person. It is refused when the preview changed since it was shown, and while the journal cannot be read in full.
• A prefix added by hand shows the same list in Settings (Coverage). Removing an entry needs no preview.

[context]

[acceptance], [converge], [review], [monitor], [git], [format]

[bug]

speccoder bug. Project settings only: the same keys in your user config are ignored, with a warning naming them.

[sandbox]

What the sandbox allows: the OS sandbox.

[worktree]

What a run’s worktree gets that git never holds; see dependency folders and copied files.

speccoder init proposes include with your checkout’s git-ignored .env files, or says that .worktreeinclude already names them.

[attest]

Signed attestations of every tick. The signer is part of the judge configuration the statements’ policy hash covers.

[mutation]

[executor]

Who makes the attempts; see external agents. Without the section, speccoder’s own loop.

[mcp.<name>]

Server names are lowercase letters, digits and -, and not fs, proc or git. Their tools appear to the model as mcp__<server>__<tool>.

Your settings

How speccoder looks and notifies you is your setting, not the project’s. It lives in $XDG_CONFIG_HOME/speccoder/config.toml (else ~/.config/speccoder/config.toml); a [ui] table in speccoder.toml is refused (exit 13).

[ui]
theme = "auto"         # auto | dark | light | high-contrast | daltonized | mono
color = "auto"         # auto | always | never; --color wins, this wins over NO_COLOR
ascii = false          # [ok] [~] [A] … instead of ✓ ~ A …, plain box borders
screen_reader = false  # labelled plain lines, no dashboard

[ui.notify]
on = ["approval", "task_failed"]   # the default: what blocks work; add "feature_done", "stalled"
when = "unfocused"     # or "always"
method = "auto"        # auto | osc9 | osc777 | bel | command | off
command = []           # with method = "command": program and arguments; the message is appended
stall_after = "15m"    # Ns | Nm | Nh, at least 30s

• Themes: auto uses the terminal’s 16 colours, following its palette; dark and light are fixed 24-bit palettes; daltonized uses blue and orange instead of green and red; mono uses only bold, dim, underline and reverse.
• Notifications: auto sends a desktop notification where the terminal shows one, a bell elsewhere. command runs without a shell, for at most five seconds (e.g. ["terminal-notifier", "-title", "speccoder", "-message"]).
• A value speccoder does not understand is a warning; the default applies.

Environment

Edit this page