Metadata-Version: 2.4
Name: token-finops-cli
Version: 0.1.0
Summary: Read-only CLI to monitor GitHub Copilot CLI token usage and estimate a monthly budget runway
Project-URL: Homepage, https://github.com/oh-my-agent-code/token-finops-cli
Project-URL: Issues, https://github.com/oh-my-agent-code/token-finops-cli/issues
Author: tronicum
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: cli,copilot-cli,finops,github-copilot,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.9
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

A small, read-only CLI to keep an eye on your **GitHub Copilot CLI** token
usage and estimate a "runway" — how many days your monthly AI-unit budget
will last at your current burn rate.

It reads directly from the Copilot CLI's own local telemetry database
(`~/.copilot/session-store.db`, table `assistant_usage_events`) — no
external API calls, no scraping, nothing leaves your machine. The database
is opened in immutable/read-only mode so it can never interfere with a
live Copilot CLI session.

## Why

GitHub's Copilot usage-metrics REST API is enterprise-admin-only (requires
`manage_billing:copilot` / `read:enterprise` scopes) — there's no
individual-seat endpoint to query your own quota. This tool works around
that by reading the CLI's own local usage log and letting you supply your
own monthly budget number (from the Copilot billing page) so it can project
a runway estimate.

## Install

With [uv](https://docs.astral.sh/uv/) (recommended):

```bash
uv tool install token-finops-cli
token-finops --since 7d
```

Or from source, editable, in a venv:

```bash
uv venv
uv pip install -e ".[dev]"
.venv/bin/token-finops --since 7d
```

Or plain pip:

```bash
pip install token-finops-cli
```

## Usage

```bash
token-finops                      # full report, last 7 days
token-finops --since 30d          # last 30 days
token-finops --since all          # all-time
token-finops --session <id>       # filter to one session

# Budget / runway
token-finops --budget 50000 --cycle-day 1
token-finops --compact            # 2-line minimal output
token-finops --watch 5            # live-refreshing view every 5s
```

## Try it without your own data (synthetic demo)

A small script generates a throwaway SQLite DB with fake usage events (same
columns the tool reads, nothing from your real `~/.copilot/session-store.db`
is ever touched):

```bash
python3 examples/generate_synthetic_db.py /tmp/demo.db --days 20
token-finops --db-path /tmp/demo.db --since 7d
token-finops --db-path /tmp/demo.db --compact
```

Or point the tool at any DB via the `TOKEN_FINOPS_DB` env var instead of
`--db-path`.

### Options

| Flag | Description |
|---|---|
| `--since {1d,7d,30d,all}` | Time window for the usage summary |
| `--session ID` | Filter to a single session |
| `--budget N` | Monthly AI-unit budget (default `50000`) — get this from your Copilot billing page |
| `--cycle-day N` | Day of month your billing cycle resets on (default `1`) |
| `--watch SECONDS` | Live-refreshing view, redraws every N seconds |
| `--compact` / `-c` | 2-line minimal output (budget bar + runway status) |
| `--verbose` / `-vv` | Full report (overrides `--compact`) |

## What it measures

The "AI unit" is GitHub's own cost/usage unit for a mixed
included-quota + pay-per-use Copilot plan, taken from the
`total_nano_aiu` column (divided by `1e9`) — this matches what's shown on
the Copilot billing page. It is **not** raw token counts.

## Requirements

- Python 3 (standard library only — no dependencies)
- GitHub Copilot CLI installed and used at least once (so
  `~/.copilot/session-store.db` exists)

## Optional: use as a Copilot CLI skill

You can drop a `SKILL.md` into `~/.copilot/skills/token-finops-cli/` so any
Copilot CLI session can answer "what's my usage/runway?" on demand by
invoking this script. See the CLI's skills documentation for the expected
format.

## Roadmap

- [ ] Support reading local usage/session logs from other coding agents
      (e.g. Claude Code), so this becomes a general "agentic coding tool
      finops" CLI rather than Copilot-only.

## License

AGPL-3.0 — see [LICENSE](LICENSE).
