Counters
Integration

How many tokens have your agents actually burned?

The number is real, it’s money, and it’s invisible — scattered across laptops, tools and provider dashboards. counters-ai-usage turns it into two counters (ai.tokens.in, ai.tokens.out) that every machine adds to — live, deduplicated, and exact past 253.

Why it works

Token counts are pure adds arriving from many devices at once — the exact write pattern counters.dev is built on. Events spool locally when you’re offline and flush in idempotent batches, so retries never double-count and N machines with one key just merge. Counts only — never prompts, never content.

1

Get the CLI

A single self-contained file, served right here — zero dependencies, Node ≥ 18. (npm package on the way.)

shell
curl -fsSL https://www.counters.dev/counters-ai-usage.mjs -o ~/.local/bin/counters-ai-usage
chmod +x ~/.local/bin/counters-ai-usage   # make sure ~/.local/bin is on your PATH
2

Store your API key

Create a key under Dashboard → API keys, then run init — the prompt keeps it out of your shell history, and the config file is chmod 0600.

shell
counters-ai-usage init
3

Claude Code — one hook

A Stop hook reports each turn’s messages (deduped by message id, cache tokens folded into in). Silent, offline-safe, never slows a session.

~/.claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "counters-ai-usage hook claude-code" }
        ]
      }
    ]
  }
}
4

Everything else — the universal proxy

Codex, OpenCode, Hermes, OpenClaw, aider, raw SDKs: anything that accepts an OpenAI-compatible base URL can point at the local pass-through proxy, which reads usage from responses (streaming included, when include_usage is on).

shell
counters-ai-usage proxy --port 4141 --upstream https://api.openai.com
# then e.g.  OPENAI_BASE_URL=http://localhost:4141/v1 <your tool>

Native per-tool recipes (Codex notify hook, OpenCode plugin) are on the way — the proxy covers those tools today, and counters-ai-usage report is the stable contract for wiring up anything yourself.

5

Watch it tick

Open your dashboard — the counters appear on first write. Sanity-check the pipeline anytime with counters-ai-usage status.

Open dashboardCreate a free org