Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content
Using the harness

Model routing

Every turn follows the Minima loop:

recommend  ──▶  run the model yourself  ──▶  judge quality  ──▶  feedback
  1. Recommend. The harness sends the turn to the Minima recommender, which ranks the candidate models and returns the cheapest one expected to clear the task. Candidates are pre-filtered to providers you actually have keys for.
  2. Run. The harness runs that model directly against the provider API — Minima never sees your prompt or code.
  3. Judge. The outcome is labeled by the strictest evidence available (see Verified outcomes).
  4. Feedback. The outcome and realized cost/tokens are reported back so the next recommendation is sharper — including per-step results for gate-verified plan steps.

This is the same engine described in the SDK Concepts — the harness is a client of it, and Under the hood covers the full turn lifecycle.

Auto vs. pinned

  • Auto (default). The status bar shows auto; Minima picks a model per turn from the candidate set (gemini-2.5-flash, claude-haiku-4-5, claude-sonnet-4-6, gemini-2.5-pro, claude-opus-4-8 by default).
  • Pinned. Choose a model with /model in the TUI, or --model <id> (optionally --provider <name>) on the CLI. Routing is bypassed — the harness always runs that model. /model auto returns to routing.
ℹ️Note

The cost/quality tradeoff defaults to the middle of the slider (5 of 0–10). Lower it to favor cheaper models, raise it to demand higher predicted quality. See the slider.

Offline mode

--offline bypasses the Minima recommender entirely — no recommend/feedback round-trips. Pair it with --model/--provider to run a specific model with no routing at all:

minima --offline --model gpt-4o-mini --provider openai -p "quick summary"

Routing also fails open: if the recommender is unreachable mid-session, the harness continues on the current model (with no feedback sent) instead of blocking your work. Use /reconnect in the TUI to re-establish the routing client.

Verified outcomes and judging

The harness labels outcomes by a strict evidence hierarchy — the same feedback-truth discipline throughout:

  1. Deterministic checks win. With plan verification on (the default), a plan step's verify command passing red→green is the label — reported as gate evidence, the strongest kind. Verified steps also ride as per-step outcomes in the same feedback call.
  2. A sampled LLM judge covers the rest. About 15% of unchecked turns are graded by a cheap judge model. /judge on|off toggles it; MINIMA_JUDGE_SAMPLE tunes the rate.
  3. Everything else is telemetry. Unjudged turns report realized cost and latency with no quality claim — never a fabricated score.

Provider faults (rate limits, 5xx) are reported as infrastructure errors, so a flaky network never teaches Minima that a model is bad.

Recovery: when a turn fails

A verified failure doesn't just get reported — it triggers the recovery ladder: re-route to a stronger model, revise the plan (briefed by the check's failure output and matching failure lessons from memory via POST /v1/diagnose), or back off on a transient provider fault. Each retry starts from a clean transcript.

💡Tip

Reporting quality and realized cost is what turns Minima's savings report from an estimate into a measurement. The harness does this automatically, with honest labels — it's the reference implementation of the feedback contract.

Memory isolation

Routing recall and learning are scoped to a namespace — by default the Mubit project minima auth provisioned for the current repo, or MINIMA_NAMESPACE if set. Different repos therefore learn independently. See Configuration → per-repo memory isolation and How Minima uses Mubit.