Models and effort
How Cusp chooses a model, how to switch models, and how reasoning effort maps onto each provider.
Every session has a model and an effort level. Cusp picks both for you, and you can change either at any time, including in the middle of a session.
How Cusp picks a model
When you add a provider, Cusp lists its models and ranks them. Two choices come out of that:
- Main model. The model the agent runs on. Cusp chooses the highest-ranked model for agentic coding that supports tool calling and isn't marked deprecated.
- Small model. A fast, inexpensive model for auxiliary work: session titles, the auto-mode classifier, compaction summaries and web page extraction. Cusp prefers a known small model from the same provider, then the cheapest capable one, then falls back to the main model.
The ranking comes from Cusp's model catalog, which records each model's context window, output limit, pricing, capabilities (tools, vision, PDF input, reasoning, prompt caching) and an agentic coding score. The catalog is refreshed from public sources such as models.dev and the OpenRouter model list.
Some typical picks for a freshly added provider:
| Provider | Main | Small |
|---|---|---|
| Anthropic | claude-opus-5-5 | claude-haiku-5-5 |
| OpenAI | gpt-6.1-sol | gpt-6-luna |
gemini-4-argon | gemini-3.8-flash | |
| xAI | grok-4.7 | grok-build-0.1 |
| DeepSeek | deepseek-v4.1-flash | deepseek-v4.1-flash |
| Z.ai | glm-5.3 | glm-5.3-flash |
| MiniMax | MiniMax-M3 | MiniMax-M3.1-Flash |
| Alibaba | qwen3.8-max-0902 | qwen3.8-flash |
These change as the catalog changes. For gateways such as OpenRouter and Vercel, Cusp offers the gateway's model list sorted by agentic ranking.
Choosing a model yourself
Models are written as provider:model, where provider is the id of a provider you configured. A bare model id means "this model on the session's current provider".
| Where | How |
|---|---|
| CLI, at start | cusp -m anthropic:claude-sonnet-5-5 or cusp --model gpt-6.1-sol |
| CLI, in a session | /model opens a picker; /model openrouter:z-ai/glm-5.3 switches directly |
| Desktop app | The model picker in the composer |
| Settings | "model": "anthropic:claude-opus-5-5" in any settings file |
| Subagents and skills | model: in the frontmatter |
Switching mid-session
You can switch models at any point. The conversation carries over. A few things to know:
- Reasoning state is replayed exactly to the same model. A different model receives a safe projection instead (the visible text, without opaque signatures), and Cusp records that the replay was patched.
- The edit tool may change. Moving from Claude to GPT switches the agent from
Edittoapply_patch. The transcript and permission rules are unaffected because both map to the same canonical tool family. - The prompt cache starts cold on the new provider. The first turn after a switch costs more.
PreModelSwitch and PostModelSwitch hooks run around a switch, and a PreModelSwitch hook can deny it. See Hooks.
Effort
Effort controls how much the model reasons before it answers. Cusp uses one scale for every provider and translates it.
| Level | Use it for |
|---|---|
none | No reasoning, when the model allows it. Fastest and cheapest |
minimal | Mechanical edits, renames, formatting |
low | Simple, well-specified changes |
medium | Everyday work. A good default for most sessions |
high | Debugging, cross-cutting changes, unfamiliar code |
xhigh | Hard problems where a wrong turn is expensive |
max | The model's full reasoning budget |
Set it with:
/effort highin the CLI (low,medium,high,xhighormax), or the effort control in the desktop appcusp --effort highat start"effortLevel": "high"in settings, oreffort:in skill and subagent frontmatter
How effort maps to providers
Each model declares the efforts it accepts. If you ask for a level the model doesn't support, Cusp clamps to the nearest supported one and tells you.
| Provider style | What Cusp sends |
|---|---|
| Anthropic, adaptive thinking | thinking: adaptive with the effort level. minimal is sent as low |
| Anthropic, budgeted thinking (older models) | A thinking token budget: 1,024 for minimal, 4,096 low, 10,000 medium, 24,000 high, 32,000 xhigh, 48,000 max |
| OpenAI Responses | reasoning.effort |
| Gemini | A thinking level or budget, depending on the model |
| Open models (DeepSeek, GLM, Kimi, Qwen, MiniMax) | The provider's own reasoning switch, where it has one |
Some models can't turn reasoning off. On those, none uses the lowest setting the model allows.
Context window
Cusp tracks token usage against the model's context window. When the window fills up, compaction frees space: first by trimming large old tool outputs (which remain available as artifacts), then by summarizing the conversation with a structured handoff that preserves the task list, files touched and decisions made.
Run /compact to compact now, optionally with instructions: /compact keep the API design discussion. PreCompact and PostCompact hooks run around it.
Cost
Every assistant message records its usage: input tokens (including cache reads and writes), output tokens and reasoning tokens. Cost is computed from the catalog's pricing, and cache reads are billed at the cache rate. /cost in the CLI shows the session total. Headless runs report total_cost_usd in their JSON output. When pricing for a model is unknown, cost is reported as null rather than guessed.