---
title: Your first gear
description: 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.
section: getting-started
order: 50
audience: [user]
sources: [cli/src/gear-wizard.ts, cli/src/gear-new.ts, cli/src/gear-command.ts, cli/src/gears.ts, docs/configuration.md]
features: []
---

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

In the TUI, press the leader key `ctrl+g`, let go, then a number:

```text
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 {#builtin}

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

```bash
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:

```text
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:

```bash
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 {#yaml}

A gear is a few lines of YAML in `~/.venom/config.yaml` or a project's `venom.yaml`:

```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:

```bash
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](/docs/configuration/gears.md) documents every gear key: per-role models (`workers`, `smart`, `vision`, `browser`, `classifier`, `summary`, `reflex`), service tiers, escalation and route profiles.

## Make it the default {#default}

```bash
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 {#automatic}

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

## Related

- [Local or cloud models](/docs/getting-started/local-or-cloud.md): the endpoint the gears' models come from.
- [Troubleshooting](/docs/getting-started/troubleshooting.md).
