# Cost analytics

> Read local usage records from three agent data sources, estimate spend offline, and configure reporting-only budget alerts.

AgentJail summarizes local usage from Claude Code, Codex, and OpenCode:

```sh
agentjail cost
```

These are the local data sources supported by the cost report, not the full
list of agents AgentJail can shield. Cursor remains supported for sandboxing
and policy enforcement, but it is not a cost-report source.

The report groups estimated spend by project and model. It also shows session
counts, input and output tokens, cache hit rate, average cost per session, and
average tokens per session.

## Choose a period or project

The default period is seven days.

```sh
agentjail cost --period 1d
agentjail cost --period 30d
agentjail cost --period 7d --project ~/work/api
agentjail cost --json
```

| Flag | Default | Description |
|------|---------|-------------|
| `--period <duration>` | `7d` | Reporting window, such as `1d`, `7d`, `30d`, or `24h`. |
| `--project <directory>` | all projects | Limit the report to one project directory. |
| `--json` | off | Print the typed report and budget alerts as JSON. |
| `--db <path>` | `~/.agentjail/agentjail.db` | Read a specific AgentJail SQLite store. |

## How the local index stays current

The daemon maintains the report as a typed index in the existing AgentJail
SQLite store. On the first v1.8.0 start it performs one resumable background
backfill. Later refreshes continue from the last complete JSONL record instead
of rereading retained Claude Code and Codex history.

Maintenance runs after daemon startup and at each next local midnight. The job
records durable catch-up state, so a sleeping laptop catches up when it wakes.
OpenCode remains a separate read-only SQLite source and is folded into the
projection during refresh.

If the first backfill is still running, `agentjail cost` reports that the index
is building. If the last successful refresh is older than 26 hours, it prints
the indexed-through time as a stale warning. The CLI and Cost dashboard never
silently fall back to a multi-gigabyte synchronous scan.

Cost maintenance is informational. A failed refresh does not block policy or
sandbox enforcement.

## Local sources and privacy boundary

The readers use usage records that the supported agent CLIs already store on
your machine. Claude Code data comes from its project JSONL files, Codex data
comes from its session directory, and OpenCode data comes from its local SQLite
database.

AgentJail indexes only:

- session identity
- project and model attribution
- token totals
- recorded or computed cost
- session start time

Prompts, responses, tool inputs, and tool results are not retained in the cost
index. The cost-analysis path does not upload the source records. Model matching
and pricing run locally through the Gryph library bundled into AgentJail. The
OpenCode database is opened read-only, and the transcript readers checkpoint
only complete records. Truncated or replaced files start a new source
generation, while Codex fork ancestry remains available for deduplication.

## How estimates are calculated

When OpenCode has already recorded a non-zero cost, AgentJail uses it. For
token-only sources, AgentJail computes the estimate offline with Gryph's model
matching and pricing catalog bundled into the installed binary.

The result is an estimate, not an invoice. An unknown model may have a zero
computed cost, and an older AgentJail release may contain older pricing. Use the
provider invoice as the billing source of truth.

## Configure budget alerts

Add a `cost` section to `~/.agentjail/policy.yaml`:

```yaml
cost:
  daily_budget: 25
  alert_threshold: 0.8
  project_budgets:
    "~/work/production-api": 10
```

| Key | Default | Description |
|-----|---------|-------------|
| `cost.daily_budget` | `0` | Global daily amount in USD. Zero disables the global alert. |
| `cost.alert_threshold` | `0.8` | Fraction of a configured budget that triggers a warning, from `0` to `1`. |
| `cost.project_budgets` | empty | Daily amounts in USD keyed by project directory. |

At the threshold, the CLI and dashboard show a warning. At 100 percent, they
mark the budget exceeded.

Budget settings are reporting-only. They do not terminate a session, block a
model request, or enter the OPA policy input. Project policy overlays cannot
change the global cost settings.

## Open the Cost dashboard

```sh
agentjail ui
```

Open the **Cost** tab to view the same report for 1, 7, or 30 days. The UI is
served on loopback and uses the same report contract as `agentjail cost`.

## See also

- [CLI reference](/docs/reference/cli): all `agentjail cost` flags and other commands.
- [Configuration](/docs/reference/configuration): the complete `policy.yaml` shape.