The hardest part of running multiple AI coding agents isn’t usually picking the right one. It’s getting a clear answer to “what did this cost?” when the answer lives across three accounts and four invoices.

Ringlet’s cost tracking exists to make that answer easy. Here’s how it works and how to use it.

How the data gets collected

Every modern model provider streams a usage block inline with the response. Anthropic sends input_tokens and output_tokens as part of the streamed event sequence. OpenAI sends usage in the final chunk of a Chat Completions stream. MiniMax follows the OpenAI shape. Groq does too.

Ringlet parses those events as they fly past — same data the agent sees. For each completed turn it writes a row to ~/.ringlet/profiles/<name>/usage.db:

id, timestamp, profile, agent, provider, model, input_tokens, output_tokens, cost_usd

cost_usd is computed from a price table baked into the Ringlet binary and refreshed each release. If a price changes mid-month and you want exact-to-the-cent reconciliation, use the provider’s invoice; Ringlet’s ledger is a real-time signal, not a billing system of record.

Querying spend

The simplest view: ringlet usage.

$ ringlet usage

PROFILE        AGENT       PROVIDER     TOKENS         COST
work           claude      anthropic    1.21M / 340K   $8.41
personal       claude      minimax      2.83M / 820K   $0.92
client-acme    claude      anthropic    480K / 130K    $3.20
staging        codex       openai       450K / 90K     $1.40
side-project   grok        openai       2.1M / 510K    $1.05
────────────────────────────────────────────────────────────
TOTAL                                                  $14.98

Filter by profile, date range, or model:

ringlet usage --profile work --since 2026-05-01
ringlet usage --provider anthropic --since 2026-05-01 --until 2026-05-31
ringlet usage --model claude-sonnet-4-5 --by-day

The --by-day view is the one engineering managers ask for:

$ ringlet usage --profile work --by-day --since 2026-05-01

DATE          TOKENS       COST
2026-05-01    140K / 38K   $1.02
2026-05-02    220K / 55K   $1.61
2026-05-03      0 / 0      $0.00   ← weekend
2026-05-06    310K / 72K   $2.18
...

Export for billing reconciliation

CSV export feeds straight into spreadsheets:

ringlet usage --export csv > may-2026.csv
ringlet usage --export csv --profile work --since 2026-05-01 > may-work.csv

JSON for programmatic consumption:

ringlet usage --export json | jq '[.[] | select(.provider == "anthropic")] | add'

Importing existing logs

If you’ve been running Claude Code without Ringlet, you already have ~/.claude/usage.jsonl. ringlet import reads it and attributes the events to a profile of your choice:

ringlet import claude --to work
# ✓ Read 18,432 events from ~/.claude/usage.jsonl
# ✓ Attributed to profile 'work'
# ✓ Cost reconstructed: $241.83 (Mar 1 → May 12)

Same for Codex (~/.codex/sessions/) and OpenCode. The import is idempotent — running it twice doesn’t double-count.

Setting cost alerts

The cost-threshold hook fires when a profile crosses a daily or monthly threshold:

# Daily $10 limit on the work profile
ringlet hooks add work --on cost-threshold \
  --period day --threshold 10 \
  --webhook 'https://hooks.slack.com/services/...'

# Monthly $200 budget warning at 80%
ringlet hooks add work --on cost-threshold \
  --period month --threshold 160 --of 200 \
  --shell 'osascript -e "display notification ..."'

These run on the daemon side, so you don’t need to keep a polling script alive.

What gets counted, what doesn’t

Counted:

  • Successful streaming responses, regardless of whether the agent kept the result.
  • Tool-call cycles (an agent making a tool call and then continuing the turn produces multiple LLM round trips; each one is counted).
  • Failed responses where the provider still streamed a usage block before erroring.

Not counted:

  • Requests that errored before the provider sent usage info (rare; network failures, 4xx auth errors).
  • Embeddings, image generation, audio — Ringlet today tracks chat completions. Embeddings via the agent’s tools will be counted when that wire format stabilises.
  • Local-only model usage (e.g. running Ollama via a tool). The provider doesn’t have a price; Ringlet records the call but not a dollar value.

How accurate is it, really?

Compared to provider invoices, Ringlet’s totals are typically within 1–2% of the billed amount. Sources of drift:

  1. Mid-month price changes. Ringlet’s price table only updates with a release.
  2. Cached input pricing. Anthropic’s prompt-caching discount is reported in a separate event field; Ringlet handles this for Claude but if the provider adds new caching tiers between releases, drift increases.
  3. Per-minute rate adjustments on hosted gateways (rare on Anthropic/OpenAI, common on smaller providers).

For “what’s the engineering team spending” answers, ±2% is plenty. For “exactly bill this customer,” reconcile against the invoice.

What you do with it

A few patterns we’ve seen teams settle into:

  • Per-client profiles. Each customer engagement gets its own profile. CSV export feeds the invoice.
  • Cost-aware agent selection. Lower-stakes work goes through a MiniMax-backed profile; high-stakes through Anthropic-direct. The ringlet usage report shows the ratio in real time.
  • Daily Slack rollups. A scheduled hook posts yesterday’s spend to a #dev-spend channel. People notice anomalies the day they happen.
  • PR-blocking budget guards. A pre-tool-use hook checks the current month’s spend against a budget and denies tool calls past the threshold. Brutal but effective for runaway-loop bugs.

Try it

The ringlet usage command works the moment you run a profile through Ringlet. There’s nothing to enable. If you’ve used Claude Code before, ringlet import claude gives you a backfill of history so the graph isn’t empty on day one.

Install takes a minute. The first thing most people do after installing is run ringlet usage and find out where their month actually goes.