Know what your
agents consume.

Quick start

Install the latest compiled release on macOS or Linux:

$ /bin/sh -c "$(curl -fsSL https://tokenhawk.dev/install.sh)"
$ tokenhawk

The installer detects your operating system and architecture, verifies the release checksum, and installs to ~/.local/bin. If needed, add that directory to your PATH.

Choose a version or install directory

$ TOKENHAWK_VERSION=0.4.4 sh -c "$(curl -fsSL https://tokenhawk.dev/install.sh)"
$ TOKENHAWK_INSTALL_DIR="$HOME/bin" sh -c "$(curl -fsSL https://tokenhawk.dev/install.sh)"

Install with Go

If you already have Go 1.26 or newer, you can install Tokenhawk directly from the module root:

$ go install github.com/polera/tokenhawk@latest

If the command is not found afterward, add $(go env GOPATH)/bin to your PATH.

Build from source

Building from source requires Go 1.26 or newer.

$ git clone https://github.com/polera/tokenhawk.git
$ cd tokenhawk
$ go build -o tokenhawk .
$ ./tokenhawk

Run Tokenhawk in a dedicated terminal tab or window. Missing provider directories are allowed, so there is no setup required for tools you do not use.

Keep Tokenhawk current

When the interactive dashboard starts in a terminal, Tokenhawk checks GitHub Releases at most once every 24 hours. If a newer release is available, you can install it immediately or defer the prompt for 24 hours. Run the upgrade directly at any time:

$ tokenhawk upgrade

The upgrade downloads the archive for your operating system and architecture, verifies its SHA-256 checksum against the release manifest, and replaces the current executable. After accepting an upgrade from the startup prompt, restart Tokenhawk to continue.

Privacy model

Tokenhawk’s session monitoring operates entirely on your machine. It reads provider session metadata from normal local stores and writes a rebuildable SQLite index beneath your operating system’s user-cache directory.

Provider transcript files remain untouched. OpenCode’s SQLite database is opened read-only, including its live WAL data. AGY account and quota fields are ignored. Source paths are omitted from exports unless you explicitly pass --include-source.

Dashboard

The dashboard separates active, inactive, and all sessions, with a fourth view for spend across a time window and a fifth for Anthropic billing reconciliation. At medium and wide terminal sizes each session row shows provider, project/session, agent counts, model, input, cached input, output, normalized input-to-output ratio, reasoning tokens, total tokens, cost, and update time.

Keyboard controls

Low-cache warning

A session is highlighted when it has at least 100,000 input tokens and less than an 80% cached-input ratio. Detail view identifies low-cache parent and subagent workloads independently.

Spend reporting

Press 4 to aggregate tokens and cost over a time window. The view shows totals and input-to-output ratios, then breaks the same sessions down by provider, model, and the 14 most recent UTC days. Estimated model rows show the uncached input, cached input, cache-write, and output quantities alongside the effective catalog rates used to calculate their cost. If the window contains older days, the view reports how many are omitted. Provider and search filters also narrow this view; e and x export exactly the sessions it covers.

If a reporting window crosses a price change, Tokenhawk shows a separate calculation for each effective rate period. Claude’s five-minute and one-hour cache writes are priced separately, and Gemini reasoning tokens are included in its billed output quantity.

Press t to cycle through the last 24 hours, last 7 days, last 30 days, month to date, and all time. Press d to enter a custom window, or launch Tokenhawk directly into one:

$ tokenhawk --since 30d
$ tokenhawk --since 2026-07-01

Accepted time windows

Windows accept RFC 3339 timestamps, YYYY-MM-DD dates, relative offsets such as 90m, 24h, 7d, 2w, 3mo, and 1y, compound Go durations such as 1h30m, and the keywords today, yesterday, wtd, mtd, ytd, and all. Relative windows continue rolling while Tokenhawk is open.

Billing reconciliation

Organization administrators can set an Anthropic Admin API key to import authoritative Claude billing from the Usage and Cost Admin API and compare it with Tokenhawk’s local list-price estimates:

$ export ANTHROPIC_ADMIN_KEY='sk-ant-admin...'
$ tokenhawk

The first interactive run imports 31 UTC days by default. While Tokenhawk remains open, it refreshes the current and previous UTC day every five minutes. Press 5 to compare estimated and billed cost by exact model and UTC day, including the dollar residual and percentage drift.

In the Spend view, a successfully covered UTC day uses the imported Anthropic cost and suppresses the overlapping local Claude estimate. Reported and estimated dollars remain visibly separate when both occur in the window.

Coverage and limits

The Admin API is available to organization administrators, not individual accounts. Pro and Max subscription use has no authoritative per-model billed spend to import. Priority Tier charges and usage routed through Bedrock, Vertex, Foundry, or Claude Platform on AWS are not reported by this endpoint and remain estimates unless their billing provider is integrated separately.

Provider data

By default, Tokenhawk discovers usage data in these locations:

Use the corresponding directory flags or the configuration file to point Tokenhawk at nonstandard roots. Run with --rebuild after changing source locations.

Live status inside agent sessions

The compact renderer always selects one session; it never combines usage from multiple sessions. Claude and AGY native hooks supply exact session identifiers. Wrappers select the active, most recently updated session for the current project directory.

Claude Code status line

Add this to ~/.claude/settings.json, merging it with any existing settings:

{
  "statusLine": {
    "type": "command",
    "command": "tokenhawk statusline claude",
    "refreshInterval": 2,
    "padding": 0
  }
}

The command consumes Claude’s status JSON from standard input and does not add anything to model context.

Antigravity CLI status line

Add this to ~/.gemini/antigravity-cli/settings.json, merging it with any existing settings:

{
  "statusLine": {
    "type": "command",
    "command": "tokenhawk statusline agy",
    "enabled": true,
    "stack_with_default": true
  }
}

AGY supplies the conversation ID, workspace, active model, and cumulative input and output. Tokenhawk stores that usage snapshot and renders it inside AGY. Because AGY exposes cumulative input and output but only current cache counters, cached input is recorded as the best available lower bound. Existing conversations are discovered, but show no token totals until resumed after the status line is configured.

Universal tmux wrapper

The universal wrapper requires tmux. Outside tmux it creates a temporary dedicated session. Inside tmux it temporarily replaces the right-side status and restores the previous settings when the client exits.

$ tokenhawk wrap codex --cd /path/to/project
$ tokenhawk wrap gemini --model gemini-2.5-pro
$ tokenhawk wrap agy --conversation SESSION_ID
$ tokenhawk wrap pi --model anthropic/claude-sonnet-4-5
$ tokenhawk wrap opencode /path/to/project

All remaining arguments are forwarded unchanged to the selected client. You can also use tokenhawk wrap claude if you prefer the universal wrapper.

Direct renderer

$ tokenhawk status --provider codex --project "$PWD"
$ tokenhawk status --provider claude --session SESSION_ID --format json
$ tokenhawk status --provider gemini --project "$PWD" --format ansi

The renderer incrementally scans provider stores by default. Add --no-scan when another Tokenhawk process already maintains the index. Set NO_COLOR=1 to turn ANSI output into plain text.

Headless export

Export all matching sessions without opening the TUI:

$ tokenhawk export --format json --output usage.json
$ tokenhawk export --format csv --output usage.csv \
    --provider codex --since 2026-07-01
$ tokenhawk export --format csv --output month.csv --since mtd

Filters include --provider, --model, --project, --status, --since, and --until. Both time bounds accept the forms listed under spend reporting. A bare YYYY-MM-DD used with --until includes that entire day.

• JSON contains nested per-model and subagent usage.
• CSV contains tagged session/model and subagent/model rows, including total and one-hour cache-write counts, cost, and running status.
• Local source paths stay excluded unless --include-source is set.

Configuration

Tokenhawk loads tokenhawk/config.toml beneath your operating system’s user-config directory. Every field is optional and command-line flags take precedence.

claude_dir = "~/.claude/projects"
codex_dir = "~/.codex"
gemini_dir = "~/.gemini/tmp"
agy_dir = "~/.gemini/antigravity-cli"
pi_dir = "~/.pi/agent/sessions"
opencode_db = "~/.local/share/opencode/opencode.db"
active_window = "5m"
refresh = "2s"
db_path = "~/.cache/tokenhawk/index.db"
pricing_file = "~/.config/tokenhawk/pricing.json"
anthropic_cost_lookback_days = 31
include_source = false

Pricing

Claude, Codex, Gemini, and recognized models used through AGY are estimates of public API list-price equivalents, not subscription charges, invoices, free-tier consumption, discounts, credits, or taxes. AGY labels are normalized before exact lookup and use the underlying Gemini or Claude catalog rate. Pi and OpenCode record calculated costs themselves; Tokenhawk labels those values reported and preserves them.

The bundled, effective-dated catalog prices only exact, known model IDs. The spend view identifies the rate and effective date behind each estimated model cost, while unknown models remain unpriced instead of inheriting a guessed family rate. Anthropic Admin API billing, when configured, is also labeled reported.

Override a rate

{
  "version": "company-rates-1",
  "rates": [{
    "provider": "codex",
    "model": "my-exact-model-id",
    "effective_from": "2026-01-01",
    "input_per_million": 1.0,
    "cached_input_per_million": 0.1,
    "cache_creation_per_million": 1.0,
    "cache_creation_1h_per_million": 2.0,
    "output_per_million": 8.0
  }]
}

Commands & flags

Shared selection and storage flags

Troubleshooting