Configuration Reference

Use environment variables only when the documented default does not fit. Host-native commands remain the primary interface; these settings tune a feature or arm an explicitly opt-in surface.

Set a variable in the environment that launches your host, then start a fresh session. On PowerShell, use $env:NAME = "value" for the current process. On POSIX shells, use export NAME=value. Persist values with your operating system or shell profile only after a temporary session behaves as expected.

Do not commit secrets or machine-specific paths. Unknown values generally fall back or fail soft, but safety-sensitive settings can refuse a run. The tables below cover supported operator-facing settings; test seams and internal state-path overrides are intentionally excluded.

This catalog is typed and deterministic, but its defaults and explanations are maintainer-reviewed rather than extracted from executable code. A contract test requires every documented variable name to exist in shipped implementation code; follow the linked feature guide and current source when a default is release-critical.

Core and safety

Variable	Default	Accepted values	Effect
`CODEARBITER_DEV`	off	`1` to arm	Allows the logged maintainer dev-mode command to suspend orchestration. This does nothing until the dev command is invoked; every entry and exit is audited.
`NO_COLOR`	unset	any present value	Removes ANSI color from terminal output while preserving content and layout.
`CODEARBITER_BASE_BRANCH`	`main`	local branch name	Sets the branch used as the SessionStart comparison base when the repository uses a different default. This changes startup reporting only; it does not retarget a pull request or authorize a merge.

Statusline

Variable	Default	Accepted values	Effect
`CODEARBITER_THEME`	`violet`	`violet`, `blue`, `green`, `amber`, `mono`, or `custom`	Selects the Claude Code statusline palette.
`CODEARBITER_THEME_FILE`	`~/.codearbiter/statusline-theme.json`	local JSON file path	Overrides the custom-theme file used when `CODEARBITER_THEME=custom`.
`CODEARBITER_STATUSLINE`	on	`off` disables	Disables the Claude Code statusline without uninstalling its settings entry.
`CODEARBITER_WIDTH`	terminal width	integer, clamped to 70–160	Overrides the rendered statusline width; otherwise `COLUMNS` and terminal probes apply.
`CODEARBITER_COMPACT`	off	`1`, `true`, `on`, or `yes`	Uses the lean statusline layout and drops subagent rows.
`CODEARBITER_COMPACT_AT`	`92`	context percentage	Sets the context-usage threshold presented as compaction pressure.

PR watch

Variable	Default	Accepted values	Effect
`CODEARBITER_BABYSIT`	`off`	`on`, `true`, or `1`	Auto-attaches the server-side PR watcher after the PR command opens a pull request. It applies only in opted-in repositories and never enables itself or auto-merges.
`CODEARBITER_BABYSIT_ONRED`	`propose`	`propose` or `branch`	Chooses whether a red watcher only diagnoses and proposes, or also creates an unmergeable spike branch. Unknown values fail closed to `propose`; the `branch` result can never be merged or opened as a PR.

Transcript pruning

Variable	Default	Accepted values	Effect
`CODEARBITER_PRUNE`	`off`	`off`, `dry`, or `on`	Controls the preview transcript-pruning service; `dry` records candidates without pruning. Enable it yourself only after reviewing dry-run output; codeArbiter never opts you in.
`CODEARBITER_PRUNE_TIER`	`gentle`	documented pruning tier	Selects the pruning strategy preset.
`CODEARBITER_PRUNE_STRATEGIES`	tier defaults	comma-separated strategy names	Overrides the strategy set selected by the pruning tier.
`CODEARBITER_PRUNE_KEEP_RECENT`	`10`	non-negative integer	Keeps this many recent eligible items untouched.
`CODEARBITER_PRUNE_MAXBYTES`	`8192`	positive byte count	Caps replacement sidecar content retained for one pruned item.
`CODEARBITER_PRUNE_MIN_SIZE`	`1048576`	positive byte count	Requires this transcript size before the service considers pruning.
`CODEARBITER_PRUNE_MIN_GROWTH`	`262144`	positive byte count	Requires this much growth since the previous pass before reconsidering the transcript.
`CODEARBITER_PRUNE_BACKUPS`	`3`	non-negative integer	Retains this many rotating transcript backups before older backups are removed.
`CODEARBITER_PRUNE_LIVE_SECS`	`90`	non-negative seconds	Treats a transcript as live for this long after its latest update and avoids compacting it.
`CODEARBITER_PRUNE_METRICS`	`~/.codearbiter/metrics/prune-dry.jsonl`	local JSONL file path	Overrides the append-only destination for dry-run pruning measurements.
`CODEARBITER_PRUNE_NUDGE`	`off`	`on` to arm	Enables the preview cold-miss nudge when pruning is also on.
`CODEARBITER_PRUNE_NUDGE_IDLE_SECS`	`240`	positive seconds	Sets the minimum idle period before a cold-miss nudge can appear.
`CODEARBITER_PRUNE_NUDGE_MIN_TOKENS`	`80000`	positive estimated token count	Sets the minimum model-context size before a cold-miss nudge can appear.

Farm backend

Variable	Default	Accepted values	Effect
`FARM_API_KEY`	required for `--farm`	provider API key	Authenticates the preview OpenAI-compatible farm backend. Keep it in the shell environment or the documented local tools `.env`; never commit it.
`FARM_API_BASE_URL`	`https://opencode.ai/zen/v1`	HTTPS OpenAI-compatible endpoint	Selects the farm provider endpoint.
`FARM_MODEL`	automatic selection	provider model id	Skips canary and cached model selection and pins one model.
`FARM_CANDIDATE_MODELS`	unset	comma-separated provider model ids	Supplies the model set for a canary comparison.
`FARM_CONCURRENCY`	`4`	integer of at least 1	Caps total in-flight worker calls, including best-of-N samples.
`FARM_BASE_BRANCH`	`main`	local branch name	Sets the branch from which the farm integration branch is created.
`FARM_INTEGRATION_BRANCH`	`farm/integration`	new or existing local branch name	Names the farm’s integration branch. Concurrent farm runs need distinct integration branches.
`FARM_SAMPLES`	`1`	integer of at least 1	Draws this many isolated candidates per task attempt; the first gate-passing candidate wins. Values above 1 can multiply provider token use even though concurrency remains capped.
`FARM_TEMPERATURE`	`0`	provider-supported number	Controls worker sampling; when samples exceed 1 and this is unset, the dispatcher uses 0.7.
`FARM_MAX_TOKENS`	provider default	non-negative integer	Caps completion tokens per worker call; `0` leaves the provider default.
`FARM_MAX_RETRIES`	`2`	non-negative integer	Limits gate retries for one task before escalation.
`FARM_REQUEST_TIMEOUT_MS`	`120000`	positive milliseconds	Bounds one provider request, including its response body.
`FARM_API_MAX_RETRIES`	`3`	non-negative integer	Limits transport retries for rate limits and server errors; provider `Retry-After` is honored.
`FARM_ENTITLEMENT_PROBE_TIMEOUT_MS`	`35000`	positive milliseconds	Bounds each model-entitlement probe during canary selection.
`FARM_GATE_TIMEOUT_MS`	`300000`	milliseconds of at least 1000	Bounds each non-git setup, gate, and mutation child command.
`FARM_ABORT_ESCALATION_RATE`	`0.5`	number from 0 to 1	Trips the dispatch circuit breaker when the settled-task escalation rate exceeds this fraction.
`FARM_ABORT_MIN_TASKS`	`3`	positive integer	Requires this many settled tasks before the escalation-rate circuit breaker can abort a run.
`FARM_ENRICH_MAX_BYTES`	`131072`	positive byte count	Caps test and in-scope source context injected into a worker prompt.
`FARM_WORKTREE_ROOT`	`.farm/worktrees`	repository-contained directory	Sets the scratch worktree root used by farm tasks and samples. An external root is refused unless `FARM_ALLOW_EXTERNAL_WORKTREE_ROOT=1` is set explicitly.
`FARM_ALLOW_EXTERNAL_WORKTREE_ROOT`	off	`1` to arm	Allows `FARM_WORKTREE_ROOT` to resolve outside the repository. This is a destructive-scope override: farm cleanup recursively removes task worktrees under that root.
`FARM_REPORT_DIR`	`.farm`	directory path	Sets the root for run-scoped farm receipts and reports.
`FARM_RUN_ID`	fresh random id	1–64 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, or `-`	Pins the run receipt directory name for reproducibility. Reusing an id publishes over that run’s existing receipt directory; use a fresh id per run.
`FARM_MUTATION`	`on`	`off` disables	Disables the farm mutation guard for a run.
`FARM_MUTATION_SAMPLE`	`15`	positive integer	Caps the number of built-in mutation candidates evaluated per task.
`FARM_MUTATION_BUDGET_MS`	`30000`	non-negative milliseconds	Time-boxes mutation testing for one task.
`FARM_MUTATION_WARN_BELOW`	`0.5`	number from 0 to 1	Attaches a review warning when the mutation score falls below this value.
`FARM_MUTATION_ESCALATE_BELOW`	`0.1`	number from 0 to 1	Hard-escalates a sufficiently sampled task at or below this mutation score.
`FARM_MUTATION_CMD`	built-in text mutator	local executable command	Replaces the built-in mutator with a language-specific mutation framework. The command runs inside the task worktree; verify it independently before trusting its score.

Verify and undo

After changing a statusline setting, run the statusline status command and trigger a new render. After changing pruning, run the prune status command and begin with dry. Farm settings are recorded in the run report; inspect that receipt before trusting the result.

To undo a setting, remove it from the launch environment and start a fresh host session. Removing FARM_API_KEY makes --farm stop at preflight; it does not affect the premium path.