Configuration

romp.toml reference, config layering, and defaults.

Configuration is TOML. romp init writes a starting romp.toml:

label          = "romp"           # trigger label
claimed_label  = "romp:claimed"
blocked_label  = "romp:blocked"
changes_requested_label = "romp:changes-requested"
base           = "main"           # default: repo default branch
width          = 3

[verify]
commands = [
  "go build ./...",
  "go test ./... -count=1",
  "golangci-lint run",
]

[scope]
protected = ["testdata/**", "internal/testutil/**", ".github/**"]
ignore    = ["vendor/**", "node_modules/**"]

[harness]
default   = "codex"              # claude | codex | opencode
model     = ""
effort    = "high"               # claude/codex: reasoning effort; opencode: model-specific variant
max_turns = 30                   # claude only; ignored by codex and opencode

[review]
enabled        = true
model          = ""             # missing or empty uses harness.model
harness        = ""             # missing or empty uses harness.default
max_fix_rounds = 2              # each round includes build, verify, push, and review

[prompt]
template = ".romp/prompt.md"     # optional
brief    = ".romp/DESIGN.md"     # optional

Precedence

Config merges in a fixed order — later layers override only the fields they set:

flags  →  .romp/local.toml  →  romp.toml  →  ~/.config/romp/config.toml  →  defaults

Zero means “use the lower layer” for builder settings. This applies to a zero width, an empty base, an unset max_turns, and other empty strings. Review settings have separate rules. review.enabled uses normal field-level layering, so omission retains the lower-layer value and an explicit false disables review. review.max_fix_rounds also uses field-level layering, including an explicit zero. A higher-precedence [review] table resets review.model and review.harness to the effective builder settings unless that table supplies non-empty replacements. Missing and explicit empty values both select harness.model and harness.default, not lower-layer reviewer overrides. Commit romp.toml and .romp/*.md; keep local.toml out of git (romp adds it to .gitignore for you).

Unknown keys under [review] are rejected when any configuration layer loads. Unrelated unknown keys retain the loader’s existing ignore behavior.

history_days is the one exception — it is read only from the user config (~/.config/romp/config.toml), never from romp.toml. Retention is an operator concern, not a team convention.

Omit timeout to let jobs run without a deadline. Set it to a Go duration string such as 25m, 1.5h, or 2h45m when a job needs a deadline. The deadline covers the builder, verification, read-only review, and all configured fix rounds as one budget. Review does not consume another job-width slot, but each pass starts one concurrent harness process per routed lens.

Full reference

Key	Default	Notes
`label`	`romp`	The trigger label.
`claimed_label`	`romp:claimed`	Marks an issue as taken.
`blocked_label`	`romp:blocked`	Marks an under-scoped issue.
`changes_requested_label`	`romp:changes-requested`	Marks a job whose blocking review findings exhausted the configured fix rounds.
`base`	repo default branch	Branch worktrees fork from.
`width`	`3`	Max concurrent jobs in this repo.
`timeout`	unbounded	Optional per-job deadline as a Go duration string.
`verify.commands`	—	Ordered commands that Romp runs independently after the agent exits.
`scope.protected`	—	Paths the agent must not touch.
`scope.ignore`	—	Paths the agent must not read.
`harness.default`	`codex`	`claude`, `codex`, or `opencode`.
`harness.model`	—	Specific model, or empty for the harness default.
`harness.effort`	`high`	Reasoning effort for Claude/Codex; model-specific OpenCode variant (see below).
`harness.max_turns`	—	Turn cap, claude only.
`review.enabled`	`true`	Enables the review gate for watched and one-shot jobs. Each pass runs one concurrent reviewer call per routed lens.
`review.model`	builder model	Reviewer model; missing or empty uses `harness.model`.
`review.harness`	builder harness	Reviewer harness; missing or empty uses `harness.default`.
`review.max_fix_rounds`	`2`	Maximum builder, verification, push, and re-review cycles after a blocking review. Set `0` to report `changes-requested` without a fix attempt.
`prompt.template`	—	Custom goal-contract template.
`prompt.brief`	—	File the agent reads first (e.g. `.romp/DESIGN.md`).
`history_days`	`30`	Global only; outcome retention window.

For OpenCode, harness.effort is passed as opencode run --variant. Variant names are model-specific. Romp prints one warning at startup when the effective variant comes from a configuration file. A command-line --effort override does not produce this configuration warning.

Verify

romp refuses to run without a verify command — it never guesses. commands must contain at least one command. romp re-runs each command through the project shell after the agent exits, in order, and opens the PR only when all of them pass. Commands may include shell syntax such as pipes, redirects, and environment assignments.

Harness effort and variants

The legal effort values depend on the harness. Shared names mean the same thing and pass through unchanged. Claude and Codex values are validated at config load. OpenCode values are passed as model-specific variants and are not validated by Romp.

Harness	Effort values
`claude`	`low`, `medium`, `high`, `xhigh`, `max`
`codex`	`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`
`opencode`	Model-specific `--variant` values; not validated by Romp

romp doctor checks the effective reviewer harness when review is enabled. A cross-harness setup must have both the builder and reviewer CLIs installed and healthy.

Where state lives

State lives outside the repo:

~/.local/state/romp/romp.db — the shared job table (SQLite, one per machine)
~/.local/state/romp/<owner>-<repo>/logs/ — per-job logs
Worktrees under the OS cache dir (~/Library/Caches/romp/<owner>-<repo>/romp-N on macOS)