Skip to content
Docs menu

venom.yaml reference

Every key venom.yaml accepts, with its type, default, the environment variable that overrides it and whether a project file needs trust.

View .md

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).

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

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

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

Details: Models.

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

Full descriptions in UI, themes and keys.

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

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

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

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.

Long tasks, reviews and cost

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
tests.on_edit, tests.max_seconds, tests.flaky_after see 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)
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)

venom serve, inbox and schedules

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 documents schedules in full.

MCP, library and 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

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

# <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 }