> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Custom routers

Define a custom router that automatically picks the right model for each task, based on task complexity or rules you write, and use it from the model picker.

Custom routers automatically pick the right model for each task, using routing logic you define. Instead of committing to a single model up front, you set the logic once, and Warp resolves a concrete model each time you send a prompt, based on either task complexity or rules you write.

## Key features

-   **Complexity-based routing** - Warp classifies each task’s difficulty and routes to the model you mapped to that level.
-   **Rule-based routing** - Write natural-language rules that describe when to use each model.
-   **Any supported model** - Route to any concrete model you have access to, across providers.
-   **Settings or file** - Create a router in settings, or author it as a YAML file that Warp loads automatically.
-   **Team-synced routers** - Admins can share a router with an entire team (Enterprise).

## How it works

A custom router appears in the [model picker](/agent-platform/inference/model-choice/#how-to-change-models) as its own entry, alongside Warp’s built-in Auto models and individual models. You select it like any other model.

When you send a prompt, the router resolves to a single concrete model and runs the task on it, just like Warp’s built-in Auto models. You can always see which model actually ran.

Warp chooses a model when you start a conversation and keeps using it for the rest of that conversation. Very short, trivial prompts (like a quick “hello”) don’t lock in the choice.

Note

A router always resolves to concrete models that you choose. It can’t route to an Auto model or to another router.

## Routing types

A router uses one of two routing types. You choose the type when you create the router.

### Complexity-based routing

Warp classifies each task as easy, medium, or hard and routes to the model you assigned to that level. You also set a default model, which Warp uses for any level you leave unset or when it can’t determine complexity.

Use complexity-based routing to put lower-cost models on simple work and more capable models on harder tasks, without describing tasks yourself.

### Rule-based routing

Rule-based routing routes each task using rules you write. Each rule pairs a classification prompt (a natural-language description of when to use a model, such as “debugging or fixing failing tests”) with the model to use when that rule matches.

-   Warp evaluates rules from top to bottom, and the first rule that matches wins. Rules higher in the list take precedence over those below.
-   If no rule matches, Warp uses the required default model.

## Create a router in Warp

1.  Open **Settings** > **Agents** > **Warp Agent** and find the **Custom Routers** section.
2.  Click **Add router** and enter a name.
3.  Under **Routing type**, choose **Complexity-based** or **Rule-based**.
4.  Configure the routing:
    -   **Complexity-based** - Select a **Default** model, then assign models to **Easy**, **Medium**, and **Hard**.
    -   **Rule-based** - Select a **Default model**, then click **Add rule** for each rule, write a **Classification prompt** describing when to use the model, and select the model. Rules are matched top to bottom, so order them by precedence.
5.  Click **Save**.

Your router now appears in the model picker. Saving also writes a file: use **Open file** to edit it directly, or **Delete** to remove the router.

## Author a router as a file

Custom routers are stored as YAML files in `~/.warp/custom_model_routers/`, with one router per file. Warp loads every file in that directory and reloads automatically when you add, edit, or remove one, with no restart required. Routers you create in settings are saved here too.

Routing targets use the same `model_id` values listed on the [Model choice](/agent-platform/inference/model-choice/#available-models) page. Every target must be a concrete, Warp-supported model. You can’t route to an Auto model, another router, or a model from a [custom inference endpoint](/agent-platform/inference/custom-inference-endpoint/).

A complexity router uses `type: complexity`. `default` is required and is used for any bucket you omit:

```
name: Cost savertype: complexitydefault: claude-4-6-sonnet-highrouting:  easy: claude-4-5-haiku  medium: claude-4-6-sonnet-high  hard: claude-4-8-opus-high
```

A rule-based router uses `type: prompt`. `default` is the required catch-all used when no rule matches, and `routing` is the ordered list of rules:

```
name: By tasktype: promptdefault: claude-4-6-sonnet-highrouting:  - description: debugging or fixing failing tests    model: claude-4-8-opus-high  - description: writing documentation or comments    model: gpt-5-5-low  - description: simple one-line edits or renames    model: claude-4-5-haiku
```

If a file can’t be parsed, Warp shows a non-blocking error identifying the file and skips it; your other routers keep working.

## Use a router

1.  In the prompt input, open the model picker by clicking the current model name.
2.  Choose your router from the list.

Your selection persists for future prompts, like any other model choice.

## Team-synced routers

Team admins can create routers that are shared with the whole team, so everyone can use the same routing strategy. Team-synced routers are an Enterprise feature, and only admins can create or edit them.

To create one, an admin:

1.  Opens the [Admin Panel](https://app.warp.dev/admin/) and goes to **Models**.
2.  Finds the **Custom Routers** section and clicks **New router**.
3.  Chooses **Complexity-based** or **Rule-based**, sets the models or rules, and clicks **Create**.

Team-synced routers appear in the model picker for every team member, who can select them like any other router.

## Credits and model availability

A custom router resolves to a concrete model, so credit usage matches whichever model the router selects for each task. See [Credits](/support-and-community/plans-and-billing/credits/) for how credits are consumed.

Like Warp’s built-in Auto models, custom routers consume Warp credits and don’t draw on your own provider keys, even if you’ve configured [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/). To run a model on your own key, select that model directly instead of a router.

If a router targets a model you don’t have access to or that’s disabled for your organization, Warp falls back to the router’s default model. If no usable model remains, Warp falls back to a built-in default and tells you.

## Related resources

-   [Model choice](/agent-platform/inference/model-choice/) — Supported models and `model_id` values, including Warp’s built-in Auto models.
-   [Bring Your Own API Key](/agent-platform/inference/bring-your-own-api-key/) — Use your own OpenAI, Anthropic, or Google API keys.
-   [Custom inference endpoint](/agent-platform/inference/custom-inference-endpoint/) — Route Warp through any OpenAI-compatible endpoint.
-   [Admin Panel for teams](/enterprise/team-management/admin-panel/) — Manage team-wide settings, including team-synced routers.