# 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.

Web page: https://candor.themethodic.com/screens/cost-guard

## Layouts

### Estimate before the run

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

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

Items:

- **Run estimate** (`run-estimate`, Pro; https://candor.themethodic.com/docs/run-estimate.md): Cost, time and API calls as ranges, with what each rests on, or an honest "can't estimate".
- **Cost guard** (`cost-guard`, Premium; https://candor.themethodic.com/docs/cost-guard.md): The block: estimate from recorded runs, approve a budget, stop at the limit.
- **Run receipt** (`run-receipt`, Pro; https://candor.themethodic.com/docs/run-receipt.md): After the run: what it cost, per model, from the service's own figures.

```bash
npx candor-ui add run-estimate cost-guard run-receipt
```

### Spend dashboard

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

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

Items:

- **Spend breakdown** (`spend-breakdown`, Pro; https://candor.themethodic.com/docs/spend-breakdown.md): AI spend over time, split by model, agent or feature.
- **Stat card** (`stat-card`, Pro; https://candor.themethodic.com/docs/stat-card.md): One metric with its change against a named period.
- **Usage meters** (`usage-meters`, Pro; https://candor.themethodic.com/docs/usage-meters.md): What's used against each limit.

```bash
npx candor-ui add spend-breakdown stat-card usage-meters
```

### Limit notice in the app

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

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

Items:

- **Service notice** (`service-notice`, Pro; https://candor.themethodic.com/docs/service-notice.md): A notice about the service itself above the composer: a usage limit, a model that's down.
- **Usage meters** (`usage-meters`, Pro; https://candor.themethodic.com/docs/usage-meters.md): The meter behind it.
- **Locked** (`locked`, free; https://candor.themethodic.com/docs/locked.md): Run is locked at the limit and says why.

```bash
npx candor-ui add service-notice usage-meters locked
```

## Rules that matter most here

- **Unknown stays unknown** (https://candor.themethodic.com/principles#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** (https://candor.themethodic.com/principles#locked-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** (https://candor.themethodic.com/principles#say-what-can-be-undone): Stopping a run at its budget says what it had already done.

## Patterns that cover part of it

- Agent cost guard: estimates, budgets and spend: https://candor.themethodic.com/patterns/agent-cost-guard.md

A full-stack block builds this with an agent route and a store: `cost-guard` (https://candor.themethodic.com/docs/cost-guard.md). Each block has a `-claude` twin for the Claude Agent SDK.

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
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.
```