Models, tokens, and thinking levels

BMAD does not pick a model. Your host does: Claude Code, Cursor, Codex, or whatever agent you installed it into runs the model, and BMAD rides on top as a procedure. So "use the best model at the best thinking level" is not a BMAD setting you flip; it is a set of decisions you make at the host, plus the few places BMAD does expose model and effort control. This page is how to spend model capability and tokens well across a BMAD project: which model per phase, what thinking effort, and how to move expensive work to where it is cheap.

Model facts here are current as of this writing (Claude family); the strategy is durable even as the specific IDs and prices move, so treat the numbers as dated and the shape as the point.

On this page

• The model tiers
• Thinking and effort
• Choosing the model per phase and role
• Shifting tokens to where they are cheap
• A worked cost picture
• Pitfalls
• Hands-on: measure a real run’s cost and cache
• Under Claude Code: /model, effort, and automatic caching internals

The model tiers

The Claude family spans roughly three tiers by capability and price. Pick per job, not per project.

The rule of thumb: judgment work on the strongest tier, mechanical work on the cheapest. A PRD or an architecture decision is judgment; extracting claims from a report or renaming symbols across a story is mechanical. Running everything on the biggest model is the most common way to overspend; running everything on the cheapest is the most common way to ship a wrong schema.

Thinking and effort

Current Claude models use adaptive thinking (thinking: {type: "adaptive"}): the model decides when and how much to think, and you tune the depth with an effort knob rather than a fixed token budget. Effort has five levels:

Two facts shape how this maps onto BMAD. First, effort matters more on the current models than it used to, so it is worth setting per phase rather than leaving at the default. Second, BMAD's phases sort cleanly by how much thinking they deserve:

In Claude Code you set the model with /model and effort via its settings (it defaults to xhigh); fast mode (/fast, Opus 4.8) trades premium price for ~2.5x output speed on the same model when latency matters in an interactive loop. Other hosts expose their own controls; the mapping above is what to aim for whatever the knob is called.

Choosing the model per phase and role

BMAD's four phases have different work profiles, so the ideal model shifts across a project. A sensible default portfolio:

• Analysis and Planning (Mary, John). Research framing, briefs, PRDs, and architecture are judgment calls where a wrong turn is expensive downstream. Run the planning personas on the strongest tier (Opus 4.8, or Fable 5 for the genuinely hardest problems). These are also the phases you can run as web bundles on a flat-rate subscription.
• Solutioning (Winston). Architecture is judgment; keep it on Opus. Cutting epics and stories is more mechanical and can drop a tier.
• Implementation (Amelia). Dev stories are coding-and-agentic work: Opus 4.8 or Sonnet 5 at xhigh. High-volume, well-specified stories are exactly where Sonnet 5 earns its lower price. QA generation and mechanical fixes can drop to a cheaper tier.

BMAD exposes model choice directly in two places:

Deep Recon's subagent_models. The research skill lets you set an ordered model preference for its spawned research assistants (see the recon how-to). The shipped guidance is exactly the judgment-vs-mechanical split: keep the lead on the strongest model, run researchers at most one tier down, never drop judgment work to the smallest tier, and let mechanical extraction use a fast tier. That single override turns a deep research run from "everything on Opus" into a right-sized fleet.

The BMad Loop's per-stage mux. The autonomous loop drives fresh coding-agent sessions through a terminal multiplexer and can point different stages at different agents (claude, codex, gemini, copilot, antigravity, opencode), mixing per stage. That means you can run implementation on your strongest coding model and the adversarial review on a different one for independent perspective, deterministically, without a human in the loop.

Everywhere else, the model is whatever your host is set to, so the lever is the host's model selector plus a fresh chat per workflow (which lets you switch model between phases without dragging one model's context into the next).

Shifting tokens to where they are cheap

Token spend in a BMAD project concentrates in a few places, and each has a lever:

Research fan-out is the biggest single cost. Parallel research burns roughly an order of magnitude more tokens than a single-agent chat (the multi-agent research design that beats a single agent does so at ~15x tokens). Deep Recon's effort knobs are the dial: the quick/standard/deep presets set subagents (2/3/6), sources per round (5/8/12), and rounds (1/2/3). Run quick for a question you half-know and deep only when the decision genuinely warrants it. Depth and sources are caps, not quotas, so a dimension stops early on coverage.

Rent someone else's crawler. Deep Recon's Draft mode and BMAD's web bundles move the expensive part of research (long agentic browsing) onto a flat-rate chat subscription instead of metered IDE tokens, then Process the report back. For a team, a PRFAQ pass and three rounds of research in a Gem cost zero marginal dollars; the same work in the IDE is real spend. This is the highest-leverage token shift BMAD offers.

Prompt caching pays for the file-first design. BMAD re-reads its state from disk on every workflow, and a stable prefix (a frozen system prompt, a fixed tool list, a large project-context.md) caches: reads cost about a tenth of the base input price, writes a small premium. The discipline that makes caching work is the same discipline BMAD already enforces: keep the stable stuff first and the volatile stuff (the current question) last. A fresh chat per workflow does not throw caching away, because the cache is keyed on the reused prefix, not the conversation.

Batch the mechanical. Bulk, non-interactive work (classify a backlog, extract from many documents) runs at half price through the Batch API. If a BMAD step fans out over many independent items and does not need to be interactive, that is a batch job.

Cap the agentic loops. For autonomous work, a task budget gives the model a token ceiling for a whole loop so it paces itself and finishes gracefully instead of being cut off, distinct from the hard per-response max_tokens limit. The BMad Loop and dev-auto are where this matters; the efficiency page returns to it.

A worked cost picture

For a greenfield project, the token budget is dominated by two phases: research (if the decision is uncertain) and implementation (always). A cost-aware run:

1. Frame cheaply. Brainstorm and forge on your default model; they are short.
2. Research at the right depth. standard preset by default; quick if you half-know the answer; Draft-to-a-web-bundle for broad public sweeps. Set subagent_models so researchers run a tier below the lead.
3. Plan on the strong tier. PRD, UX, and architecture are judgment; Opus/Fable at high. Consider running these as web bundles on a flat rate.
4. Implement on the value tier. Sonnet 5 at xhigh for the bulk of dev stories; escalate a genuinely hard story to Opus. QA and mechanical fixes on a cheaper tier or in batch.
5. Automate with a budget. If you run the loop unattended, set a task budget and a gates.mode you trust, and let the mux put review on a second model.

The through-line: match the model and the effort to the stakes of the step, and move browsing and bulk off the metered path. Most overspend is one of three mistakes: max effort everywhere, the biggest model for mechanical work, or a deep research run for a question a quick run would have answered.

Pitfalls

• Effort maxed everywhere. max on routine work burns tokens for no gain and can cause overthinking. Default to high, xhigh for coding, max only when correctness dominates cost.
• One model for everything. The biggest model for mechanical extraction is waste; the cheapest for architecture is risk. Use subagent_models and the loop mux to split the work.
• deep research by reflex. The preset is a token multiplier; reach for it only when the decision warrants six assistants and three rounds.
• Ignoring the flat-rate path. Running long research browsing on metered IDE tokens when a web bundle would do it for a flat fee is the most common avoidable cost.
• Cache-blind prompts. Interpolating a timestamp or a per-run ID into the front of a workflow's context silently defeats caching. Keep the stable prefix stable.

Hands-on: measure a real run's cost and cache

Read your own numbers before you theorize about them. This is a five-minute session you can replay in any BMAD repo.

Set the model and effort for the session, then run one dev story:

/model claude-opus-4-8
/effort xhigh
# ... run a dev-story workflow to completion ...
/usage

/usage reports cost and two durations, wall-clock and API time, plus a per-model breakdown of input, output, cache-read, and cache-write tokens. The number to watch is the cache-read share. On the first workflow the stable prefix (system prompt, tool list, project-context.md) is written, so cache-write is high. On the second workflow in the same session that same prefix is a read, so cache-read dominates:

Illustrative (run it in your own repo; not machine-verified here).

/usage
  Session cost:      $1.84
  Duration (wall):   22m 41s
  Duration (API):    6m 12s
  claude-opus-4-8
    input           18,204
    output          31,077
    cache read     412,900   (89%)
    cache write     41,880

Wall-clock far above API time is you reading and typing while the model sits idle. The 89% cache-read share is the file-first design paying off: re-reading state each workflow bills at about a tenth of input, not a full re-read.

To log the same numbers for a harness, run headless and pull them with jq. --output-format json returns total_cost_usd and usage_by_model:

claude -p "implement story 2.3 per the acceptance criteria" \
  --model claude-sonnet-5 --output-format json \
  | jq '{cost: .total_cost_usd, usage: .usage_by_model}'

Illustrative (run it in your own repo; not machine-verified here).

{
  "cost": 0.4123,
  "usage": {
    "claude-sonnet-5": {
      "input": 9102,
      "output": 15330,
      "cache_read": 388120,
      "cache_write": 40210
    }
  }
}

Append that object per story and you have the raw feed for the benchmark harness on page 17: cost per story, cache-hit rate, and output tokens, all comparable across model and effort settings.

The payoff is one substitution you can now see instead of guess. Switch the bulk dev stories from claude-opus-4-8 to claude-sonnet-5 and watch cost per story fall in /usage while the cache-read share holds steady.

Under Claude Code: /model, effort, and automatic caching internals

BMAD names the strategy; the host holds the knobs and decides what persists. In Claude Code the scoping is precise.

Aliases opus, sonnet, haiku, fable resolve to full IDs (opus to claude-opus-4-8). So a fresh chat per BMAD workflow keeps your /model choice but drops a one-off /effort high; put effort in the settings effort key if you want it to stick per phase. A dev-story subagent or the deep-recon skill can carry its own model:/effort: frontmatter, which is how BMAD's per-role split lands without touching the session default.

Prompt caching is automatic, with breakpoints at four boundaries: the system prompt, the tools-and-skill-descriptions block, the CLAUDE.md-and-loaded-files block, and the conversation prefix. Cache reads bill at about a tenth of input (the write is a small premium). TTL is 1 hour on a subscription, 5 minutes on an API key or cloud provider, so idle time between BMAD phases costs more on metered access. /usage breaks out cache read and cache write so you can watch the ratio. --exclude-dynamic-system-prompt-sections moves per-machine content (environment info, MCP tool names) out of the system prompt so the cache reuses across machines on the same repo.

BMAD's file-first design is what keeps these breakpoints warm: a fixed system prompt, a large but unchanging project-context.md, a tool list stated once. Re-reading state each workflow is then a cache read, not a re-bill. Interpolate a timestamp or per-run id into that prefix and every breakpoint downstream goes cold.

With models and tokens handled, the next page makes efficiency systematic: the levers that cut cost, context bloat, and rework across a whole BMAD project. 👉