Screens / Approving and controlling

Cost guard

Say what a run is likely to cost before it starts, hold it to a budget, and report what it did cost.

For: Whoever starts runs, and the owner of the budget.

Markdown

3 ways to lay it out

1. Estimate before the run

Pick it when: Runs that can be expensive: the person sees a range and approves a budget first.

An estimate card with a cost range, a time range and a budget field, with Run and Cancel.

Run estimateProCost, time and API calls as ranges, with what each rests on, or an honest "can't estimate".
Cost guardPremiumThe block: estimate from recorded runs, approve a budget, stop at the limit.
Run receiptProAfter the run: what it cost, per model, from the service's own figures.

Install estimate before the run

Pro and Premium items need a licence key; free ones install as they are.

2. Spend dashboard

Pick it when: Owners watch spend across agents, models and features over time.

Three stat cards over a column chart of spend and a breakdown list.

Spend breakdownProAI spend over time, split by model, agent or feature.
Stat cardProOne metric with its change against a named period.
Usage metersProWhat's used against each limit.

Install spend dashboard

Pro and Premium items need a licence key; free ones install as they are.

3. Limit notice in the app

Pick it when: A limit is near or reached and the person needs to know before the next run.

A notice above the composer with a meter and the limit's reason.

Service noticeProA notice about the service itself above the composer: a usage limit, a model that's down.
Usage metersProThe meter behind it.
LockedFreeRun is locked at the limit and says why.

Install limit notice in the app

Pro and Premium items need a licence key; free ones install as they are.

Rules that matter most here

Unknown stays unknown
An estimate from too few recorded runs says it can't estimate; a range is labelled as a range.
A control that can't be used says why
At the limit, Run stays and says which limit it is and when it resets.
Say what can and can't be undone
Stopping a run at its budget says what it had already done.

Already covered elsewhere

Pattern: Agent cost guard: estimates, budgets and spend
Builds the whole screen with an agent route and a store: Cost guard (Premium), with a -claude twin for the Claude Agent SDK.

Brief for a coding agent

Paste this into the agent that builds the screen. The docs MCP server returns the same text from get_screen.

Build a cost guard with Candor UI: say what a run will probably cost before it starts, hold it to a budget, and report what it cost.
Start from the cost-guard block (cost-guard-claude for the Claude Agent SDK) or use RunEstimate and RunReceipt yourself.
Estimate from recorded runs, and as a range. If there are too few to estimate, say "can't estimate"; never show a made-up figure.
The person approves a budget before the run; nothing is pre-filled as approved.
At the limit the run stops and the screen says what it had already done and what it cost, from the service's own figures.
A reached limit locks Run with Locked and says which limit and when it resets.
For spend over time use SpendBreakdown and StatCard; for limits use UsageMeters.
See the agent-cost-guard pattern.

Start from the "Estimate before the run" layout: An estimate card with a cost range, a time range and a budget field, with Run and Cancel.
Candor items: run-estimate (https://candor.themethodic.com/docs/run-estimate.md), cost-guard (https://candor.themethodic.com/docs/cost-guard.md), run-receipt (https://candor.themethodic.com/docs/run-receipt.md).
Install: npx candor-ui add run-estimate cost-guard run-receipt
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.