---
title: Gears
description: Switch the main model, thinking level, delegation models and route profile in one keystroke, use the built-in gears, and define your own.
section: configuration
order: 20
audience: [user, operator, builder, agent]
sources: [packages/harness/src/config/gears.ts, cli/src/gears.ts, cli/src/gear-command.ts, cli/src/gear-new.ts, cli/src/keys.ts, docs/configuration.md]
features: [configuration.gear]
---

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

```bash
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](/docs/configuration/ui-and-themes.md#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:

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

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

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

```yaml
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+F*key*, `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](#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](#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 {#roles}

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

```yaml
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 {#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 {#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](/docs/configuration/venom-yaml.md#permissions)).
- **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 {#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 {#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.

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

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 |

## Related

- [Models](/docs/configuration/models.md): `model`, tiers and thinking outside gears.
- [venom.yaml reference](/docs/configuration/venom-yaml.md).
