Skip to content
Docs menu

Gears

Switch the main model, thinking level, delegation models and route profile in one keystroke, use the built-in gears, and define your own.

View .md

A gear is a named preset of the main model, its thinking level, the delegation models (workers and the smart tier), per-role models, the vision and decision models, the search scope and the orchestrator route profile. Shifting gears changes all of them at once, from the next model request.

Shift gears

venom gear list            # every gear, its models, and whether the orchestrator serves them

In the TUI:

Input Does
/gear list the gears: the engaged one marked, unavailable ones with the reason
/gear power, /gear 3 shift to a gear by name, unique prefix or key
/gear up, /gear down shift up or down, skipping unavailable gears
ctrl+g 1 … ctrl+g 9 the leader, then a key: shift to the gear on that key
ctrl+g up, ctrl+g +, ctrl+g = shift up
ctrl+g down, ctrl+g - shift down
ctrl+g g pick a gear from a list
alt+<n> (alt+1 … alt+9) shift to gear n
alt+., alt+, shift up, shift down
shift+F1 … shift+F12 shift to gear 1 … 12

ctrl+g is the default leader key (Keys). The alt and shift+F shortcuts depend on the terminal (on macOS, alt needs the Option key set to send Meta or Esc+); keys.gear_hotkeys: false turns them off. The leader works in every terminal and inside tmux.

To start in a gear, set gear: to a key or name:

gear: normal

Unset, no gear is engaged until you shift. With --model or VENOM_MODEL and gear: both set, the gear's tiers, thinking level and profile apply and the model you chose stays.

Built-in gears

Each model is a list of candidates: the first one the orchestrator lists in /v1/models is used, and an entry ending in * matches by prefix.

Key Gear Main model candidates Thinking Fast tier (workers) Smart tier Also Delegation
1 eco venom-fast, openai/gpt-5.4-nano, qwen-fast, glm-fast off venom-fast, openai/gpt-5.4-nano, qwen-fast venom-default, venom-fast normal
2 normal venom-default medium venom-fast venom-smart normal
3 power openai/gpt-5.5, venom-smart, qwen, glm high venom-fast same as main normal
4 local ollama/qwen3:8b, ollama/qwen3*, ollama/* off ollama/qwen3:4b, ollama/qwen3*, ollama/* ollama/qwen3:8b, ollama/* fully offline normal
5 delegate openai/gpt-5.5, venom-smart, venom-default medium qwen-fast, glm-fast, venom-fast venom-smart, qwen, glm eager
6 open glm, kimi, deepseek, qwen medium qwen-fast, glm-fast, venom-fast qwen, deepseek, glm open-weight models normal
7 qwen qwen, qwen/qwen3.8-max medium qwen-fast, qwen/qwen3.8-flash, venom-fast qwen, qwen/qwen3.8-max vision qwen-vision; profile qwen-first normal
8 china glm, kimi, deepseek, qwen medium qwen-fast, glm-fast qwen, deepseek, glm vision qwen-vision, glm-vision; profile china; search self-hosted normal
9 auto venom-auto medium venom-auto, venom-fast venom-auto, venom-smart Venom Cloud picks a model per request normal

A gear is unavailable when none of its main model candidates is served, or when the orchestrator does not have its route profile. /gear lists it with the reason and shifting skips it. Tiers whose candidates are not served fall back to venom-fast and venom-smart.

  • qwen sends route profile qwen-first, so the orchestrator also puts Qwen first behind the venom-* aliases venom uses for side calls (summaries, the classifier).
  • china sends route profile china, which re-targets every venom-* alias to Qwen, GLM, Kimi and DeepSeek and refuses any other target. web_search uses only your SearxNG, and auto mode's decider falls back to the LLM classifier because venom-decide is not served there.
  • auto is only venom-auto, so it is unavailable on servers that don't list it (a self-hosted orchestrator, plain Ollama).

Your own gears

gears: maps a gear's name (or a key, 1–12) to its settings. Your entries patch the built-ins field by field; new names add gears; null removes one.

gear: review
gears:
  review:                       # a new gear on key 10
    key: 10
    description: careful review, read-only
    model: venom-smart
    thinking: high
    delegate: off
    mode: plan
    ui: { label: REVIEW, badge: syntaxVariable }
  my-qwen:                      # inherit a gear and change two fields
    extends: qwen
    thinking: high
    agents: { verifier: glm-fast }
  power:                        # patch one field of a built-in
    thinking: xhigh
  local: null                   # remove a built-in
  8: { thinking: high }         # by key: patch the gear on key 8
Key Type Meaning
gears.*.name string for a numbered entry (9: { name: review }): the gear's name. A numbered entry without a new name patches the gear on that key
gears.*.key 1–12 binds the gear to shift+Fkey, alt+<n> (1–9) and the leader + key. A key another gear held moves to this one. Never inherited
gears.*.extends gear name start from another gear (built-in or yours): maps merge, lists replace, null unsets. Cycles and unknown parents are reported and ignored
gears.*.description string one line shown by /gear and venom gear list
gears.*.model model or list the main model
gears.*.thinking off … xhigh the main model's thinking level, sent as reasoning_effort
gears.*.service_tier auto | default | flex | priority | batch the provider service tier main turns ask for (Service tiers)
gears.*.fast model or list the fast tier (same as workers, which wins)
gears.*.smart model or list the smart tier (same as roles.smart, which wins)
gears.*.workers model, list or role object the workers: the explorer and agents with model: fast
gears.*.roles map role → model or role object per-role models (Roles)
gears.*.agents map agent name → model per-agent models while engaged
gears.*.vision_model model or list describes images for a text-only main model
gears.*.decision_model model or list the model auto mode's decider asks (venom-decide by default)
gears.*.search default | self-hosted self-hosted: web_search uses only your SearxNG, never Brave, Tavily or DuckDuckGo
gears.*.profile string the orchestrator route profile sent as x-venom-profile on every request of the session
gears.*.mode plan | default | plan-execute tightens the permission mode while engaged (a gear never loosens it), or plans every task first and runs it step by step on workers
gears.*.delegate eager | normal | off eager: a one-line reminder to hand searches and test runs to subagents; off: the task tool is refused while engaged
gears.*.escalation { max, to } | false re-run a failing fast-tier subagent on a stronger tier; default { max: 1, to: smart }
gears.*.escalation.max 0–10 re-runs per session
gears.*.escalation.to smart | main | model id where the re-run goes
gears.*.ui.badge theme token the HUD badge's colour (accent, success, warning, error, syntaxVariable, …)
gears.*.ui.label string the badge's text instead of G<key> <name>

Names are lowercase letters, digits, ., _ and -, starting with a letter. up, down, pick, list, show, save, edit, rm, remove, new, next and prev are reserved. A gear from an untrusted project file applies as written: it cannot loosen anything, since mode only tightens and profile only chooses among your orchestrator's routes.

Roles

A gear can send each kind of work to a different model and route profile:

gears:
  team:
    model: glm
    profile: china
    workers: { model: qwen-fast, profile: cheap, thinking: low }
    roles:
      smart: qwen
      vision: qwen-vision
      browser: { model: [gpt-5.4-mini, venom-vision], profile: null }
      classifier: glm-fast
      summary: { model: qwen-fast, profile: cheap }
      reflex: qwen-fast
Role What runs on it Default
gears.*.roles.workers the fast tier: the explorer and subagents with model: fast workers, then fast
gears.*.roles.smart subagents with model: smart smart
gears.*.roles.vision descriptions of images for a text-only main model vision_model
gears.*.roles.browser descriptions of browser_screenshot shots for a text-only main model the vision role
gears.*.roles.classifier auto mode's classifier the fast tier
gears.*.roles.summary compaction summaries the fast tier
gears.*.roles.reflex routine browser steps through browser_autopilot none: no autopilot

Each role is a model reference or an object with four fields: gears.*.roles.<role>.model, gears.*.roles.<role>.profile (sent as x-venom-profile on that role's requests instead of the gear's; null means none), gears.*.roles.<role>.thinking (for workers and smart subagents) and gears.*.roles.<role>.service_tier. The same four fields apply to gears.*.workers (gears.*.workers.model, gears.*.workers.profile, gears.*.workers.thinking, gears.*.workers.service_tier). Each role request also carries x-venom-role: <role>, which Venom Cloud's venom-auto reads as a tier signal.

Service tiers

Tier Meaning
default the standard tier, asked for explicitly
flex about half price, slower; a 429 retries at once on the standard tier
priority faster, at a premium
auto the provider's choice
batch the provider's batch API at half price; answers can take minutes to hours. For unattended workers and summary only

The tier goes out as a header (x-venom-service-tier, or x-venom-urgency: batch), never in the request body, so the prompt cache is unaffected. A role never inherits the main row's tier. The orchestrator maps it to what each upstream accepts.

What a shift does

The main model switches at once when venom is idle, else at the next turn boundary; the running request is never aborted. Tiers, per-agent models and the route profile apply to subagents spawned after the shift. The system prompt never changes. The HUD shows the gear (G8 china, or the ui.label), and a one-line notice lists the new models.

Engaging a gear also asks the server to load its models (POST /v1/prewarm), so the first turn on a local model doesn't wait for it to load.

  • Budget step-down. At 80% of a session's budget, or when the orchestrator key passes a soft limit, venom steps down to eco once, at the end of an agent run. It skips this when eco is not served or not cheaper, when the current model is free, or when the gear names a route profile.
  • Stuck detection. A file edited back and forth, or the same call failing the same way, shifts up one gear once per session (eco → normal → power, or stuck.gear), then asks you (venom.yaml reference).
  • Auto-escalation. A fast-tier subagent whose own tests, lint or typecheck failed after it changed files, most of whose tool calls failed, or that a verifier rejected, runs once more on escalation.to.

venom gear

Command What it does
venom gear list every gear: key, name, model, profile, what it extends, (yours) for your gears
venom gear show <name> one gear resolved through extends, and the files that define it
venom gear save <name> [--home | --repo] [--extends g] [--model m] [--thinking t] [--fast m] [--smart m] [--profile p] [--key n] write a gear to ~/.venom/config.yaml, or with --repo to <repo root>/venom.yaml. Without settings, saves the directory's effective model, tiers and thinking
venom gear rm <name> [--home | --repo] remove your gear, or disable a built-in (gears.<name>: null)
venom gear new [--budget low|medium|high|<$>] [--quality good|strong|best] [--privacy local|no-us|any] [--name n] [--save home|repo|none] [--publish] [--yes] [--json] the gear wizard

In the TUI: /gear new, /gear save <name> [key] [--repo] (the settings in force now), /gear edit <name> (the entry in the editor, checked on save), /gear rm <name>, /gear show <name>, and /gear experiment [off|on] for Venom Cloud gear experiments. venom config validate checks gears too: cycles, bad names and keys, and models and profiles against the orchestrator.

The gear wizard

venom gear new asks three questions (arrow keys on a terminal; flags otherwise): budget per task (low about $0.05, medium $0.25, high $1, or an amount), quality (good, strong, best) and privacy (local only, no US providers, anything). It reads GET /v1/models and list prices (your own price overrides with VENOM_ADMIN_TOKEN), picks a model per role, prints a preview with an estimated cost per task, and saves gears.<name> with fallbacks. --json prints the plan without saving, including add_providers when the served models leave a gap. An org admin with VENOM_CLOUD_ADMIN_KEY can --publish the gear to the organisation's gears on Venom Cloud.

venom gear new --budget 0.30 --quality best --privacy no-us --name deep --save repo
venom gear new --privacy local --json

Gears from the server

When VENOM_BASE_URL points at a venom orchestrator or Venom Cloud, venom also reads GET <base_url>/gears along with /v1/models (same host, same key, cached with the model list). The answer is { "source": "Acme", "locked": false, "gears": [ … ] } in the same shape as gears:.

  1. Locked (locked: true): only the server's gears. Your config's gears are ignored with one notice, and /gear save, edit and rm refuse.
  2. Otherwise: the built-ins, patched by the server's gears, then by your files (home, then project). An organisation may name a default gear, used when your config sets no gear:.

/gear labels each gear with where it last changed: [built-in], [Acme] or [config].

With Venom Cloud, a gear's profile can be cloud, cloud-first, daemons or daemons-first to choose between provider keys and your own daemons per request. These are never counted as missing.

Troubleshooting

Symptom Cause and fix
A gear is listed as unavailable None of its main model candidates is in /v1/models, or its profile is missing. venom gear show <name> lists the candidates; add a served model to the list
alt+1 types ¡ on macOS Set the terminal's Option key to Meta or Esc+, or use the leader (ctrl+g 1)
/gear save: … sets the gears (locked) The server locks gears; ask your organisation's admin
403 profile_forbidden from Venom Cloud The organisation's routing forbids that profile for the model