Cost analytics · agentjail

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

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.

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:

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

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.