token-finops-cli 0.2.0__tar.gz → 0.3.0__tar.gz

token_finops_cli-0.3.0/PKG-INFO

@@ -0,0 +1,267 @@
+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.

token_finops_cli-0.3.0/README.md

@@ -0,0 +1,244 @@
+# 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.

token_finops_cli-0.3.0/examples/generate_synthetic_db.py

@@ -0,0 +1,40 @@
+"""Generate a synthetic fake-home tree for demos/tests.
+
+Thin CLI wrapper around `token_finops_cli.synth.generate` -- see that module
+(and `docs/SYNTH.md`) for what gets written per tool and what the scenarios
+mean. Equivalent to `token-finops synth`.
+"""
+import argparse
+
+from token_finops_cli.synth import ALL_TOOLS, generate
+from token_finops_cli.synth.env import env_for
+from token_finops_cli.synth.scenarios import KNOWN as SCENARIOS
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("out", help="Output directory for the synthetic fake-home tree")
+    parser.add_argument("--tools", action="append", default=None,
+                        help=f"comma-separated tool(s) to generate (default: all). known: {', '.join(ALL_TOOLS)}")
+    parser.add_argument("--days", type=int, default=14)
+    parser.add_argument("--scenario", choices=SCENARIOS, default="steady")
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--print-env", action="store_true",
+                        help="also print `export VAR=...` lines")
+    args = parser.parse_args()
+
+    tools = None
+    if args.tools:
+        tools = [t.strip() for chunk in args.tools for t in chunk.split(",") if t.strip()]
+
+    manifest = generate(args.out, tools=tools, days=args.days, scenario=args.scenario, seed=args.seed)
+    for tool, info in manifest.items():
+        print(f"{tool}: {info['events']} events -> {info['path']}")
+    if args.print_env:
+        for var, val in env_for(args.out).items():
+            print(f"export {var}={val}")
+
+
+if __name__ == "__main__":
+    main()

token_finops_cli-0.3.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "token-finops-cli"
+version = "0.3.0"
+description = "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"
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.10"
+authors = [
+    { name = "tronicum" },
+]
+keywords = ["github-copilot", "copilot-cli", "claude-code", "codex", "gemini-cli", "hermes-agent", "finops", "token-usage", "cli", "local-llm"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/tronicum/burn-token-burn"
+Origin = "https://github.com/oh-my-agent-code/token-finops-cli"
+Issues = "https://github.com/tronicum/burn-token-burn/issues"
+
+[project.scripts]
+token-finops = "token_finops_cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/token_finops_cli"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+
+[tool.ruff.lint]
+# pin the rule set explicitly: ruff 0.16 widened its defaults and broke CI
+select = ["E4", "E7", "E9", "F"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

token_finops_cli-0.3.0/src/token_finops_cli/__init__.py

@@ -0,0 +1,7 @@
+"""token-finops-cli: read-only, local-first token usage and budget-runway tracker for
+AI coding agents (Copilot CLI, Claude Code, Codex CLI, Gemini CLI, Hermes Agent, ...)."""
+
+from .cli import main
+
+__version__ = "0.3.0"
+__all__ = ["main"]

token_finops_cli-0.3.0/src/token_finops_cli/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

token_finops_cli-0.3.0/src/token_finops_cli/adapters/__init__.py

@@ -0,0 +1,22 @@
+"""Per-tool adapters. Each adapter is read-only and exposes:
+
+    class XAdapter(BaseAdapter):
+        tool = "x"
+        def available(self) -> bool
+        def scan(self, since=None) -> Iterable[UsageEvent]
+        def quota(self) -> Optional[QuotaSnapshot]
+        def default_policy(self, allowance=None) -> BudgetPolicy
+
+Adapters must never write to the tool's own data store. SQLite sources are
+opened with `immutable=1` (no WAL/lock interaction with the live app).
+"""
+from __future__ import annotations
+
+from .base import BaseAdapter, registry, sqlite_readonly  # noqa: F401
+
+
+def all_adapters() -> list[BaseAdapter]:
+    # Import side effects register the adapters.
+    from . import aider, claude_code, cline, codex, continue_dev, copilot, gemini_cli, hermes, opencode  # noqa: F401
+
+    return [cls() for cls in registry.values()]