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.1.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.25 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.25 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.

Privacy model

Tokenhawk 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. Source paths are omitted from exports unless you explicitly pass --include-source.

Dashboard

The dashboard separates active, inactive, and all sessions. At medium and wide terminal sizes each 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.

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 supplies an exact session ID. Wrappers for other clients 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.

Codex, Gemini CLI, Pi, and OpenCode

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

Filters include --provider, --model, --project, --status, --since, and --until. Dates accept RFC 3339 or YYYY-MM-DD.

• JSON contains nested per-model and subagent usage.
• CSV contains tagged session/model and subagent/model rows, including 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"
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"
include_source = false

Pricing

Claude, Codex, and Gemini costs are estimates of public API list-price equivalents, not subscription charges, invoices, free-tier consumption, discounts, or taxes. 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. Unknown models remain unpriced instead of inheriting a guessed family rate.

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,
    "output_per_million": 8.0
  }]
}

Commands & flags

Shared selection and storage flags

Troubleshooting