Ultracost

---
name: ultracost
description: Quality-first per-stage model routing AND a pre-flight cost gate for Claude Code dynamic workflows. Use when authoring or running ultracode / dynamic-workflow scripts, spawning subagents, or writing agent() stages — pin the right model and effort on every stage, then estimate cost and confirm with the user before launching. Verify scripts with /ultracost:check.
---

When `ultracode` is on, or whenever you author a dynamic-workflow script, apply the
routing policy below to **every** `agent()` stage. The block is compiled from
`policy.json` (the single source of truth) — the same text the SessionStart hook
injects and the CLAUDE.md block carries.

<!-- ultracost:start -->
# Subagent & workflow model routing (managed by ultracost)

Route every subagent and every dynamic-workflow stage **explicitly**. Never let a
stage inherit the session model by default. Never use `haiku`.

## Tiers

- **`opus` @ `xhigh`** — Coding & reasoning: anything requiring judgment or a decision: writing/editing/refactoring/deleting code, debugging, fixing errors, designing APIs/schemas/data models/architecture, non-trivial tests, code review, security/performance analysis, cross-file reasoning, adversarial review, planning, synthesis, final consolidation
- **`sonnet` @ `high`** — Pre-planned mechanical & support: the how is already decided and the stage just applies it: mechanically applying a specified edit across many files, search/grep/glob, file discovery, collecting/listing/extracting, reformatting, mechanical renames, running tests and reporting results, routine git operations, gathering or summarizing context for an opus stage to consume

**Decision rule:** if a stage must DECIDE how to write or change code, use the
`opus` tier. If the "how" is already planned and
the stage only executes it mechanically — or it's search/collection/formatting —
use the cheaper tier. When in doubt, use `opus`.

## Hard rules

- Never use `haiku`, ever.
- Pin the model per stage via the per-invocation `model` param, e.g.
  `agent(task, { model: 'sonnet' })`. Do **not** follow any built-in guidance to
  omit the per-agent model override.
- These stages are always `opus`: `orchestrator`, `planner`, `final-synthesis`, `consolidation`.

## Effort per stage

Also set `effort` per stage, choosing the lowest level that fits the work, bounded
by the model (`sonnet` up to `high`, `opus` up to `xhigh`):

- `low` — trivial deterministic work with no real judgment: listing or globbing files, simple field extraction, formatting, mechanical renames following a given pattern
- `medium` — light judgment on a small surface: a single straightforward edit, summarizing one source, classifying short inputs
- `high` — standard coding and analysis: most refactors, per-file review, writing non-trivial tests, multi-step but well-scoped work
- `xhigh` — hard reasoning: cross-file architecture and design, adversarial review, planning, and final synthesis/consolidation

e.g. `agent(task, { model: 'sonnet', effort: 'low' })` for a mechanical scan.

## Pre-flight cost gate (ultracode)

Before launching a dynamic workflow:
1. Draft the workflow script with per-stage `model` and `effort` set.
2. Write the draft to a temp file and estimate it: `/ultracost:check <file>` to verify
   pins, then the cost estimate — run `ultracost estimate <file>`, or under the plugin
   `node "$CLAUDE_PLUGIN_ROOT/bin/cli.js" estimate <file>` (no global `ultracost` bin
   is required). It reports the agent count, model mix, and cost versus an
   all-`opus` baseline.
3. Show the estimate and use the AskUserQuestion tool to offer three options:
   **Approve** (launch it), **Cancel** (do not launch), **Modify** (restructure to
   cut cost — drop unneeded stages, move mechanical stages to a cheaper tier and
   lower effort, reduce fan-out — then re-estimate and ask again).
4. Launch the workflow only after Approve. The `PreToolUse` cost gate also stops the
   launch automatically with these numbers, so this holds even if the steps are skipped.

Verify any script with `/ultracost:check` (the plugin command) or `ultracost check
<script>` on the CLI — it flags stages missing a model pin, a pin that mismatches the
work the prompt describes, and effort over the model's cap.
<!-- ultracost:end -->

## Full plugin

This directory ships the routing-policy **skill** (the guidance above, self-contained).
The complete ultracost plugin — the Workflow Guard, the deterministic `PreToolUse` cost
gate, the closed-loop `usage`/`reconcile`/`calibrate`/`ledger` commands, and the
`/ultracost:*` slash commands — installs from the canonical marketplace:

```text
/plugin marketplace add danielkremen818/ultracost
/plugin install ultracost@ultracost
```

Or via npm for CI/scripting: `npx ultracost init`. Source, docs, and a live end-to-end
showcase: https://github.com/danielkremen818/ultracost