Configuration

ReSpex merges configuration in this order:

built-in defaults
       ↓
user config
       ↓
project .respex/config.toml

Project-level values override user-level values field by field. Arrays replace wholesale; an empty array or string means “not set” and does not unset an inherited value.

Setup commands

respex config init                 # create user config
respex config init --local         # create project config
respex config path                 # print user config path
respex config path --local         # print project config path
respex config edit                 # edit user config
respex config edit --local         # edit project config
respex config validate             # validate user config
respex config validate --local     # validate merged project config
respex config show                 # show effective values and sources
respex config show --json

Example user config

spec = "SPEC.md"
spec_files = []                            # extra bundle files for large projects
notes = ".respex/notes.md"                   # scratchpad for ideas not yet in the spec
editor = ["code", "--wait"]                # optional editor argv
pager = ["less", "-FRX"]                   # optional pager argv
agent_timeout = "1h"                         # hard limit; Go duration syntax

[agent]
command = ["claude", "-p", "{{prompt}}"]   # argv array — any agentic CLI
# command = ["devin", "--print", "{{prompt}}"]
# command = ["codex", "exec", "{{prompt}}"]
# command = ["gemini", "-p", "{{prompt}}"]
# command = ["opencode", "run", "{{prompt}}"]
delivery = "argv"                            # or "stdin" for long prompts
env = []

[prompts]
# Optional overrides for built-in prompts. {{prompt}} carries the description for
# draft/baseline. For baseline, {{spec_path}} is a proposal directory where the
# agent must write SPEC.md; other prompts receive a spec file or directory.
# draft    = "..."
# baseline = "..."
# refine   = "..."
# apply    = "..."
# verify   = "..."

[verify]
# Optional conformance checks run by respex verify and chained after each
# whole-version apply. Commands run in order against the working tree and
# stop at the first failure; an empty list keeps verification off.
# commands = [["go", "build", "./..."], ["go", "test", "./..."]]
# timeout = "30m"                             # hard limit for the whole run
# env = []                                    # extra environment, e.g. ["GOFLAGS=-count=1"]
# audit = false                               # also let the configured agent audit conformance

Verification

[verify] configures conformance checks run by respex verify and chained after every whole-version respex apply. Commands run in order against the working tree with the project root as working directory; the run stops at the first failing command and the rest are recorded as skipped. Exit code is 0 only when every check passed. Verification is opt-in: an empty or absent commands list with audit disabled keeps it off. When it is configured, apply counts a version as “already applied” only while its latest verification passed — see Verification.

With audit = true, the configured agent additionally audits conformance against the committed spec after the command checks pass; its CONFORMS: yes/no reply counts as a check. Override the audit prompt with [prompts] verify.

Editor and pager

respex edit uses the configured editor, then VISUAL, then EDITOR. GUI editors should include their wait argument (for example, code --wait). VISUAL/EDITOR values with arguments are parsed safely.

respex view uses the configured pager, then PAGER, then less -FRX / more. Piped or redirected output receives exact Markdown without decoration.

Agent non-interactive mode

Agent CLIs must run non-interactively. For Devin CLI, use:

[agent]
command = ["devin", "--print", "{{prompt}}"]

Success means exit code 0. Output is captured under .respex/logs/. Interactive terminals show an elapsed-time spinner; disable with --no-progress or NO_COLOR.