Skip to Content
GuidesModels & Effort

Models & Reasoning Effort

Every feature run uses one agent and one model. You choose a default model once, and you can override it for a single feature. Three more settings control how much a run thinks and spends: reasoning effort, adaptive model tiers, and the shep usage report.

The default model

A fresh install runs on claude-opus-5-5. Onboarding in the browser asks you to pick an agent and a model, so most people change this on day one.

If you set a model before, Shep keeps it. A new release never rewrites a saved models.default; the built-in default only applies to installs that have never chosen one.

Where model lists come from

Each agent offers its own list of models. For some agents Shep asks the agent or provider for the current list, so a new model shows up without a Shep upgrade. For the rest, Shep ships a built-in list.

AgentWhere the list comes from
Claude CodeThe Anthropic Models API (GET /v1/models) when ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN is set, otherwise the aliases the claude CLI reports, otherwise the built-in list
Cursor CLIcursor-agent --list-models
Codex CLIcodex debug models
OpenRouterOpenRouter’s public model list (/api/v1/models)
Together AITogether AI’s /v1/models (needs your API key)
Kimi Code, Gemini CLI, Copilot CLI, Cline, Ollama, LLM ProxyBuilt-in list

Live lists are cached for an hour. If a lookup fails, the picker falls back to the built-in list, so an offline machine still has choices.

A few notes on specific agents:

  • Claude Code on Bedrock, Vertex or Foundry uses provider-specific model ids, so Shep skips the Anthropic API there and uses the CLI aliases or the built-in list.
  • Kimi Code treats --model as a key in ~/.kimi/config.toml. The built-in list uses the default keys (kimi-k3, kimi-k2.7-code, …).
  • LLM Proxy fronts whatever your proxy serves, so its list is only a starting point.

The web model picker accepts any model id you type, not only the listed ones. Shep doesn’t check your input against the list, so a model released yesterday works as long as the agent accepts it.

Set your default model

From the terminal:

shep settings agent # pick the agent first shep settings model # interactive picker for that agent's models

shep settings model shows the built-in list for the agent you have configured. If you need a model that isn’t listed, choose it in the web UI instead: Settings → Agent → Agent & Model shows the live list and lets you type any id.

Settings → Agent with the Agent & Model picker open on Claude Code's models: a search box and Fable 5.1, Fable 5 and Opus 5.5, with Opus 5.5 checked

Override the model for one feature

shep feat new "Add rate limiting to the public API" --model claude-sonnet-5 # Claude Code shep feat new "Add rate limiting to the public API" --model gemini-2.5-flash # Gemini CLI shep app new "A booking tool for climbing gyms" --agent codex-cli --model gpt-5.6-sol

shep feat new --model uses your configured agent, so pass a model that agent serves. shep app new also takes --agent (claude-code, codex-cli, cursor, gemini-cli, …). In the web UI, the agent and model chip in the New feature composer lets you change both.

The model is pinned to the feature when it’s created. Later changes to your default don’t affect it. To change a pinned model, open the feature’s Overview tab and use Pinned execution. The new agent and model apply from the next start, approval or retry.

Reasoning effort

Reasoning effort sets how long the agent may think on each turn. The levels, from least to most reasoning:

LevelWeb label
lowLow
mediumMedium
highHigh
xhighExtra high
maxMax

If you leave effort unset (“Agent default”), Shep sends no effort flag and the agent uses its own default.

Only Claude Code receives the effort setting (as claude --effort <level>). Other agents ignore it. Cursor encodes effort in the model id instead (for example claude-opus-5-5-high), so pick the variant you want in the model list.

Set a default for new features:

shep settings effort # interactive picker shep settings effort high # set the default shep settings effort --clear # back to the agent's own default

Or use Settings → Agent → Reasoning effort:

Settings → Agent with Claude Code · Opus 5.5 selected and the Reasoning effort menu open on High, listing Agent default, Low, Medium, High, Extra high and Max; below, Adaptive model selection with high, medium and low complexity tiers

Override it for one feature:

shep feat new "Refactor the billing module" --effort xhigh

In the web composer, the effort menu sits next to the agent and model chip:

The New feature composer with Claude Code · Opus 5.5 selected and the effort menu set to Extra high

Like the model, effort is pinned when the feature starts. Shep sends the same level again when the run resumes, after an approval, and on retry, so changing your default later doesn’t change a run in flight. An invalid value passed to --effort is rejected before the feature is created.

Adaptive model tiers

A spec-driven run produces a plan of tasks, and many of them are mechanical: renames, translation keys, enum entries, stories. With adaptive model selection on, Shep classifies each planned task as High, Medium or Low complexity and runs it on a model sized for that tier.

The rules:

  • The pinned model is a ceiling. A task never runs on a model more capable than the one you pinned. If you pin a mid-size model, High tasks run on that model, not a larger one.
  • Tiers stay in the pinned model’s family. A Gemini pin only routes to Gemini models; a Claude pin only to Claude models. To cross families, set a tier model explicitly.
  • Only models the agent serves are used. A pinned model Shep doesn’t recognise disables routing for that run instead of failing it.
  • Task order is kept. Consecutive tasks that resolve to the same model run together, and dependent tasks never move.

Routing applies to the implementation tasks of spec-driven runs. Fast-mode runs use the pinned model throughout.

shep settings adaptive-models # show the resolved tier plan shep settings adaptive-models --enable # turn routing on shep settings adaptive-models --low claude-haiku-4-5 # choose the Low-tier model shep settings adaptive-models --high "" # empty string: derive the tier again shep settings adaptive-models --clear # drop all tier overrides shep settings adaptive-models --disable # run every task on the pinned model
FlagWhat it does
--enable / --disableTurn routing on or off
--high <model>, --medium <model>, --low <model>Pick the model for a tier. An empty string goes back to deriving it from the pinned model
--clearRemove every tier override

Without options, the command prints the plan: the agent, the pinned model (the ceiling), and the model each tier resolves to. If the pinned model has no smaller sibling in the agent’s list, it tells you every task would still run on the pinned model.

The same settings are in Settings → Adaptive models (“Route tasks by complexity”, plus a model per tier).

See what runs cost: shep usage

shep usage # last 7 days, grouped by phase shep usage --since 24h --by agent # last day, by agent shep usage --by feature # which feature used the most shep usage --by model --json # machine-readable, by model
FlagDefaultValues
--since <duration>7dA number and a unit: s, m, h, d, w (for example 36h, 2w)
--by <dimension>phasephase, agent, feature, model
--jsonoffPrint the full result as JSON

The report lists runs started, completed, failed and stopped in the window, then one row per group: runs, p50 and p95 phase duration, tokens, cost and failure rate.

Cost is only as complete as what the agents report. Claude Code reports cost. The SDK providers (OpenRouter, Together AI, Ollama, LLM Proxy) report tokens but no cost, so their cells show n/a. A total that includes such runs is marked PARTIAL, and a group with some missing costs shows its sum with a +.

What’s next