Skip to content
Docs menu

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.

View .md

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 new

Or /gear new in the TUI. Three questions, answered with the arrow keys:

  1. Budget per task: low (about $0.05), medium ($0.25), high ($1), or a dollar amount.
  2. Quality: good enough (quick edits), strong (everyday features) or the best (hard bugs, design).
  3. 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+F5

The 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 review

That 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 eco when 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 (eco to normal to power), once per session.
  • Offline. When a cloud upstream stops answering, venom moves the session to local and offers /offline back when 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.