@tokz/cli 0.2.4 → 0.2.6

package/README.md

@@ -1,127 +1,153 @@
 # tokz
 
-Audit where your coding agents' context windows — and API dollars — actually go.
-
-Supports multiple agentic coders: **Claude Code** (`~/.claude/projects`),
-**OpenAI Codex CLI** (`~/.codex/sessions` rollout files, cumulative
-token-count deltas), **OpenCode** (`~/.local/share/opencode/storage`), and
-**Antigravity CLI** (`~/.gemini/antigravity-cli`). Antigravity stores no
-token counts on disk, so its numbers are *estimates*: per-model turn counts
-are read from the conversation databases' generation-metadata records,
-projects and dates from `history.jsonl`, and tokens are derived from
-conversation content size (~4 chars/token) — the UI labels it "estimated"
-everywhere. Cursor CLI is detected and listed with the reason it can't be
-parsed yet. The TUI opens with an agent picker — choose which agent's
-analytics to explore; everything downstream (projects, dashboards,
-timeframes) is scoped to it.
+**See where your coding agents' tokens — and dollars — actually go.**
+
+tokz reads the session logs your coding agents already write to disk and turns
+them into a clear picture of cost: per model, per project, per tool, per day,
+and per MCP server — including the ones you pay to load on every turn but never
+call. One command, no API key, nothing leaves your machine except an optional
+pricing refresh.
 
 ```bash
-npx @tokz/cli             # interactive TUI: browse projects, drill into charts
+npx @tokz/cli             # interactive TUI — pick an agent, browse projects, drill into charts
 npx @tokz/cli audit       # static report for the current project
 npx @tokz/cli audit --all # static report across every project on this machine
 npx @tokz/cli blocks      # Claude usage by rolling 5-hour billing window
 
-npm i -g @tokz/cli        # installs the `tokz` command
-tokz                      # then just: tokz
+npm i -g @tokz/cli        # install the `tokz` command, then just: tokz
 ```
 
-## Blocks (5-hour billing windows)
+The TUI opens on an agent picker; everything downstream — projects, dashboards,
+timeframes — is scoped to the agent you choose.
+
+## Supported agents
+
+tokz auto-detects each agent from its local data directory. No configuration.
+
+| Agent | Reads from | Status |
+| --- | --- | --- |
+| Claude Code | `~/.claude/projects` | ✅ parsed |
+| OpenAI Codex | `~/.codex/sessions` | ✅ parsed |
+| OpenCode | `~/.local/share/opencode` | ✅ parsed |
+| Gemini CLI | `~/.gemini/tmp` | ✅ parsed |
+| Qwen Code | `~/.qwen` | ✅ parsed |
+| Droid (Factory) | `~/.factory/sessions` | ✅ parsed |
+| Codebuff | `~/.config/manicode*` | ✅ parsed |
+| OpenClaw | `~/.openclaw` | ✅ parsed |
+| Kimi CLI | `~/.kimi` | ✅ parsed |
+| pi-agent | `~/.pi/agent` | ✅ parsed |
+| Kilo | `~/.local/share/kilo/kilo.db` | ✅ parsed (SQLite) |
+| Goose | `~/.local/share/goose` | ✅ parsed (SQLite) |
+| Hermes | `~/.hermes/state.db` | ✅ parsed (SQLite) |
+| Antigravity | `~/.gemini/antigravity-cli` | ≈ estimated¹ |
+| GitHub Copilot CLI | `~/.copilot/otel` | 🔍 detected, not parsed² |
+| Amp | `~/.local/share/amp` | 🔍 detected, not parsed² |
+
+¹ Antigravity stores no token counts on disk. tokz reads real per-model turn
+counts from its conversation databases and estimates tokens from content size
+(~4 chars/token); the UI labels every Antigravity number **estimated**.
+
+² Detected and listed with the reason, but not yet parsed: Copilot stores usage
+as OpenTelemetry spans, Amp as a usage ledger. (Cursor is intentionally left
+out — it keeps no token counts locally; usage lives server-side behind auth.)
+
+The three SQLite-backed agents are read with a small built-in pure-JS SQLite
+reader, so there's no native dependency and `npx` just works.
 
-`tokz blocks` groups Claude usage into the rolling 5-hour windows Claude's
-usage limits operate on: one row per block with models, total tokens, and
-cost, plus burn rate (tok/min and $/hr), projected tokens/cost by block end,
-and time remaining for the active block. `--active` shows only the current
-block, `--recent` the last 3 days, `--token-limit N` (or `max` — your
-biggest past block) adds ⚠️/🚨 warnings, `--session-length H` changes the
-window, `--json` for raw output.
+## Interactive TUI
 
-## Statusline for Claude Code
+Bare `tokz` launches a full-screen Ink UI: a live parse progress bar, then a
+landing screen of stat cards — total cost, monthly projection, sessions, turns,
+cache hit rate — with a 30-day activity sparkline.
 
-`tokz statusline` renders one compact line for Claude Code's status bar —
-model, session cost, today's total, active block cost with time left, burn
-rate, and context usage with percentage. One command wires it up:
+- **Project list** — every project by short name (real paths recovered from the
+  transcripts), ranked by cost, with session count, last activity, and share
+  bars, plus a pinned **All projects** row. `/` filters, `s` cycles the sort
+  (cost · recent · name), `a` jumps to the aggregate view.
+- **Dashboard** (per project or aggregated) — six tabs via `1–6` or `←`/`→`:
+  1. **Overview** — stat cards, 30-day cost sparkline with peak day, cost by
+     model, top tools, unused-server warning.
+  2. **Models** — per-model token table (input / cache read / cache write /
+     output / turns), cost, and share.
+  3. **Tools** — top tools ranked by estimated cost (each turn's bill split
+     across the tools it called), with call counts; MCP tools highlighted.
+  4. **Servers** — every MCP server with calls observed and estimated cost,
+     from configs (`.mcp.json`, `~/.claude.json`) and from transcripts alone
+     (plugin and externally-managed servers) — plus whether each is dead weight.
+  5. **Sessions** — costliest sessions with date, wall-clock length, turns, tool
+     calls, and dominant model.
+  6. **Activity** — daily cost bars with turn counts; `g` groups by day · week ·
+     month.
+- **Timeframe** — `t` cycles All time · Today · Yesterday · Last 7 days · Last
+  30 days; every list, chart, and total rescopes.
+- `?` help overlay, `esc` back, `q` quit.
+
+The layout is responsive down to ~35 columns — tables drop non-essential
+columns, tab labels collapse to numbers, the banner shrinks — and long lists
+scroll. Piped or non-interactive, `tokz` prints the static aggregate report.
+
+## Blocks — Claude's 5-hour windows
+
+`tokz blocks` groups Claude usage into the rolling 5-hour windows its usage
+limits operate on: one row per block with models, total tokens, and cost, plus
+burn rate (tok/min and $/hr), projected tokens and cost by block end, and time
+remaining on the active block.
 
 ```bash
-tokz statusline enable    # writes the hook into ~/.claude/settings.json
-tokz statusline disable   # removes it (only if it's tokz's)
+tokz blocks --active            # only the current block
+tokz blocks --recent            # last 3 days
+tokz blocks --token-limit max   # ⚠️/🚨 warnings vs your biggest past block
+tokz blocks --session-length 5  # window length in hours (default 5)
+tokz blocks --json              # raw output
 ```
 
-`enable` preserves everything else in your settings file (and refuses to
-touch one it can't parse); it's equivalent to:
-
-```json
-{
-  "statusLine": { "type": "command", "command": "npx -y @tokz/cli statusline" }
-}
-```
+## Statusline for Claude Code
 
-It reads only transcripts touched in the last few hours and never fetches
-pricing from the network on this path, so it stays fast.
+`tokz statusline` renders one compact line for Claude Code's status bar:
 
-## Dates, ranges, and timezones
+```text
+🤖 Fable 5 (high) | 💰 $0.23 session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr | 🧠 25,000 (12%)
+```
 
-- `tokz audit --since 2026-07-01 --until 2026-07-15` — any inclusive date
-  range (also accepts `YYYYMMDD`); `--days N` still works.
-- `tokz audit --weekly` / `--monthly` — appends an activity table rolled up
-  by ISO week (keyed by its Monday) or calendar month. In the TUI the
-  Activity tab cycles day · week · month with `g`.
-- `tokz --timezone local audit …` — group days in your system timezone, or
-  any IANA zone (`--timezone Asia/Amman`); default is UTC.
+Model with reasoning effort, session cost, today's total, active-block cost with
+time left, burn rate (colored by tokens/min), and context usage (colored by how
+full the window is). Session cost, context, and effort come from Claude Code's
+hook payload; today's total and the block come from your local transcripts.
 
-## Interactive TUI
+```bash
+tokz statusline enable    # add the hook to ~/.claude/settings.json
+tokz statusline disable   # remove it (only if it's tokz's)
+```
 
-Bare `tokz` launches a full-screen terminal UI (Ink) with a live parse
-progress bar, then a landing screen of stat cards — total cost, monthly
-projection, sessions, turns, cache hit rate — plus a 30-day activity
-sparkline.
+`enable` preserves everything else in your settings and refuses to touch a file
+it can't parse. `--cost-source auto|cc|calc|both` picks the session-cost source:
+`cc` uses Claude Code's own figure, `calc` recomputes from tokens, `both` shows
+`($0.25 cc / $0.23 calc)`. The statusline reads only recently-touched
+transcripts and never fetches pricing, so it stays instant.
 
-From there:
+## Dates, ranges, timezones
 
-- **Project list** — every project by short name (real paths recovered from
-  the transcripts themselves), ranked by cost, with session count, last
-  activity, and share bars, plus a pinned **All projects** row. Press `/` to
-  filter by name, `s` to cycle sorting (cost · recent · name), `a` to jump to
-  the aggregate view.
-- **Dashboard** (per project or aggregated) — six tabs, switched with `1–6`
-  or `←`/`→`:
-  1. **Overview** — stat cards, 30-day cost sparkline with peak day, cost by
-     model, top tools, unused-server warning.
-  2. **Models** — per-model token table (input / cache read / cache write /
-     output / turns), cost and share, plus the total cost split.
-  3. **Tools** — top tools ranked by estimated cost (each turn's bill split
-     across the tools that turn called) with call counts and share; MCP tools
-     highlighted.
-  4. **Servers** — every MCP server with calls observed and estimated cost.
-     Covers both configured servers (`.mcp.json`, `~/.claude.json`) and ones
-     only visible in transcripts — plugin MCP servers and externally managed
-     configs — plus whether each is dead weight in your context window.
-  5. **Sessions** — costliest sessions with date, wall-clock length, turns,
-     tool calls, and dominant model.
-  6. **Activity** — daily cost bars with turn counts, average per active day.
-- **Timeframe** — press `t` anywhere to cycle All time · Today · Yesterday ·
-  Last 7 days · Last 30 days; every list, chart, and total rescopes to that
-  window (`--days N` does the same for the static report).
-- `?` shows a help overlay, `esc` goes back, `q` quits.
-
-The layout is responsive: on narrow terminals the list drops columns (share
-bar, then last-active, then sessions), tables keep only their key columns,
-tab labels collapse to numbers, and the banner shrinks — nothing wraps or
-breaks down to ~35 columns.
-
-Piped or non-interactive, `tokz` falls back to the static aggregate report
-automatically.
+```bash
+tokz audit --since 2026-07-01 --until 2026-07-15   # any inclusive range (also YYYYMMDD)
+tokz audit --days 7                                # last N days
+tokz audit --weekly      # or --monthly — appends an activity table by ISO week / month
+tokz --timezone local audit …                      # or any IANA zone; default UTC
+```
 
 ## What it measures
 
-Reads Claude Code transcripts (`~/.claude/projects/**/*.jsonl`) and MCP configs
-(`.mcp.json`, `~/.claude.json`). Reports real billed token usage per model
-(input / cache read / cache write / output), dollar cost at current Anthropic
-pricing, a monthly projection, cache hit rate and estimated cache savings,
-per-tool call counts, per-day activity, per-session cost, and — the headline —
-**MCP servers you pay to load on every turn but never call**.
+Real billed token usage per model (input / cache read / cache write / output),
+dollar cost, monthly projection, cache hit rate and estimated cache savings,
+per-tool call counts and cost, per-day activity, per-session cost, and — the
+headline — **MCP servers you pay to load on every turn but never call**.
+
+Costs are API-equivalent: what these tokens would bill at pay-as-you-go rates.
+On a Pro/Max subscription, read it as value received, not a bill. Pricing comes
+from a live model catalog, cached on disk for a day; run with `--offline` to
+skip the fetch and use built-in rates.
 
-Costs are API-equivalent: what these tokens would bill at Anthropic
-pay-as-you-go rates. On a Pro/Max subscription treat it as value received,
-not a bill.
+## Privacy
 
-100% offline. No API key, no telemetry, nothing leaves your machine.
+Your session logs never leave your machine. The only network call tokz ever
+makes is fetching public model pricing (cacheable, and fully skippable with
+`--offline`). No API key, no telemetry.