Gears
Switch the main model, thinking level, delegation models and route profile in one keystroke, use the built-in gears, and define your own.
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 themIn 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: normalUnset, 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.
qwensends route profileqwen-first, so the orchestrator also puts Qwen first behind thevenom-*aliases venom uses for side calls (summaries, the classifier).chinasends route profilechina, which re-targets everyvenom-*alias to Qwen, GLM, Kimi and DeepSeek and refuses any other target.web_searchuses only your SearxNG, and auto mode's decider falls back to the LLM classifier becausevenom-decideis not served there.autois onlyvenom-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
ecoonce, at the end of an agent run. It skips this whenecois 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, orstuck.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 --jsonGears 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:.
- Locked (
locked: true): only the server's gears. Your config's gears are ignored with one notice, and/gear save,editandrmrefuse. - 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 |
Related
- Models:
model, tiers and thinking outside gears. - venom.yaml reference.