Metadata-Version: 2.5
Name: token-finops-cli
Version: 0.3.0
Summary: Read-only, local-first token usage and budget-runway tracker for AI coding agents (Copilot CLI, Claude Code, Codex CLI, Gemini CLI, Hermes Agent, ...) plus a local-vs-cloud savings estimator
Project-URL: Homepage, https://github.com/tronicum/burn-token-burn
Project-URL: Origin, https://github.com/oh-my-agent-code/token-finops-cli
Project-URL: Issues, https://github.com/tronicum/burn-token-burn/issues
Author: tronicum
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: claude-code,cli,codex,copilot-cli,finops,gemini-cli,github-copilot,hermes-agent,local-llm,token-usage
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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

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

## 60-second tour

```bash
$ 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
```

```bash
$ 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
```

```bash
$ 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
  …
```

```bash
$ 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
```

```bash
$ 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
```

```bash
$ 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
```

```bash
$ 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.

```bash
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):

```bash
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:

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

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

```bash
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.

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

```bash
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`.

| Variable | Overrides | Default |
|---|---|---|
| `TOKEN_FINOPS_COPILOT_DB` | Copilot session-store DB path | `~/.copilot/session-store.db` |
| `TOKEN_FINOPS_DB` | (legacy alias, `sessions`/original CLI) Copilot DB path | `~/.copilot/session-store.db` |
| `CLAUDE_CONFIG_DIR` | Claude Code config root (`self-audit --config-dir` also sets this) | `~/.claude` |
| `CODEX_HOME` | OpenAI Codex CLI home | `~/.codex` |
| `GEMINI_CLI_HOME` | Gemini CLI home | `~/.gemini` |
| `HERMES_HOME` | Hermes Agent home | `~/.hermes` |
| `CLINE_CLI_HOME` | Cline CLI (non-VS Code) home | `~/.cline` |
| `TOKEN_FINOPS_CLINE_DIRS` | Cline/Roo/Kilo VS Code `globalStorage` roots | per-OS VS Code data dir |
| `TOKEN_FINOPS_OPENCODE_DB` | OpenCode/Kilo CLI sqlite DB path | `$XDG_DATA_HOME/opencode/opencode.db` |
| `XDG_DATA_HOME` | Base for the OpenCode DB default above | `~/.local/share` |
| `TOKEN_FINOPS_AIDER_DIRS` | Aider chat-history search roots | `~` |
| `TOKEN_FINOPS_AIDER_ANALYTICS` | Aider opt-in analytics JSONL path | `~/.aider/analytics.jsonl` |
| `CONTINUE_GLOBAL_DIR` | Continue.dev sessions root | `~/.continue` |
| `TOKEN_FINOPS_HARDWARE_JSON` | Override the `savings` hardware-profiles JSON | packaged `hardware_profiles.json` |
| `TOKEN_FINOPS_ENERGY_JSON` | Override the `savings` energy/tariff JSON | packaged `energy.json` |

## 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`](../README.md) — project overview, design rules, related tools
- [`../docs/PLAN.md`](../docs/PLAN.md) — structured plan and status
- [`../docs/ADAPTERS.md`](../docs/ADAPTERS.md) — how to add an adapter
- [`../docs/adr/`](../docs/adr/) — one ADR per coding assistant
- [`../docs/SYNTH.md`](../docs/SYNTH.md) — synthetic telemetry generator
- [`../docs/USECASES.md`](../docs/USECASES.md) — every executable use case
- [`../docs/TMUX.md`](../docs/TMUX.md) — `status --format …` for tmux, starship, waybar, polybar, i3, SwiftBar
- [`../docs/INTEGRATIONS.md`](../docs/INTEGRATIONS.md) — editor / agent-native / desktop integrations (design doc)
- [`../CHANGELOG.md`](../CHANGELOG.md), [`../CONTRIBUTING.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](https://github.com/oh-my-agent-code/token-finops-cli)),
kept verbatim where possible. Everything else in this repository builds on
that foundation.
