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.6.0 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 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 user-cache directory.

Provider transcript files remain untouched. Search and session detail read current and previous user/assistant text directly from supported provider stores on demand, excluding tool traffic and reasoning, and never persist it to Tokenhawk index. A detail export includes the conversation you explicitly loaded; bulk and headless exports remain metadata-only. OpenCode 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 has four persistent views: live sessions, complete session history, spend analysis across a time window, and transcript search. Session rows adapt to terminal width: compact layouts retain core totals and ratios, while wide layouts add model, token-category, reasoning, cost, agent, and update details.

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 3 to aggregate tokens and cost over a time window. The view shows totals and input-to-output ratios, graphs token usage and cost over UTC time, then breaks the same sessions down by provider, model, and the 14 most recent UTC days. API-priced 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 narrow both the view and its exports.

If a reporting window crosses a price change, Tokenhawk shows a separate calculation for each effective rate period. Claude 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.

Press e or x here to export the displayed totals and provider, model, and day breakdowns instead of raw session rows. Spend exports also include one token-and-cost time-series point per UTC day, including zero-value days.

Anthropic-reported spend

Organization administrators can set an Anthropic Admin API key to import authoritative Claude billing from the Usage and Cost Admin API:

$ 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. In Spend, a successfully covered UTC day uses imported Anthropic cost and suppresses the overlapping local Claude API-rate cost. Reported and API-rate dollars remain visibly separate when both occur in the window.

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 API-rate costs unless their billing provider is integrated separately.

Transcript search and review

Press 4 to search current and previous user/assistant messages with a case-insensitive literal query. Tokenhawk keeps the newest matching hit from each session, then lists those sessions newest first with the provider, project, time, role, and a short snippet. Select a result and press Enter to open the session complete chronological conversation beneath its usage detail.

Run the same search without opening the TUI:

$ tokenhawk search "database migration"
$ tokenhawk search --provider codex --project "$PWD" --since 30d "SQLite"
$ tokenhawk search --role user --session SESSION_ID --format json "cache invalidation"
$ tokenhawk search --regex 'migration \d+_\w+'

Search flags must precede the query. Use --until, --limit, or --case-sensitive to narrow the matching session set, or --regex to treat the query as a Go regular expression. In the TUI, press Ctrl+R to toggle literal and regular-expression matching.

Claude, Codex (including archived sessions), Gemini, Antigravity CLI, Pi, and OpenCode transcripts are read directly each time. Tool calls, tool results, reasoning blocks, and other non-message payloads are excluded. Tokenhawk decodes only user input and assistant prose from protobuf conversation payloads in AGY SQLite files, leaving reasoning summaries, tool invocations, and other fields opaque.

Inside session detail, use arrows or page keys to scroll, / to find text, n/N to move between matches, and r to reload. A detail export includes the complete loaded conversation with role, timestamp, subagent ID, and text.

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 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 wrapper

The universal wrapper prefers tmux when it is available. 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
$ tokenhawk wrap --no-tmux codex

Without tmux, or with --no-tmux, Tokenhawk runs the client in a built-in pseudo-terminal that reserves the bottom row for the same live status line on macOS and Linux. This mode requires an interactive terminal at least four rows tall. Windows continues to require tmux. Place --no-tmux before the provider name; all arguments after the provider 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 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 priced at public API list rates. These API-rate costs are 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 nonzero costs recorded by OpenCode are labeled reported and preserved. When OpenCode records zero cost for a recognized OpenAI, Anthropic, or Google model, Tokenhawk applies the underlying model public API list rate.

The bundled, effective-dated catalog prices only exact, known model IDs. The spend view identifies the rate and effective date behind each API-priced 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