Live & Local Monitor for Coding Agents

Real-time token & spend visibility in your terminal.

Track active sessions, subagents, cache efficiency, and API spend across Claude Code, Codex, Gemini CLI, Antigravity CLI, Pi, and OpenCode. 100% local SQLite index. Zero telemetry.

Install Tokenhawk → GitHub Repository ↗

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

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

$gh release download -R polera/tokenhawk Releases ↗

tokenhawk (live session monitor)

LIVE

Tokenhawk dashboard showing session history across Claude, Codex, Gemini, and Pi

TOKENHAWK codex in 11.80M cache 96.6% out 76.4k I:O 154:1 $4.2800 2/4 agents

6 Tools Claude Code, Codex, Gemini, AGY, Pi, OpenCode

100% Local Index kept in local SQLite cache

2s Refresh Real-time local scan without polling APIs

0 Telemetry No accounts, no external tracking

Interactive Interface

One terminal interface. Five purpose-built views.

Switch views inside the interactive TUI with keyboard numbers 1 to 4 or Tab. Inspect real session metrics below.

tokenhawk: [2] Complete Session History

2s scan

[1] Live / [2] History Cross-provider session listing with tokens, I:O ratios, running agents, and cost. Press j/k to move, Enter for detail

tokenhawk: [3] Spend Analysis & Breakdown

UTC trends

Tokenhawk spend analysis showing UTC token and cost trends

[3] Spend UTC-day trends, provider and model breakdowns, rate calculations, and JSON/CSV export. Press t to cycle windows, e to export

tokenhawk: [4] Transcript Search (Literal or regex)

On demand

Tokenhawk transcript search using regular expression across sessions

[4] Search Literal or regex queries across Claude, Codex, Gemini, AGY, Pi, and OpenCode transcripts. Press Ctrl+R for regex, / to edit

tokenhawk: Session Detail & Subagent Accounting

Detailed breakdown

Tokenhawk session detail with subagent breakdown

Detail Breaks out parent and child subagents, token categories, status, and ready-to-run resume command. Press r to reload, Esc to return

tokenhawk: Compact Terminal Layout (80 cols)

Responsive

Tokenhawk compact dashboard in a narrow terminal

Responsive Automatically adapts columns, tables, and headers for half-screen and split panes. Fits narrow tmux panes and sidebars

Prompt Cache Economics

Why cache hits dictate your monthly AI bill.

Modern coding agents replay thousands of lines of context on every turn. Prompt caching discounts cached tokens by up to 90%. When cache breaks, costs multiply rapidly.

Tokenhawk flags sessions with 100,000+ input tokens and < 80% cache hit ratio with an immediate LOW CACHE alert in the dashboard and live status line.

Session Input Tokens: 1.5M tokens

Cache Hit Ratio: 65%

Estimated Session Cost $1.82

Avoidable Cache-Miss Cost $1.30

LOW CACHE WARNING ACTIVE Input >= 100k & Cache < 80%

Built for Developers

Granular telemetry without the overhead.

Built as a zero-dependency Bubble Tea terminal application. Indexes files already on disk.

Multi-Provider Aggregation

Read session logs across Claude Code, Codex, Gemini CLI, Antigravity CLI, Pi, and OpenCode simultaneously.

Index maintained in ~/.cache/tokenhawk

Subagent Hierarchy

Break out parent agent sessions from spawned subagents. Track running status, token consumption, and child costs individually.

Explore / reviewer / coder tree tracking

Low-Cache Alarms

Instant visual warning when cache invalidations cause prompt recomputation on large contexts.

Triggered at >=100k in and <80% cache

Time-Windowed Spend

Analyze spend by day, model, or provider across relative windows like 24h, 7d, 30d, mtd, or custom dates.

UTC daily ledger with public catalog rates

Transcript Search

Instant on-demand literal or regex search across all local transcripts. View chronological message history directly in the TUI.

Read on demand; never written to SQLite index

Headless Export & CLI

Pipe structured JSON or CSV data into reporting scripts, billing pipelines, or CI runs without launching the interactive UI.

tokenhawk export --format json

Supported Ecosystem

Discovery paths & integration points

Tokenhawk reads local storage roots out of the box with zero required provider setup.

Provider	Default Storage Location	Pricing Method	Subagents	Status Integration
Claude Code	`~/.claude/projects/*/.jsonl`	API List Rate / Admin API	Supported	Native statusline hook
Codex	`$CODEX_HOME/sessions/*/.jsonl`	API List Rate	Supported	Universal wrapper / tmux
Gemini CLI	`~/.gemini/tmp//chats/session-.json`	API List Rate	N/A	Universal wrapper / tmux
Antigravity CLI (agy)	`~/.gemini/antigravity-cli/conversations/*.db`	Underlying Model Rate	N/A	Native statusline hook
Pi	`~/.pi/agent/sessions/*/.jsonl`	Provider-Reported	N/A	Universal wrapper / tmux
OpenCode	`~/.local/share/opencode/opencode.db`	Reported / Model Rate	Supported	Universal wrapper / tmux

Live Status Integration

Keep live metrics in your prompt.

Embed Tokenhawk directly in Claude Code, Antigravity CLI, or run any tool with our built-in terminal wrapper.

Configuration Snippet

// ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "tokenhawk statusline claude",
    "refreshInterval": 2,
    "padding": 0
  }
}

// ~/.gemini/antigravity-cli/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "tokenhawk statusline agy",
    "enabled": true,
    "stack_with_default": true
  }
}

# Wraps any tool with live status bar
$ tokenhawk wrap codex
$ tokenhawk wrap gemini --model gemini-2.5-pro
$ tokenhawk wrap opencode /path/to/project
$ tokenhawk wrap --no-tmux codex

# Formats: plain, ansi, tmux, json
$ tokenhawk status --provider codex --project "$PWD"
$ tokenhawk status --provider claude --session SESSION_ID --format json
$ tokenhawk status --provider gemini --project "$PWD" --format ansi

Zero-Trust Privacy

Your code and prompts stay on your machine.

Tokenhawk indexes only session metadata (timestamps, token counts, model names, cost estimates). Prompts, completions, tool call arguments, and credentials are never indexed or transmitted anywhere.

Transcript searches read raw session files into memory strictly on demand during user queries and are never persisted to Tokenhawk's SQLite database.

Read full privacy specification →

Indexed Locally

Session & model identifiers
Input / Cached / Output token counters
Session start & update timestamps
Parent and subagent hierarchy
API catalog rate calculations
Project directory paths

Never Stored

Prompt text and user queries
Model responses and completions
Tool arguments and execution results
API keys or authentication tokens
Telemetry or analytics beacons
Remote cloud sync / accounts

Fast, lightweight, open-source

Start monitoring your agents in seconds.

Install the precompiled binary with one command. Compatible with macOS, Linux, and Windows.

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

Read Documentation → Download Binary ↗