# Run costs

The panel can show **what each run actually cost** — tokens in/out and an
approximate dollar amount — right next to the run, so you can answer *"how much
did last night's run cost?"* and *"which repos burn the most?"* without leaving
the dashboard.

## Where you see it

- **Run list** — a compact `~$0.42` chip on each row that has cost data.
- **Run drawer** — a **Cost** line with the full summary, e.g.
  `~$0.42 · 20k in · 2.8k out · 2 models`.

Amounts are prefixed with `~` because they're **best-effort estimates**, not an
invoice. Sub‑dollar runs show four decimals (`~$0.0594`); larger ones round to
cents. Token counts are abbreviated (`980`, `15k`, `2.4M`).

## How it's measured

Cost capture runs entirely on your [worker](/docs/add-worker) via
[tokscale](https://github.com/just-every/tokscale) — a tool that reads the local
usage data your AI harness already writes (Claude Code, OpenCode, Codex, etc.).

For each run, the worker snapshots cumulative usage at **start** and at **end**
and reports the **difference** — that delta is the run's token/cost, sent to the
panel and stored on the run. Nothing is estimated from prompt text; it's the
harness's own accounting.

> **BYOK-safe.** tokscale reads token *usage* counters only. It never reads,
> logs, or transmits your provider keys — consistent with
> [BYOK](/docs/byok-provider-keys). Cost data is the only thing that leaves the
> worker.

## Enable it on a worker

Cost capture is **opt‑in per worker** and fully optional — a worker without
tokscale runs exactly as before, just with no cost line. To turn it on, install
tokscale on the worker host so it's on the worker's `PATH`:

```bash
# install (Bun) — any install that puts `tokscale` on PATH works
bun add -g tokscale

# confirm the worker can see it
tokscale --version
```

The next run on that worker will start reporting cost. No panel setting and no
worker restart are required — the worker detects tokscale at run time.

## Caveats

- **No tokscale → no cost.** Runs are unaffected; the Cost line is simply hidden.
- **Concurrent runs share the delta.** Because tokscale usage is machine‑global,
  two runs executing at the same time on one worker each over‑count by the
  other's usage. AM's per‑repo runs are typically sequential, so this is close
  enough — and it's advisory, never used to block or bill.
- **Estimate, not billing.** Your provider's actual charge can differ (negotiated
  rates, volume discounts). Treat the figure as a relative signal.

## Aggregate & export — the Cost tab

Per‑run cost is useful, but to answer *"what did AM cost us this month?"* or
*"which repo (or which profile) burns the most?"*, open the **Cost** tab.

- **Date range** — Today / 7d / 30d / 90d, or a custom from/to.
- **Summary** — total cost, run count, and average cost per run for the range.
- **By repository** and **by [profile preset](/docs/profile-presets)** — so a team
  can see, e.g., how much the `unit-tests` profile cost on a given repo.
- **By model** — a simple bar breakdown of spend per model.
- **Export CSV** — one row per run (`run_id, repo, started_at, status, cost_usd,
  preset, model`) to reconcile against your provider bill.

Behind it: `GET /api/runs/cost-summary` and `GET /api/runs/cost-export` (CSV or
`?format=json`), both accepting `from` / `to` / `repo_id`.

**Plan limits:** Free sees the **last 7 days**; Pro and up get the full **90‑day**
history and CSV export. Runs without cost data (no `tokscale` on the worker)
count toward run totals but add `$0`.

## Related

- [Reading a run](/docs/reading-runs) · [Add a worker](/docs/add-worker)
- [BYOK provider keys](/docs/byok-provider-keys) · [Plans & limits](/docs/plans-and-limits)