---
title: venom.yaml reference
description: Every key venom.yaml accepts, with its type, default, the environment variable that overrides it and whether a project file needs trust.
section: configuration
order: 10
audience: [user, operator, builder, agent]
sources: [docs/venom-config.schema.json, packages/harness/src/config/schema.ts, packages/harness/src/config/index.ts, cli/src/venom-config.ts, docs/configuration.md]
features: [configuration.venom-yaml]
---

The JSON Schema (`venom config schema`, also `docs/venom-config.schema.json` in the source tree) is the source of truth for this page. Every key is optional. An unknown key or a wrong type is dropped with a warning and the rest of the file loads. "Trust" marks keys a project file may set only once the project is trusted ([Project files and trust](/docs/configuration.md#trust)).

Start a file with the schema line so your editor checks it:

```yaml
# yaml-language-server: $schema=~/.venom/venom-config.schema.json
$schema: ~/.venom/venom-config.schema.json   # optional, for editors that read the key instead
```

## Models {#models}

| Key | Type | Default | Env var | Meaning |
|---|---|---|---|---|
| `model` | string | `venom-default` | `VENOM_MODEL` | the main model (id or alias) |
| `thinking` | map model → `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` | `venom-fast: off`, `venom-default: medium` | `VENOM_THINKING` (wins per model) | default reasoning effort per model id or alias |
| `tiers.fast` | string | `venom-fast` when served | `VENOM_FAST_MODEL` | the fast tier: the explorer, compaction summaries, agents with `model: fast` |
| `tiers.smart` | string | `venom-smart` when served | `VENOM_SMART_MODEL` | the smart tier: agents with `model: smart` |
| `agents.<name>.model` | string | the agent file's | | a model (id, alias or tier) for one agent: `agents: { explorer: { model: qwen-fast } }`. A `task` call's own `model` still wins |
| `vision_model` | string | `venom-vision` | `VENOM_VISION_MODEL` | describes images for a text-only main model |
| `decision_model` | string | `venom-decide` | `VENOM_DECISION_MODEL` | the decision model auto mode's decider and search re-ranking ask |
| `orchestrator.base_url` | URL with `/v1` | `http://localhost:8787/v1` | `VENOM_BASE_URL` | where models are served. Trust. The key stays in `VENOM_API_KEY` |
| `gear` | key (1–12) or name | none | | the gear engaged at startup |
| `gears` | map name or key → gear | the nine built-ins | | your gears and patches to the built-ins; see [Gears](/docs/configuration/gears.md) |

Details: [Models](/docs/configuration/models.md).

## Search and browser {#search}

| Key | Type | Default | Env var | Meaning |
|---|---|---|---|---|
| `search.url` | URL | none | `VENOM_SEARCH_URL` | your SearxNG, tried first by `web_search`. Trust |
| `search.brave_key_env` | variable name | `BRAVE_API_KEY` | | the variable holding the Brave Search key (never the key). Trust |
| `search.tavily_key_env` | variable name | `TAVILY_API_KEY` | | the variable holding the Tavily key. Trust |
| `search.orchestrator` | `on` \| `off` | `on` | `VENOM_SEARCH_ORCHESTRATOR` | `on`: ask the orchestrator's `/v1/search` first; `off`: only the direct backends, then DuckDuckGo |
| `search.rerank` | `on` \| `off` | `off` | `VENOM_SEARCH_RERANK` | re-rank results with the decision model |
| `browser` | `on` \| `off` \| `window` \| `headless` \| `extension` | `on` | | `on`: browser tools load lazily when a Chrome is installed; `off` = `--no-chrome`, `window` = `--chrome`, `headless` = `--chrome-headless`, `extension` = `--chrome-extension`. A flag wins |

## UI {#ui}

Full descriptions in [UI, themes and keys](/docs/configuration/ui-and-themes.md).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `ui.width` | 40+ \| `auto` \| `full` | `auto` (100 columns) | reading width; `VENOM_MAX_WIDTH` wins; `/width` saves here |
| `ui.verbosity` | `quiet` \| `normal` \| `full` | `quiet` | how much of each turn the transcript shows; `/verbose` saves here |
| `ui.meter` | `on` \| `off` \| `compact` \| `full` | `compact` | the call meter under each turn (`on` = `compact`); `/meter` saves here |
| `ui.agents_panel` | `on` \| `off` \| `auto` | `auto` | the agents panel; `/agents-panel` saves here |
| `ui.theme` | theme name \| `auto` | `auto` | colour theme; `/theme` saves here |
| `ui.theme_overrides` | map token → `#rrggbb` | none | single colours over the active theme |
| `ui.hud` | `auto` \| `compact` \| `full` \| `custom` | `auto` | the status bar layout; `/hud` saves here |
| `ui.hud_lines` | list of lists of segment ids | the full layout | the custom HUD's lines |
| `ui.hud_thresholds.warn`, `ui.hud_thresholds.crit` | percent | `50`, `80` | amber and red levels for the HUD's percentages |
| `ui.clock` | `full` \| `time` \| `date` \| `off` | `full` | the HUD's lower-right corner |
| `ui.clock_format` | `12h` \| `24h` | the locale's | clock hours |
| `ui.location` | string | the time zone's city | the place shown in the HUD, derived offline |
| `ui.pr_pane.side` | `right` \| `left` | `right` | where the pull requests pane opens |
| `ui.pr_pane.width` | columns \| `"45%"` | half the terminal, 44–120 | the pane's width |
| `ui.pr_pane.auto_refresh` | `true` \| `false` \| seconds | `true` (60 s) | refresh while the pane is open |
| `statusline` | list of widgets | none | one extra status line; UI only, never sent to the model |
| `keys.leader` | key | `ctrl+g` | the leader (prefix) key |
| `keys.leader_timeout_ms` | integer | `1500` | how long the leader waits for its key |
| `keys.leader_bindings` | map key → action | the defaults | what the key after the leader does; `null` removes one |
| `keys.gear_hotkeys` | boolean | `true` | shift+F1…F12, alt+1…9, alt+. and alt+, for gears |

## Context and memory {#context}

| Key | Type | Default | Meaning |
|---|---|---|---|
| `context.autocompact` | share 0.2–0.95 \| `off` | the model's `hard` threshold (`0.55` for an unknown model) | where automatic compaction starts, as a share of the window. `off`: only when the next request would not fit. `/compact` works either way |
| `context.quality.<model or prefix*>.soft` | share | per model family | past it, idle compaction runs |
| `context.quality.<model or prefix*>.hard` | share | per model family | past it, the compaction trigger fires (unless `context.autocompact` is set) |
| `context.idle_compact` | seconds \| `off` \| `{ after, headless }` | `180`, interactive only | compact in the background after this long idle when past the soft threshold. `context.idle_compact.after` is the seconds; `context.idle_compact.headless: true` also in `venom serve`, ACP and print mode |
| `memory.auto` | `on` \| `off` | `on` | load the project's `MEMORY.md` index into each session and give the model the `memory` tool and `/memory` |
| `memory.dir` | path | `~/.venom/projects/<slug>/memory` | where memory files go (absolute, `~/…`, or relative to the project root). Trust |
| `memory.max_index_lines` | integer | `200` | index lines loaded into the prompt (at most 12 KiB) |
| `memory.org_dir` | path | none | a shared directory of org-wide memory every machine reads. Trust |

`VENOM_CONTEXT_WINDOW` caps the context window venom assumes: the smaller of the server-reported window and this value, or this value when the server reports none (default 131072).

## Workspaces {#workspaces}

| Key | Type | Default | Meaning |
|---|---|---|---|
| `workspaces.default` | `off` \| `session` \| `subagents` \| `both` | `off` | when venom uses git worktrees without being asked: every interactive session, every writing subagent, or both |
| `workspaces.dir` | path | `.venom/worktrees` | where worktrees go, relative to the repository root. Trust |
| `workspaces.branch_prefix` | string | `venom/` | each workspace's branch is `<prefix><name>` |
| `workspaces.cleanup` | `auto` \| `keep` \| `ask` | `auto` | when a session in a workspace ends: remove it if nothing would be lost, always keep it, or ask |
| `workspaces.copy_ignored` | list of patterns | `[.env.example]` | gitignored files copied into a new workspace; a secret-named file only when a pattern names its exact path. Trust |
| `workspaces.create` | command or list | none | run with `sh -c` in each new workspace; `KEY=VALUE` lines it prints go into the agent's environment there. Trust |
| `workspaces.finish` | command or list | none | run just before venom removes a workspace. Trust |
| `workspaces.timeout_ms` | integer | `120000` | kill `create` and `finish` after this long |

## Permissions and guards {#permissions}

| Key | Type | Default | Meaning |
|---|---|---|---|
| `permissions.mode` | `plan` \| `default` \| `accept-edits` \| `auto` \| `yolo` | `default` | the starting permission mode. A project file needs trust past `default`; `--permission-mode`, `--yolo`, `--plan` win |
| `permissions.allow` | list of rules | none | allow rules (`bash(npm test:*)`, `edit(src/**)`), on top of `~/.venom/permissions.json`. Trust |
| `permissions.ask` | list of rules | none | ask rules |
| `permissions.deny` | list of rules | none | deny rules |
| `permissions.auto.timeout_ms` | integer | none (the classifier request's own 30 s) | give up on one auto-mode review after this long; `VENOM_AUTO_TIMEOUT_MS` wins |
| `permissions.auto.on_failure` | `ask` \| `deny` | `ask` | a failed or timed-out review hands the call to you (headless: denied) or denies it; `VENOM_AUTO_ON_FAILURE` wins |
| `guards.output_budget` | integer tokens | none | output tokens a run is meant to use (also `--output-budget`); a model that stops early is nudged to keep going, at most 3 times |
| `stuck.oscillations` | integer | `2` | times one file may go back to an earlier version before the session counts as stuck (`0`: off) |
| `stuck.repeated_failures` | integer | `3` | times the same call may fail the same way (`0`: off) |
| `stuck.escalate` | boolean | `true` | shift up one gear before asking you |
| `stuck.gear` | gear name | next of `eco` → `normal` → `power` | the gear to shift to |
| `session_guard.stall_calls` | integer | `12` | model calls in a row with no progress before the session pauses (`0`: off) |
| `session_guard.max_minutes` | integer | no limit | pause after this many minutes since your last message |
| `session_guard.max_usd` | number | no limit | pause after this much spend since your last message, at list price |
| `guardrails.catalog` | list of ids | none | built-in guardrails to switch on (`/guardrails catalog` lists them) |
| `guardrails.rules` | list of rules | none | your own guardrails (fields `code`, `name`, `kind`, `action`, `mode`, `enabled`, `match`, `direction`, `paths`, `repos`, `models`, `tools`, `limit`, `answer`, `description`). Trust |

`guardrails.rules[].kind` is one of `content`, `routing`, `models`, `tools`, `spend`, `answers`; `action` one of `block`, `deny`, `keep_local`, `downgrade`, `ask`, `redact`, `rewrite`, `warn`, `log`; `mode` `enforce` or `monitor`; `direction` `request`, `response` or `both`. The guardrail format itself is documented in [Guardrails](/docs/security/guardrails.md).

## Long tasks, reviews and cost {#tasks}

| Key | Type | Default | Meaning |
|---|---|---|---|
| `resume.checkpoints` | boolean | `true` | write a checkpoint to `~/.venom/tasks/` at each turn and plan step; `false` also turns off `venom resume` and the limit wait |
| `resume.on_limit` | `wait` \| `fail` | `wait` | a 429 naming a reset time parks the task until then, or ends the run |
| `resume.fallback_gear` | gear name | none | switch to this gear at once on a usage limit instead of waiting |
| `resume.max_wait_hours` | number | `12` | the longest a task waits on one limit |
| `resume.prompt` | boolean | `true` | on a terminal, ask at start whether to resume an interrupted task here |
| `plan_execute.approve` | `ask` \| `auto` | `ask` | show a plan-then-execute plan and wait for Run / Edit / Cancel, or run it as written (headless always runs it) |
| `review.before_pr` | boolean | `true` | review the branch's diff before the agent runs `gh pr create`; `--no-self-review` skips one run. Trust |
| `review.model` | model | the gear's smart tier | the self-review's model, also `venom review`'s default. Trust |
| `review.gear` | gear name | none | the gear `venom review` runs on without `--model` or `--gear` |
| `review.rounds` | integer | `1` | times a pull request may be held back for fixes (`0`: no review) |
| `review.max_usd` | number | `2` | stop one self-review at this cost. Trust |
| `tasks.lookup` | `git` \| `gh` | `git` | how a session's task is found: the branch offline, or also `gh pr view`. Trust |
| `tasks.pr_footer` | `off` \| `body` \| `comment` | `off` | write the task's spend into the pull request venom opened. Trust |
| `tool_billing.<tool>` | billing entry | none (tools are free) | what a non-built-in tool costs; see [Tool billing](/docs/configuration/models.md#tool-billing) |
| `tests.on_edit`, `tests.max_seconds`, `tests.flaky_after` | see [Tests](/docs/configuration/models.md#tests) | `auto`, `60`, `3` | tests after edits and the flaky-test detector |
| `learn` | boolean | `true` | draft a template or skill after the same kind of job three times ([Learned skills](/docs/configuration/models.md#learn)) |
| `finetune.enabled` | boolean | `false` | let `venom finetune export` and `venom export-traces` read your saved sessions |
| `finetune.since` | date | none | sessions last modified before it are never read |
| `finetune.trainer` | `unsloth` \| `axolotl` \| `llama-finetune` | auto (first on PATH) | the local trainer `venom finetune train` runs |
| `finetune.base_model` | path | none | the local base model the trainer starts from |
| `offline.auto`, `offline.gear` | boolean, gear name | `true`, `local` | switch to a local gear when the network drops ([Offline mode](/docs/configuration/models.md#offline)) |

## venom serve, inbox and schedules {#serve}

| Key | Type | Default | Meaning |
|---|---|---|---|
| `serve.public_url` | URL | none | the address phones and teammates reach this machine's `venom serve` at; `VENOM_SERVE_PUBLIC_URL` overrides. Trust |
| `inbox.attention.minutes_per_day` | number | no cap | minutes of your attention agents may use per local day; low-value items over it are held. Trust |
| `inbox.attention.threshold` | number | `0` | lowest rank that reaches you. Trust |
| `schedules.<job>` | job | none | a background agent `venom serve` runs on a cron or on events. Trust |

A job takes `schedules.<job>.cron` (five fields, local time, or `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`), `on` (events that also start it), `role` (`dependency-bumper`, `flaky-hunter`, `dead-code`, `docs-drift`, or a plugin's), `prompt`, `cwd` (inside a `venom serve --root`), `workspace` (default `true`), `gear`, `model`, `mode` (default `default`, every question answered no), `max_usd` (default 1), `max_minutes` (default 120, `0`: no limit), `enabled`, `allow` (rules the run may use without asking), and for recorded browser scripts `browser_task`, `params`, `browser` (`headless`, `launch`, `extension`, `attach`) and `attach_port`. `venom schedule add|list|rm|run` manages them; the [automation section](/docs/automation.md) documents schedules in full.

## MCP, library and plugins {#plugins}

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mcp.enabled` | list of names | none | approved MCP servers you turned on (home file only; `venom mcp enable` writes it) |
| `mcp.disabled` | list of names | none | approved servers you turned off; lists from every file add up |
| `library.hidden` | list of names | none | team library items you don't want: a name, `org:<name>`, `skill:<name>`. Required items still load |
| `plugins.sources` | list of `path:` / `npm:` / `git:` sources | none | plugins to load; `venom plugin add` writes it. Trust |
| `plugins.<name>.enabled` | boolean | `true` | `false` lists the plugin without loading it |
| `plugins.<name>.config` | map | the plugin's defaults | the plugin's settings, checked against its manifest by `venom config validate` |

## Hooks, sounds and voice {#hooks}

| Key | Type | Default | Meaning |
|---|---|---|---|
| `hooks` | list | none | commands or sounds on venom events. Every file's list runs, home first; a project file's commands only while the project is trusted |
| `hooks[].event` | `MainAgentDone` \| `SubagentDone` \| `StepDone` \| `PermissionNeeded` \| `AgentFailed` \| `ScheduleDone` | required | the event |
| `hooks[].matcher` | regex | all | anchored, over the agent name or role, or the tool name for `StepDone` and `PermissionNeeded` |
| `hooks[].command` | shell command | none | gets the event's JSON payload on stdin |
| `hooks[].sound` | name or absolute path | none | a sound played instead of, or as well as, the command |
| `hooks[].timeout` | seconds | `30` | kill the command after this long |
| `hooks[].async` | boolean | `true` | don't wait for the command; events never block the agent either way |
| `sounds.enabled` | boolean | `true` | play event sounds at all |
| `sounds.volume` | 0–1 | `0.6` | volume |
| `sounds.only_when_unfocused` | boolean | `true` | only while the terminal is in the background (a terminal that reports no focus plays) |
| `sounds.quiet_hours` | `"HH:MM-HH:MM"` | none | no sounds in this local window (wraps midnight) |
| `sounds.min_turn_seconds` | seconds | `5` | no done sound for shorter runs |
| `sounds.events.main_agent_done` | sound \| path \| `off` | `chime` | |
| `sounds.events.subagent_done` | sound \| path \| `off` | `tick` | |
| `sounds.events.step_done` | sound \| path \| `off` | `off` | |
| `sounds.events.permission_needed` | sound \| path \| `off` | `attention` | |
| `sounds.events.agent_failed` | sound \| path \| `off` | `failure` | |
| `sounds.events.schedule_done` | sound \| path \| `off` | `done` | |
| `voice.model` | path | `~/.venom/models/ggml-base.en.bin` | the whisper.cpp model for voice input (`ctrl+g r`, `/voice`) |
| `voice.language` | code | `en` | whisper's language; `auto` detects it |

Built-in sounds: `chime`, `done`, `tick`, `pop`, `bell`, `hiss`, `success`, `failure`, `attention`, `marimba`. `VENOM_SOUND_PLAYER` sets your own player command. Claude Code-style hooks stay in `.claude/settings.json`; the automation and plugins sections cover hook payloads and Claude Code hooks.

## A full example {#full-example}

```yaml
# <repo>/venom.yaml: what the project needs; each person's ~/.venom/config.yaml adds taste
model: venom-default
tiers: { fast: venom-fast, smart: venom-smart }
thinking: { venom-default: medium, venom-fast: off }
gear: normal
gears:
  review:
    key: 10
    extends: power
    mode: plan
permissions:
  mode: default
  deny: ["bash(git push:*)"]
tests: { on_edit: auto, max_seconds: 90 }
workspaces: { default: subagents }
context:
  quality:
    "ollama/*": { hard: 0.45 }
```

## Related

- [Configuration](/docs/configuration.md): files, precedence, trust and `venom config`.
- [Environment variables](/docs/configuration/env-vars.md).
