Understanding costs

How CodeHerder tracks model spend and how to view costs by window, agent, model, or task — from the CLI or the web app's Cost breakdown page.

CodeHerder records model spend and displays totals in USD. You can view costs for your own activity, for a specific agent, or for the whole workspace — broken down by any window from today through the last 30 days.

How spend is tracked

When an agent sends a request to an AI model and receives a response, that exchange is one turn. Cost is recorded per turn and attributed to the session in progress. Sessions are grouped under the task they belong to, so you can see what a task cost across all its stages.

Which sessions report cost: a session running the Claude, Codex, OpenCode, or Pi harness reports its spend this way. A Cursor session doesn’t report spend yet, so it always shows $0 here — see Choosing the coding-agent CLI your agents run for what else differs by harness.

Costs are reported in USD.

Reading the token breakdown

Every turn involves several categories of tokens, each billed at a different rate:

Fresh input — the part of the prompt that is new and uncached. Billed at the standard input rate.
Cached read — prompt tokens that were already stored in the model’s prompt cache. These are billed at a fraction of the fresh-input rate, so a large cached-read count is a sign of efficiency, not expense. When CodeHerder’s agents re-read the same long task brief across many turns, most of it hits the cache.
Cache write — tokens written to the cache on a turn that establishes or extends a cache entry. Billed slightly above the fresh-input rate but amortised quickly because every subsequent read of those tokens is cheap.
Output — tokens the model generates in its response.

The CLI surfaces all four counts on the summary line:

total:   $0.0421   turns: 12   in: 42000   out: 3200   cache-r: 180000   cache-w: 8400   think: 0   cache-hit: 81.2%

cache-r is cached-read tokens; cache-w is cache-write tokens; cache-hit is the share of all input tokens that were served from the cache. A high cache-hit percentage means the stable prefix of your agents’ prompts is being reused efficiently.

The web app’s Cost breakdown page shows the same categories: an Input tokens tile whose value is the fresh count, with cached read and cache write given as a sub-line beneath it. See Cost in the web app below for the whole page, in the order it renders.

Checking your costs

Run ch costs to see your own spend for today:

ch costs

The output shows the time window, total spend, turn count, and per-token-class counts. With no flags, the window is today.

Changing the time window

Widen the window with --window:

ch costs --window week
ch costs --window month
ch costs --window yesterday

Or set an exact lookback with --since:

ch costs --since 7d
ch costs --since 24h

--since accepts a relative duration (Nd, Nh, or Nm for days, hours, and minutes) or a full RFC 3339 timestamp. --window and --since are mutually exclusive.

Scoping to an agent or workspace

To view costs for a specific agent:

ch costs agent <agentId>

To view the workspace-wide total (defaults to the workspace set in CH_WORKSPACE_ID):

ch costs workspace
ch costs workspace <workspaceId>

Workspace-wide cost views need the Starter plan; your own costs and an agent’s costs (above) are open on every plan — see Plans and limits.

Breaking down by agent or model

Add --by to split the totals into per-agent or per-model tables:

ch costs --window week --by agent
ch costs --window week --by model
ch costs --window month --by agent,model

When both agent and model are requested, both tables are printed below the totals. The day-by-day sparkline is always included.

Use --json to receive the raw JSON envelope instead of the formatted output:

ch costs --window month --by agent,model --json

Costs for one task

To see the spend for a specific task, add --task:

ch costs --task <taskId>
ch costs workspace --task <taskId> --window month

ch task show <taskId> also prints a cost line directly in the task summary. It covers the last 30 days and shows total spend and turn count. When cache-read cost is non-zero the line breaks it out parenthetically — for example:

cost (30d):  $0.1234 total   ($0.0921 generation · $0.0313 (25%) cache-read)   48 turns

When the task has run across multiple workflow stages, a per-stage breakdown is printed below.

Model escalation and rework costs

When a review or verify stage sends a task back to code for rework, CodeHerder automatically runs the rework on a more capable model tier. The first build attempt uses the standard tier; after the first rejection, all subsequent build attempts use the more capable tier.

This means a task that required rework will typically show spend across two model tiers — but the per-stage breakdown in ch task show <taskId> won’t show it: that breakdown is grouped by stage only, so every code attempt is collapsed into one code line regardless of which model tier ran it.

To see the two-tier split for a single task, combine --task with --by model:

ch costs --task <taskId> --by model

This breaks that task’s spend out per model, so the standard-tier and more-capable-tier rows appear separately. To see how model spend is distributed across your whole workspace instead, drop --task and widen the window: ch costs --window week --by model. The web app has the same rollup, scoped to the window you select there rather than to one task — see By agent template and by model in Cost in the web app below.

For the full explanation of when escalation applies and which task types use it, see How work flows. To see how often each model and stage combination succeeds without rework, see Quality metrics: first-pass rate in Monitoring your agents.

Cost-aware model routing

Cost-aware model routing is a separate setting that moves in the opposite direction from escalation: escalation moves a stage up to a more capable model after rework is rejected, while routing moves a stage down to a cheaper model when it’s safe to do so. Escalation is about getting a task right after a setback; routing is about spending less when quality won’t suffer. The two run independently, so a task can be escalated and routed at different points in its life.

New workspaces have cost-aware routing turned on. Older workspaces may start off, until an owner or admin turns it on. Either way, a workspace owner or admin can turn it on or off from Settings → General, in the Cost-aware model routing section — check or clear “Route eligible stages to a cheaper model when quality allows.” It’s a per-workspace setting and only appears on a workspace, not on a group.

When it’s on, a workflow stage that is pinned to a specific model can run on a cheaper model instead of its pinned default — but only when CodeHerder expects no drop in quality. That expectation is based on how often that kind of work has recently succeeded on the first try without rework: if the cheaper model’s first-pass success rate on similar stages isn’t high enough, CodeHerder keeps the pinned model. Stages that aren’t pinned to a specific model are never affected either way.

Routing also needs somewhere to look for a cheaper option: it only ever picks from that config’s Allowed models, and only within the pinned model’s own tier. A workspace where no launch config is pinned to a model, or where a pinned config’s Allowed models list has fewer than two models of that tier, has the setting on with nothing for it to do. See Which model your agents run for how pinning and Allowed models work together.

To see what routing has actually saved, or would save if you turned it on, see Model routing in Cost in the web app below.

Billed vs. covered (AI subscription plans)

If your workspace’s agents run on an AI subscription plan, a portion of the model spend is covered by that plan rather than billed directly. When this applies, the CLI adds a second line below the total:

billed:  $0.0210   covered: $0.0211 (subscription)

The web app shows the same split, and adds a turn-count and percentage view — see the bars, summary tiles, and By billing class in Cost in the web app below.

This section only appears when the workspace has active subscription-covered turns. If you do not see it, all recorded spend was billed directly via API usage.

Cost in the web app

The Dashboard has a Cost tile showing your workspace’s 7-day spend as a sparkline. Clicking View breakdown → from that tile opens the Cost breakdown page — it isn’t a separate sidebar entry, so this link is the way in.

Choosing a window

A single Window filter offers Today, Yesterday, Last 7d, and Last 30d. The page defaults to Last 30d — wider than ch costs, which defaults to today (see Checking your costs above). If a number here doesn’t match a ch costs run, check that both are looking at the same window first.

The bars and summary tiles

Once the window has any turns, the page opens with:

The composition bar — Generation against Context overhead (cache-read) (see Reading the token breakdown above).
A Billed / Covered (subscription) bar, shown only when the window has subscription-covered turns.
The date range the window covers, as YYYY-MM-DD → YYYY-MM-DD.
A row of summary tiles: Total spend, Claude turns, Input tokens, and Output tokens always appear; Billed and Covered (subscription) join them when the window has subscription-covered turns; Tasks and Sessions — each a distinct count — join them when the workspace reports those counts.

Reading a rollup table

Every rollup table on the page — by agent template, by model, by workflow stage, by billing class, by task kind — shares one column set: Name, USD, %, Turns, $/turn, $/task, $/session. The USD column carries a bar behind the number, scaled to the largest row in that table, so you can compare rows at a glance. A share that rounds below 0.05% shows as a dash rather than a falsely precise number.

By agent template and by model

Side by side, By agent template — rows link through to the agent’s page — and By model break total spend down along those two dimensions.

By workflow stage

By workflow stage lists spend per pipeline stage, ordered by where each stage falls in the pipeline rather than by spend, so you can follow a task’s cost from plan through code and beyond.

By billing class

By billing class splits spend into the two ways a turn can be paid for: a Subscription (covered) row for turns covered by your plan, and an unclassified (counted as API) row for turns billed directly. If the workspace has no subscription-covered turns, only the unclassified (counted as API) row appears. This table doesn’t appear when there’s no billing-class data to show.

Model routing

When the window has routing data, a Model routing section shows cost-aware routing: what actually ran, against the counterfactual model it would have run on instead, repriced from the current rate card. Two headline figures sit above the table, and which one (or both) you see depends on what’s in the window you’ve selected — not on whether routing is turned on for your workspace right now:

Saved by routing — appears once the window contains turns that actually ran through routing.
Estimated savings if enabled — appears once the window contains turns that ran with routing evaluated but not applied, recorded as a shadow comparison.

A window that spans both shows both figures together. The table itself lists Stage, Model, Mode, Actual, Would-have, Savings, Turns — the Mode column marks each row Live or Shadow, so you can tell which figure a given row is feeding. For what routing does and how to turn it on, see Cost-aware model routing above.

This section doesn’t appear at all until at least one launch config is pinned to a model, and its savings figures stay at $0 until a pinned config’s Allowed models list gives routing more than one model of that tier to compare — see Which model your agents run for setting both up.

Detailed breakdowns

Click Show detailed breakdowns to reveal three more views (the button relabels to Hide detailed breakdowns once expanded):

By task kind — spend by task type, with an Unattributed row for turns that weren’t tied to a task.
Agent template × stage — a heatmap of spend across agent templates and pipeline stages.
Model × stage — the same heatmap, by model instead of agent template.

Each cell shows that pairing’s spend in dollars. Both heatmaps shade each cell relative to the most expensive cell in the grid, leave a cell blank where that pairing had no spend, show turns and cost per turn on hover, and carry a shade legend below the grid running from $0 up to the spend in the most expensive cell.

If the window has no turns at all, the page shows “No cost rows in this window.” instead of the bars and tables above.

Controlling spend

You can control spend two ways: cap it, or reduce it. An agent daily spend cap and a task total spend cap (default) both stop spend before it grows unchecked — see Spend limits for how to set them and what happens when one is reached. Cost-aware model routing (above) takes the other approach, lowering spend on eligible stages instead of stopping it, with no cap to configure.

Plans and limits — your account’s plan, its resource limits, and usage meters
Spend limits — cap per-agent daily and per-task total model spend, or use cost-aware model routing to lower it instead
Which model your agents run — pinning a config to a model and setting up Allowed models so routing has something to choose between
How work flows — stages, gates, and model escalation
Review debt — the review-stage slice of spend, alongside review latency and rework
Monitoring your agents — fleet health and first-pass rate
Why isn’t my task moving? — includes what to do when a spend cap blocks a task