token-finops-cli

Read-only, local-first token usage and budget-runway tracker for AI coding agents. v0.3.0 grew this out of the original 0.2.x line — a single 600-line script that read GitHub Copilot CLI's local telemetry — into a modular tool with 9 adapters (Copilot, Claude Code, Codex CLI, Gemini CLI, Hermes Agent, OpenCode/Kilo, Cline/Roo/Kilo, Aider, Continue.dev), a shared runway engine, a self-audit for Claude Code sessions, and a local-vs-cloud savings estimator. The philosophy hasn't changed: standard library only, no runtime dependencies, and it never writes to any tool's own data store — SQLite is opened read-only/immutable where applicable.

Everything below that talks about the original Copilot budget/cycle/session reports still works exactly as it did in 0.2.x.

Install

uv tool install token-finops-cli          # recommended
pipx install token-finops-cli
pip install token-finops-cli

60-second tour

$ token-finops adapters
  tool         found  root
  copilot      yes    ~/.copilot
  claude_code  yes    ~/.claude
  codex        no     ~/.codex
  gemini_cli   no     ~/.gemini
  hermes       no     ~/.hermes
  opencode     no     ~/.local/share/opencode
  cline        no     ~/.config/Code/User/globalStorage
  aider        no     ~
  continue     no     ~/.continue

$ token-finops report --compact
GitHub Copilot CLI [######--------------]  29.4%  runway  41.2d  OK
Claude Code        [############--------]  61.0%  runway   1.9h  WARN

binding constraint: Claude Code (5h) — runway 1.9h -> WARN

$ token-finops sessions --tool claude_code --since 30d
Claude Code sessions (last 30d):
  session_id      started              calls   tokens   API-eq $
  0bbc8283-…      2026-09-05 09:12     428     73.1M    87.28
  …

$ token-finops self-audit
Self-audit: Claude Code session 0bbc8283-…
  API calls (deduplicated): 428  = main loop 211 + sub-agents 217
  total tokens:     73.1M     (95 % of them cache reads)
  API-equivalent:   $87.28

By model:
  claude-fable-5-1      255 calls   $73.25   84%
  claude-sonnet-5       172 calls   $14.03   16%

Sub-agents = 30 % of API-equivalent cost

$ token-finops savings --hardware mac-studio-m4-max-128gb --model qwen3-32b --utilization 0.2
  local total:       $8.86 / 1M tok    (capex-dominated at 20 % utilisation)
  cloud (sonnet):    $3.20 / 1M tok    -> CLOUD CHEAPER
  break-even utilisation: 60 % of 24/7

$ token-finops break-even --hardware mac-studio-m4-max-128gb
  replaceable cloud usage (haiku/sonnet-class): 35.5M tokens = $14.94 API-equivalent
  local alternative: energy $14.29 + capex $116.87 = $131.15
  -> cloud still cheaper by $116.21; at the current pace the box never pays off

$ token-finops synth --out /tmp/demo-home --print-env && \
  eval "$(token-finops synth --out /tmp/demo-home --print-env)" && \
  token-finops report --compact

runs the whole CLI against a fully synthetic, throwaway fake-home tree — no real telemetry anywhere. See docs/SYNTH.md in the repo root for scenarios (steady, burst, exhausted, weekend, fresh, quiet, subagent-heavy).

GitHub Copilot CLI (the original tool)

token-finops-cli still reads ~/.copilot/session-store.db (assistant_usage_events) directly — no external API calls, nothing leaves your machine, the DB is opened read-only.

token-finops report --tool copilot                  # 7-day summary + runway (default window)
token-finops report --tool copilot --budget 1500 --cycle-day 1   # your plan's monthly AI units
token-finops report --tool copilot --compact        # 2-line minimal output
token-finops report --tool copilot --watch 5        # live-refreshing view every 5s

Session history and break/gap reports (per-session archival view, distinct from the runway report):

token-finops sessions                       # list all past Copilot sessions
token-finops sessions --since 30d --limit 10
token-finops sessions --session <id>                    # detailed break/gap report
token-finops sessions --session <id> --gap-minutes 60
token-finops sessions --totals              # ONE combined report across ALL sessions

The detailed per-session view reports "breaks" — gaps between requests longer than --gap-minutes (default 30) — and active vs. idle wall-clock time. The "AI unit" is GitHub's own cost/usage unit (total_nano_aiu / 1e9) — the same number shown on the Copilot billing page, not raw token counts.

Claude Code: status-line hook

Anthropic subscriptions expose only a percentage of a rolling 5h/7d window, and only through the status line. Wire the collector as your status line command; every redraw stores a snapshot, and two snapshots in the same window are enough for a burn estimate:

// ~/.claude/settings.json
{ "statusLine": { "type": "command", "command": "token-finops collect-statusline" } }

token-finops report --tool claude_code --json

Claude Code — window: 5h (resets 2026-09-05 12:29 UTC)
  budget:   [############------------------]  40.0%
  window:   [############------------------]  40.0% elapsed
  pace:     1.00 (on pace)
  burn:     20.0% per hour (from snapshots)
  runway:   3.0h vs 3.0h left -> OK

Status bars: tmux, starship, waybar, SwiftBar

token-finops status                      # CC 61% 2h! | CX 17% 3h | CP 29% 41d | binds: CC
token-finops status --format tmux        # for status-right (contrib/tmux/token-finops.tmux)
token-finops status --format starship    # binding constraint only
token-finops status --format waybar      # JSON; also polybar, i3, xbar, json

status serves a cache (~/.token-finops/last.json) and rescans only with --fresh or when the cache is older than --max-age seconds. Refresh it from one timer (contrib/refresh/) and let every widget poll freely. Details: ../docs/TMUX.md.

Self-audit

Claude Code writes one line per content block, so naive counting over-reports by roughly 1.9x. self-audit deduplicates on (message.id, requestId), includes sub-agent transcripts, and breaks the bill down by model — the model, not the raw token count, is what decides the cost.

token-finops self-audit                     # latest session
token-finops self-audit --session <id-prefix>
token-finops self-audit --json              # machine-readable, for CI/PR checklists

Local vs. cloud: savings and break-even

token-finops savings --list                          # available hardware/model/tariff keys
token-finops savings --hardware rtx-4090-workstation --model llama-3.3-70b
token-finops savings --power solar-de-feed-in --utilization 0.8
token-finops break-even --since 90d --replaceable-tiers haiku,sonnet

Solar is priced at the feed-in tariff you forgo, not at zero. Capex is amortised per hour of actual inference. Only Haiku/Sonnet-class work counts as replaceable by a local model — a 32B model does not do Opus/Fable-class work. Hardware and energy numbers live in editable JSON (savings/hardware_profiles.json, savings/energy.json) with sources and review dates — measure your own box and overwrite them.

Environment variables

Every adapter reads its data root from an override variable before falling back to the tool's real default location. None of these are required — they exist so you can point the CLI at a different install, a synthetic fixture tree, or a non-default $HOME.

Documentation and design rules

This package is one component of the token-finops repository. For the full guide, the read-only/fractions-not-dollars design rules, the per-assistant Architecture Decision Records, and the 50 executable use cases, see the repository root:

• ../README.md — project overview, design rules, related tools
• ../docs/PLAN.md — structured plan and status
• ../docs/ADAPTERS.md — how to add an adapter
• ../docs/adr/ — one ADR per coding assistant
• ../docs/SYNTH.md — synthetic telemetry generator
• ../docs/USECASES.md — every executable use case
• ../docs/TMUX.md — status --format … for tmux, starship, waybar, polybar, i3, SwiftBar
• ../docs/INTEGRATIONS.md — editor / agent-native / desktop integrations (design doc)
• ../CHANGELOG.md, ../CONTRIBUTING.md

License

AGPL-3.0-or-later.

Credit

The Copilot CLI budget/runway/session-break logic in this package is a direct port of the original token-finops-cli by tronicum (oh-my-agent-code/token-finops-cli), kept verbatim where possible. Everything else in this repository builds on that foundation.