Smart Mode: Reference

The complete reference for Smart Mode: the overlay, the persisted config, the on-disk learning stores, constraints, and why it's built the way it is.

The overlay (Ctrl+S)

Four rows. ↑/↓ move; Enter toggles the master switch or assigns a slot; x resets a slot to auto; Esc closes. The slots dim when Smart Mode is off.

That's the whole surface. Turning Smart Mode on enables all three of its behaviours together — internal routing (compaction and other engine calls run on the Utility model), orchestration (the main turn runs on Strategic with the delegation directive), and subagent routing (each task worker's model resolves by its role).

They aren't separate toggles because no one reasonably wants them apart: switching internal routing off just makes your compaction summaries more expensive for no benefit. A toggle earns a row only where a reasonable user would reasonably choose either way.

Commands

• Ctrl+K → Smart Mode (or Ctrl+S) — open the config overlay.

Persisted config

Every overlay choice is saved to your settings so the next session starts where you left off. The state lives under the smart_mode key in settings.json (~/.agentty/settings.json, or the platform equivalent).

Older settings files may still contain route_internal, orchestrate, route_subagents, learn_routing, outcome_feedback, speculative and recall_plans. Those keys are ignored — no migration is needed.

Nothing is stored per-workspace

Smart Mode keeps no on-disk state. Earlier versions persisted a learned routing prior (.agentty/routing_memory.tsv) and a log of successful task decompositions (.agentty/decompositions.jsonl); both were removed, along with the four self-supervised layers that fed them. They were never measured against the fixed policy, and a routing prior that quietly ratchets one week's cost into the next is not a feature you can verify.

The useful half of that signal is retained where it costs nothing: the session cascade still self-corrects from delegation behaviour, build failures and next-turn corrections — it decays each turn, is clamped by AGENTTY_SMART_BIAS_CLAMP, and dies with the process.

If you upgraded from an older build, the two files are still on disk and inert. Nothing reads them; delete them whenever you like.

Advanced tuning

The overlay picks your models. Three numeric policy knobs — for power users who want to retune the router's aggressiveness — are exposed as environment variables (read live, clamped to a safe range, unset = the shipped default). They're documented in full under Configuration › Smart Mode tuning:

Force the master switch for one session

AGENTTY_SMART_MODE=1 forces Smart Mode on for that process; =0 forces it off. 1/true/yes/on count as on, 0/false/no/off as off; unset means your saved setting governs, as before.

AGENTTY_SMART_MODE=1 agentty   # deterministic routing for a scripted run
AGENTTY_SMART_MODE=0 agentty   # force it off without touching your config

The pin is session-scoped and non-destructive: agentty never persists it, so a benchmark, CI run, or bisect can't overwrite the preference you use interactively. While a pin is active the ^S overlay's Enabled row shows on (env pin) / off (env pin), and toggling it in-app is a hinted no-op (unset the variable to toggle again). Ideal for reproducible experiments.

Individual classifier weights are deliberately not exposed. The tier threshold is the right control surface, not fifteen fiddly weights.

Developer escape hatches

Each folded-in behaviour keeps a negative env override, for bisecting a routing bug without editing settings:

AGENTTY_SMART_NO_INTERNAL=1     # compaction/titles stay on the main model
AGENTTY_SMART_NO_ORCHESTRATE=1  # main turn stays on the selected model
AGENTTY_SMART_NO_SUBAGENTS=1    # workers use the tier auto-router

These are deliberately env-only and deliberately negative: the default is on, and an escape hatch in the UI is just a toggle with extra steps.

Constraints

• Off is a strict no-op. With the master switch off, Smart Mode adds zero tokens, zero latency, and makes no routing decisions — the turn runs exactly as if the feature did not exist.
• Roles resolve to models, never model names to behavior. The resolver maps a role to (model, effort). It never inspects a model id string to decide what to do, so pinning any model to any slot is always safe.
• Effort never exceeds the turn's ceiling. Complexity-scaled effort and cascade correction only move within the bounds the active model allows; a Utility model is never asked for more effort than it supports.
• Learning is bounded and reversible. Priors decay toward the default, are keyed by a turn signature (a structural class plus a content hash) rather than exact text, and can be wiped at any time. A cold workspace behaves identically to one with the learning layers off.

Design rationale {#design}

Smart Mode follows the orchestrator-workers pattern from Anthropic's multi-agent work: a strong model owns the plan and delegates well-scoped subtasks to cheaper workers, rather than one model doing everything at one effort level. Three ideas make that practical here:

1. Roles, not model names. Decoupling behavior from model identity keeps every layer composable — you can pin models, swap providers, or turn a layer off without touching the others.
2. Complexity-scaled effort + cascade. Most turns are simple; spending flagship effort on them is waste. The classifier scales effort to the turn, and cascade correction retries at higher effort only when a cheap attempt actually falls short — the RouteLLM/cascade insight applied inside the agent loop.
3. Outcome-grounded learning. A stateless router can't learn, because it never sees whether its choice worked. The agent loop does — it sees the build fail, the test go red, the user correct the next turn. Smart Mode's learning layers close that loop: they persist what the cascade discovered and what decompositions succeeded, so the second session in a repo is smarter than the first.

See the design note for the full write-up and the layer-to-file map.