Your first gear
Switch between cheap, normal, strong and local models in one keystroke with gears, build a gear for your budget with the gear wizard, and make it the default.
A gear is a preset: the main model, its thinking level, the models subagents and summaries use, the vision model and the orchestrator route profile, switched together. Shifting gears is how you trade cost for strength in the middle of a task, the way you shift a car.
Shift gears
In the TUI, press the leader key ctrl+g, let go, then a number:
ctrl+g 1 eco (cheapest)
ctrl+g 2 normal
ctrl+g 3 power (strongest)
ctrl+g 4 local (Ollama only, fully offline)
ctrl+g g pick from a list
ctrl+g + one gear up ctrl+g - one gear down/gear lists the gears, marks the engaged one and says why any are unavailable; /gear power, /gear 3, /gear up and /gear down shift. Where your terminal sends them, alt+1 to alt+9, alt+. (up) and alt+, (down) and shift+F1 to shift+F12 work without the leader. The status bar shows the engaged gear.
The built-in gears
| Key | Gear | Main model (first one the endpoint serves) | Thinking | For |
|---|---|---|---|---|
| 1 | eco |
venom-fast, openai/gpt-5.4-nano, qwen-fast, glm-fast |
off | Reading, small edits, long cheap runs |
| 2 | normal |
venom-default |
medium | Everyday work |
| 3 | power |
openai/gpt-5.5, venom-smart, qwen, glm |
high | Hard bugs, design, large refactors |
| 4 | local |
ollama/qwen3:8b, then any ollama/ model |
off | Offline; nothing leaves the machine |
| 5 | delegate |
openai/gpt-5.5, venom-smart, venom-default |
medium | A strong main model that hands work to cheap subagents eagerly |
| 6 | open |
glm, kimi, deepseek, qwen |
medium | Open-weight models on Model Studio or Z.ai |
| 7 | qwen |
qwen |
medium | Qwen first for every role |
| 8 | china |
glm, kimi, deepseek, qwen |
medium | Chinese-developed models only, enforced by the orchestrator |
| 9 | auto |
venom-auto |
medium | Venom Cloud picks the model per request |
A gear whose models the endpoint doesn't serve, or whose route profile the orchestrator doesn't have, is unavailable: /gear shows it with the reason and shifting up or down skips it. Checking needs no request: venom uses the model list it fetched at start.
When you engage a gear, venom asks the endpoint to load that gear's models (POST /v1/prewarm), so the first turn on a local model doesn't wait for it to load.
Build a gear with the wizard
venom gear newOr /gear new in the TUI. Three questions, answered with the arrow keys:
- Budget per task: low (about $0.05), medium ($0.25), high ($1), or a dollar amount.
- Quality: good enough (quick edits), strong (everyday features) or the best (hard bugs, design).
- Privacy: local only, no US providers, or anything the endpoint serves.
The wizard reads the endpoint's model list (and its prices, when VENOM_ADMIN_TOKEN lets it read them; otherwise the bundled list prices, with local models free), picks a model for each role and shows the plan with an estimated cost per task:
Gear strong-gear: strong quality, any provider, budget $0.25 a task, thinking medium
main → venom-default $0.08 (list price, US)
workers → qwen/qwen3.8-flash $0.0069 (list price, non-US)
smart → zai/glm-5.3 $0.03 (list price, non-US)
summary → qwen/qwen3.8-flash $0.0032 (list price, non-US)
est. $0.11 a task (a typical task's tokens at these prices; within budget)The estimate prices one typical task's tokens, so it is for comparing gears, not a quote. When the endpoint serves nothing that fits your answers, the wizard lists the providers you could add and the environment variable each needs. It then saves the gear to ~/.venom/config.yaml (every project) or the project's venom.yaml.
Every question has a flag, for scripts:
venom gear new --budget 0.30 --quality best --privacy no-us --name deep --save repo
venom gear new --privacy local --json # print the plan as JSON, save nothing| Flag | Values | Default |
|---|---|---|
--budget |
low, medium, high, or dollars per task |
asked; medium without a terminal |
--quality |
good, strong, best |
asked; strong without a terminal |
--privacy |
local, no-us, any |
asked; any without a terminal |
--name |
the gear's name | from the answers |
--save (or --home, --repo) |
home, repo, none |
asked; home without a terminal |
--publish |
publish to your organisation's gears on Venom Cloud (needs VENOM_CLOUD_ADMIN_KEY) |
off |
--yes, -y |
ask nothing: unanswered questions take their defaults | implied without a terminal |
--json |
print the plan as JSON and save nothing, unless --save is given too |
off |
Write a gear by hand
A gear is a few lines of YAML in ~/.venom/config.yaml or a project's venom.yaml:
gear: review # engaged at start
gears:
review:
extends: power # start from a built-in
model: venom-smart
thinking: high
key: 5 # ctrl+g 5, alt+5, shift+F5The same from the shell, without opening the file:
venom gear save review --extends power --model venom-smart --thinking high --key 5
venom gear list # every gear: key, name, model, profile, what it extends
venom gear show review # one gear, resolved through extends
venom gear rm review # remove it (on a built-in: disable it)/gear save <name> [key] in the TUI saves what is in effect now (model, thinking, profile) as a gear; /gear edit <name> and /gear rm <name> change or remove one. Gears in the Configuration section documents every gear key: per-role models (workers, smart, vision, browser, classifier, summary, reflex), service tiers, escalation and route profiles.
Make it the default
venom config set gear reviewThat sets gear: in ~/.venom/config.yaml; every session starts in it. Put gear: in a project's venom.yaml to start that project's sessions in another gear. With Venom Cloud, an organisation can also define gears for its members and name a default; your own gear: wins over the organisation's default.
Gears that shift on their own
- Budget. A session that reaches 80% of its budget steps down to
ecowhen the current run ends, once per session. - Stuck. When the agent edits a file back and forth or repeats the same failing call, venom shifts up one gear (
ecotonormaltopower), once per session. - Offline. When a cloud upstream stops answering, venom moves the session to
localand offers/offline backwhen the upstream answers again.
None of these touch a model you picked yourself with --model, and none switch back on their own: a switch breaks the prompt cache.
Related
- Local or cloud models: the endpoint the gears' models come from.
- Troubleshooting.