> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weaveos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Models and routing

> How Weave Router chooses a model, and every control you have over that choice

Weave Router decides per request. There is no fixed ladder of models and no static rule table: a scorer evaluates each call against your settings and picks the best fit. This page covers what the scorer takes into account and how you steer it.

## How a decision is made

* **Every LLM call is routed**, not just the first prompt of a session. In an agentic loop that means each tool call — and subagents, which have their own context, are routed too.
* **The requested model matters.** The model your agent asked for is the anchor: the router compares candidates against it and only moves the turn when the trade-off is worth it.
* **Upgrades are allowed.** If a turn needs a stronger model than the one requested, the router will move up a tier even though it costs more.
* **Context is respected.** The router estimates the context in each request and filters candidates using their provider-specific windows and an output reserve. When the conservative estimate excludes every candidate, the widest eligible models remain available for the provider to decide actual fit.
* **Caching is priced in.** Switching models evicts the provider-side prompt cache, so the router compares the expected gain of switching against the cache-eviction cost and stays put when staying is cheaper. Anthropic's cache is modelled with a one-hour time to live (TTL), other providers with five minutes.
* **Sessions can be pinned.** Once a session is warm on a model, the router prefers to keep it there until the trade-off clearly changes.

<Note>
  The router is cache-*aware*, not a cache manager. It does not send keep-alive pings, warm caches on a schedule, or predict usage patterns to pre-warm them.
</Note>

## Routing priority

Under **Models & routing → Routing priority**, the quality-versus-price dial sets how aggressively the router trades quality for cost. The distribution preview shows how the current split shifts traffic across model tiers. Weave ships a tuned default; **Reset to default** returns to it.

### Subscription routing

The same panel picks how subscriptions and credits interact:

| Mode | Behavior |
| - | - |
| Let router choose (default) | Subscriptions are used where they apply, and the router picks models by your priorities. |
| Strict pass-through until low | Every subscription-covered request goes to the model you asked for — no substitution — until plan usage reaches your threshold. |
| Use prepaid credits only | Subscriptions are ignored and every request bills Weave Router credits. |

**Strict pass-through until low** takes a threshold (default 80%): the router stays out of the way until that share of the plan is used, then resumes routing so engineers keep working past their limit instead of being blocked.

<Warning>
  Switching to **Use prepaid credits only** without a funded balance or auto-recharge means every request bills prepaid credits and starts failing at \$0. Weave blocks the change until credits are ready.
</Warning>

## Choosing which models can be used

### Models

**Models & routing → Models** lists every model in the router's roster. Uncheck one and the router stops selecting it — useful when a model isn't on your organization's approved list. Weave adds new models to the roster as providers release them; new entries are enabled by default, so re-check the list after a major release if you maintain an allowlist.

### Providers

**Models & routing → Providers** excludes an entire provider, including as a failover target. Requests are never sent through an unchecked provider.

### Preferred models

Preferred models let you lean toward specific models in priority order. The router still picks per request — a preference presses the scale on close calls rather than locking other models out. There is no strict priority ordering, and no way to require model A before model B is allowed.

## Overriding the router for one session

| Action | How |
| - | - |
| Pin a session to a model | `/force-model <model-id>` in Claude Code (`/fm` in pi) |
| Clear the pin | `/unforce-model` (`/ufm` in pi) |
| Pin programmatically | Send the `x-weave-force-model` header with the model ID |
| Bypass the router entirely | `npx @weave-os/router off --claude`, then quit and reopen the client |

An unrecognized model ID in the force header fails the request with a 400 that names the value, and so does a model your organization has excluded. The router doesn't fall back to automatic routing, so a typo can't pass for a working pin. The `/force-model` command is different: it replies that the ID isn't recognized and keeps routing automatically.

## Seeing the decision

The first routed response in a session, and any response where the serving model changes, carries an in-band marker (`✦ Weave Router → <model>`) plus the reason for the pick. Turns that stay on the same model don't repeat it. Clients that display the route themselves (like pi) suppress it; programmatic callers can suppress it by sending `X-Weave-Routing-Marker: off`. Claude Code's managed status line shows the response model, current selection, and an estimated cost difference, and the full history lands in the [Router report](/router/reporting).

## Context indicators

Claude Code's managed status line prefers the client's own reported percentage, such as **Context 58%**. Codex's integration uses the terminal title and has no client-native percentage or inline status bar through its lifecycle hooks.

When native usage is unavailable, a recent session snapshot can show **last Router ctx est. \~72k/128k**. The numerator is a conservative whole-request estimate, including image estimates. The denominator is the effective window of the model/provider that served that request; some of that space is reserved for output. It is not remaining input capacity or the client's compaction budget. Estimates never supply a percentage or warning cue.

These displays refresh between turns through status-line or lifecycle events. Asynchronous telemetry can lag the latest turn, so snapshots are labeled **last** and expire after five minutes. Older clients or Routers omit unavailable context fields while preserving existing indicators. A model change alone does not compact a conversation: the client owns its transcript and compaction. Claude Code's `/compact` is a client command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.