Docs

Everything Tokenmeter does is configured in one JSON file and exposed through a small local API.

configuration

Create ~/.tokenmeter/config.json with only the keys you want to change. It is merged over the bundled price list at startup, so upgrades never touch your settings.

{
  "_plans": {"claude": 100, "codex": 20},
  "_budget": {"daily": 30, "monthly": 600},
  "gpt-6-astra": {"input": 10, "cache_read": 1, "cache_write_5m": 0, "cache_write_1h": 0, "output": 50}
}

how cost is calculated

Each model reply reports tokens by type. Tokenmeter multiplies each type by that model's list price and adds them up:

cost = cached reads × read price
     + uncached input × input price
     + cache writes × write price
     + output × output price      (all per million tokens)

The dashboard splits tokens into three columns so the number is legible. Cached is the conversation re-sent from cache each turn, about 2 percent of a fresh token's price on Claude. Fresh is uncached input plus cache writes, context sent for the first time or re-written after a cache miss, and it drives most of the cost. Output is what the model wrote, including thinking. Claude Code writes its cache at the 1-hour rate; OpenAI does not charge for cache writes. Expand any prompt row to see its arithmetic.

These are API list prices. If you are on a subscription you pay the plan price; the dashboard shows that first and this API-equivalent figure below it, so you can see how many times your plan the same usage would have cost.

usage limits

Codex writes its 5-hour and weekly quota usage into every session log, so Tokenmeter shows the real percentages and reset times as of your last Codex turn. Anthropic does not write Claude plan usage to disk; Tokenmeter shows rolling 5-hour and 7-day totals from the logs, and the real percentage when a Claude Code OAuth token is available in the macOS keychain.

team mode

On a shared machine run tokenmeter --host 0.0.0.0 with TOKENMETER_TOKEN set. On each laptop run tokenmeter --export http://that-host:7788 with the same token. The shared dashboard gains a user filter. Only token counts, models, project paths and timestamps travel. Prompt text stays local.

http api