TokenCat

TokenCat is a local-first CLI that shows how your AI coding agents use tokens across one machine, and optionally across trusted machines on your LAN.

Run tokencat to get a terminal dashboard for Codex, Claude Code, Gemini CLI, Antigravity, OpenCode, GitHub Copilot Chat/Agent, and GitHub Copilot CLI. TokenCat reads the telemetry files those tools already keep locally; it does not proxy requests, rewrite endpoints, read credentials, or print prompt and response bodies.

Why TokenCat

• One dashboard for several coding agents: Codex, Claude Code, Gemini CLI, Antigravity, OpenCode, VS Code Copilot Chat/Agent, and Copilot CLI.
• Zero-provider setup for normal use: install it and run tokencat.
• Privacy-first scanning: local files only, anonymous session IDs by default, no OAuth/session token reporting.
• Cost estimates with clear coverage: bundled pricing works offline, and unknown models stay visible instead of being guessed.
• Useful terminal views: dashboard, sessions, models, daily usage, doctor, pricing, and JSON output for scripts.
• Multi-machine rollups: trusted TokenCat nodes can be aggregated with --lan, including SSH snapshot hosts from ~/.ssh/config.

Install

TokenCat requires Python 3.9 or newer.

pipx install tokencat

Upgrade later with:

pipx upgrade tokencat

Optional mDNS discovery and advertising for HTTP LAN nodes requires the mdns extra:

pipx install "tokencat[mdns]"

To try a checkout of this repository:

pipx install .

With mDNS support from a checkout:

pipx install ".[mdns]"

Quick Start

Open the default 7-day dashboard:

tokencat

Look farther back:

tokencat --since 30d
tokencat --since 2026-01-01

Check what TokenCat can see on this machine:

tokencat doctor

LAN and SSH Nodes

TokenCat can roll up trusted machines without sending prompts or responses. Each node exposes or returns a read-only snapshot.

SSH-configured machines and containers are the recommended path and do not need a long-running HTTP server or mDNS. If a host appears in ~/.ssh/config and has tokencat available remotely, tokencat nodes --trust can add it as an SSH snapshot node. Later, tokencat --lan runs ssh <host> tokencat snapshot --json and aggregates the returned snapshot.

Aggregate trusted nodes:

tokencat dashboard --lan
tokencat summary --lan
tokencat sessions --lan

Remove trusted nodes:

tokencat nodes --remove

You can also start an HTTP node on another machine. Install tokencat[mdns] when you want the node to advertise itself over mDNS:

export TOKENCAT_NODE_TOKEN="choose-a-shared-secret"
tokencat serve --lan

tokencat serve starts in the background by default:

tokencat serve --status
tokencat serve --logs
tokencat serve --stop

For foreground debugging:

tokencat serve --lan --foreground

Discover and trust nodes:

tokencat nodes --trust

Without the mdns extra, tokencat nodes --trust still lists SSH candidates from ~/.ssh/config; it only skips automatic mDNS discovery.

If mDNS is blocked by Docker Desktop, VPNs, or network policy, trust a node by URL:

tokencat nodes --url http://127.0.0.1:8765 --trust

Advanced Usage

Focus on one provider:

tokencat dashboard --provider codex
tokencat sessions --provider claude --limit 20
tokencat models --provider gemini
tokencat daily --provider copilot
tokencat sessions --provider opencode

Change the terminal theme:

tokencat --theme light
tokencat dashboard --theme dark

Use structured output:

tokencat summary --json
tokencat sessions --json --show-title --show-path

JSON Output

Commands with --json emit stable envelopes with:

• generated_at
• filters
• providers
• summary or items
• warnings

This makes TokenCat easy to pipe into local scripts, dashboards, or personal automation.

Configuration

Most users do not need a config file. TokenCat discovers local agent data from the standard locations for each tool.

Common environment variables:

Local TokenCat state is kept under ~/.tokencat/:

• ~/.tokencat/pricing/ stores the refreshed pricing cache.
• ~/.tokencat/node.json stores this machine's node identity.
• ~/.tokencat/nodes/trust.json stores trusted LAN or SSH nodes.
• ~/.tokencat/logs/node.log and ~/.tokencat/node.pid are used by the detached node server.

Commands

Useful flags:

--provider codex|claude|gemini|antigravity|copilot|opencode
--since 7d
--until 2026-05-31
--daily | --weekly | --monthly    # dashboard usage buckets
--theme auto|dark|light
--json
--no-price
--lan

Session listings also support:

--limit 50
--model gpt-5-codex
--show-title
--show-path

Pricing

TokenCat estimates API-equivalent cost when a model can be matched to known pricing data.

• Pricing works offline with the bundled catalog shipped in the package.
• On first pricing use, TokenCat silently tries to refresh a local cache under ~/.tokencat/pricing/.
• If the refresh fails, it quietly falls back to the bundled catalog.
• tokencat pricing refresh refreshes the local cache manually.
• Resolution is source-aware: direct source pricing first, then official API pricing for the model family, then OpenRouter as the marketplace fallback.
• The internal codex-auto-review label is estimated using gpt-5.4-mini pricing because OpenAI does not publish a direct model mapping for that label.
• JSON output includes pricing_source and pricing_model when a row is priced.
• Unknown, renamed, redirected, or unattributed models remain visible with explicit pricing status.

Current pricing references:

• OpenAI API pricing
• OpenAI Codex pricing
• Gemini API pricing
• Anthropic models and pricing
• xAI models
• OpenRouter pricing
• GitHub Copilot plans

Privacy

TokenCat is intentionally conservative.

• Reads local telemetry files only.
• Does not proxy, intercept, or replay model requests.
• Does not rewrite provider endpoints.
• Does not read OAuth/session credentials for reporting.
• Does not print raw prompt or response bodies.
• Uses anonymous session IDs by default.
• Shows titles and paths only when you pass --show-title or --show-path.

Limits

• TokenCat supports macOS and Linux, including typical Docker/containerized Linux environments where the relevant agent state is mounted or available locally.
• Windows is not yet supported.
• SSH LAN rollups work in the base install. mDNS discovery and advertising for HTTP LAN nodes requires tokencat[mdns].
• mDNS can be unreliable through Docker Desktop, VPNs, or restrictive networks. Use tokencat nodes --url ... --trust or SSH nodes in those environments.
• Copilot CLI usage is counted from shutdown summaries; active CLI sessions without shutdown summaries are detected but not counted yet.
• Cost is an estimate, not your actual bill.

License

TokenCat is licensed under GNU GPLv3. See LICENSE.