Smart Mode: Roles & Routing

The three model roles, auto-fill, which model each turn gets, and how reasoning effort scales.

view .md
for v0.9.62 · unchanged since v0.9.55
on this page
  1. Assigning models
  2. Which model the main turn gets
  3. Complexity-scaled effort
  4. Where each role is used

This page explains how Smart Mode picks a model and a reasoning effort for each piece of work. Most people come here to pin a model to a role, or to understand why a turn got the effort it did. For the overview, see Smart Mode.

Assigning models

  1. Open Ctrl+S.
  2. The Strategic, Implementation and Utility rows each show the model that would run now, tagged · pinned (you chose it) or · auto (Smart Mode filled it).
  3. Press Enter on a role row to open the model picker and pin a model.
  4. Press x on a pinned role to reset it to auto.
Role Answers Runs
Strategic What should we build? Architecture, API design, hard bugs, review, planning Complex main turns, reviewer subagents
Implementation Build what was decided. Write and edit code, fix compiles, write tests Standard main turns, coder / tester / general subagents
Utility Gather info, do mechanical work. Search, read, summarise, commit messages, compaction Trivial and Simple main turns, explorer subagents, internal engine calls

Zero-config auto-fill

Leave a role empty and Smart Mode fills it from your provider's live model list:

  • Strategic: your current model, at your effort.
  • Implementation: the strongest mid-tier model, one effort step down.
  • Utility: the cheapest capable model, with reasoning effort off.

On a single-model or Opus-only account there is nothing cheaper, so every role stays on your model.

Which model the main turn gets

Each turn is rated into a tier (see below), and the tier picks the role:

Tier Role
Trivial, Simple Utility
Standard Implementation
Complex Strategic

Two rows in Ctrl+S control this:

  • Route the main turn (default on). Off means every main turn runs on Strategic.
  • Cheapest main-turn role (default utility). Set it to implementation to keep simple turns off the cheapest model, or strategic to never route down.

If you start agentty with an explicit --model, that model is honoured.

Complexity-scaled effort

Effort has to be chosen before the request is sent, so Smart Mode rates each turn up front. This costs no extra model call and no latency. There are four tiers:

Tier Looks like Effort
Trivial "yes", "commit it", "run it" none
Simple a short, single-clause fix one step down from your baseline
Standard the everyday working turn your baseline (unchanged)
Complex "why does this deadlock?", "refactor the auth module", a long or multi-part ask one step up (or two when the turn is deeply complex)

You don't set the tier; it comes from your prompt. Ask a design or "why" question, or list a multi-step task, and the turn gets more room to think.

Your baseline, and why it defaults to auto

The table above is relative to a baseline: the effort setting on your model, which you change with ← / → in the model picker. Tiers move up or down from it, so the baseline needs room in both directions.

auto (the default) means the middle rung of whatever effort levels your current model has:

Your model's ladder auto means trivial simple standard complex
minimal · low · medium · high low off minimal low medium
low · medium · high · max medium off low medium high
on/off only high off off high high
no reasoning control — off off off off

Trivial turns never get a reasoning budget, at any baseline.

To fix the level yourself, pick any rung and it stays there. off is a real choice: agentty then sends no reasoning parameter on any turn, including complex ones.

How the classifier works

The rating is a small added-up score, not a keyword lookup. Three kinds of signal add weight, and the total is cut into tiers:

  • Structure (most of the weight, works in any language): numbered asks, clause and conjunction count, how much code is in the prompt, question shape, length.
  • Words: weighted design, debug and architecture keywords in the major languages. They add capped evidence; one stray "design" in "add a design token" does not force the top tier.
  • Token shape: the mix of prose, identifiers and paths.

Because it's a score, Smart Mode knows how far into a tier a turn sits. A turn barely past Complex gets one step up; a turn deep into Complex gets two.

Other rules:

  • Ambiguity rounds up. Standard is the fallback. Under-thinking a hard turn costs more than a little extra budget on an easy one.
  • Context counts. A short follow-up to a hard turn ("now do the same for the other module") inherits weight from the turn it continues. A plain "thanks" is taken at face value. An attached payload can also lift the tier.
  • Effort stays in range. A model with no reasoning control gets none.

To make the router more or less eager to escalate, tune AGENTTY_SMART_COMPLEX_THRESHOLD and AGENTTY_SMART_DEEP_MARGIN, or the matching advanced rows in Ctrl+S (Ctrl+E).

The cascade correction

The up-front rating is a first guess. After each turn, agentty looks at what actually happened and adjusts an effort bias for the rest of the session:

  • A Simple or Standard turn that started two or more task workers was really harder. The bias goes up.
  • A failed shell, test, diagnostics or edit call is a sign the route was too weak.
  • A Complex turn that delegated nothing and answered directly was easier. The bias goes down.
  • A message that corrects the last turn ("no", "that's wrong", "actually…", "undo", "revert") pushes the bias up.

The bias moves back toward neutral each turn, so one odd turn doesn't stick. It is capped by AGENTTY_SMART_BIAS_CLAMP (the Self-correction cap row). The bias is session-only: it resets on a new thread and on exit, and is never saved. The routing card shows it as session +N.

Where each role is used

  • Main turn: by tier, as above.
  • Subagents (task): explorer → Utility, reviewer → Strategic, coder / tester / general → Implementation.
  • Internal engine calls (the auto-compaction summary): Utility.

All of these go through one resolver that maps role → (model, effort). It never checks a model name such as if (model == "opus"), which is why Smart Mode works with any provider and why turning it off changes nothing: with the switch off, every role is your single active model.