burnrate-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel Idoko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# 🔥 Burnrate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**See what your coding agents really cost, and when you'll hit the wall.**
+
+Burnrate is a local, zero-dependency spend and quota meter for **Claude Code** and **Codex CLI**. It reads the logs your agents already write and shows:
+
+- a live **5-hour block forecast**: *"At $5.96/h you'll hit your budget at 17:44, 15 minutes before the reset."*
+- **attribution** by session (titled by your first prompt), project, model and agent: *"that refactor cost $14.23"*
+- **value for money** on subscriptions: *"Claude Max 20x → 3.5× value ($708 of API-equivalent usage for $200)"*
+- a **status line** for Claude Code, a **menu-bar** plugin, a terminal summary and CSV export
+
+```bash
+npx burnrate-cli      # opens http://127.0.0.1:4317
+npx burnrate-cli demo # try it with 30 days of synthetic data
+```
+
+![Burnrate dashboard](docs/screenshots/dashboard-light.png)
+
+> Nothing leaves your machine: no account, no API key, no telemetry. The dashboard binds to `127.0.0.1` only.
+
+---
+
+## Why the numbers are right
+
+Most usage calculators over-count. Claude Code writes **one log line per content block, each repeating the same `usage`**. In a real session we measured 228 assistant lines for 92 actual API responses, so naive summing inflates cost about 2.5×. Prompt-cache writes also cost **1.25× input for the 5-minute TTL and 2× for the 1-hour TTL**, and web searches cost $10 per 1,000.
+
+Burnrate deduplicates by `message.id + requestId` and prices every component. Its test suite reproduces Claude Code's own recorded `cost-state` for a real session **to the 7th decimal place** ($15.0607934 Opus + $1.1404568 Haiku). See [`tests/pricing.test.ts`](tests/pricing.test.ts).
+
+## Install
+
+```bash
+npm i -g burnrate-cli    # installs the `burnrate` command (or use npx burnrate-cli)
+```
+
+Requires Node 20+. Works on macOS, Linux and Windows.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `burnrate` | Scan logs and open the dashboard |
+| `burnrate status` | Today, 7 days, month and projection, current block meter and forecast, top sessions |
+| `burnrate statusline` | One line for Claude Code's status line (reads its JSON on stdin) |
+| `burnrate bar` | xbar / SwiftBar menu-bar output |
+| `burnrate sessions [--days 30] [--limit 20]` | Most expensive sessions |
+| `burnrate export [--csv\|--json] [--days 30]` | Per-message usage with cost |
+| `burnrate budget --block 40 --week 300 --month 1000` | Set budgets (`--clear` to remove) |
+| `burnrate plan claude-max-20x` | Set your subscription to see the value multiple (`--name X --usd N` for custom) |
+| `burnrate watch` | Desktop notifications at 80% and 100% of any budget |
+| `burnrate demo` | Dashboard on synthetic data; your real data is untouched |
+| `burnrate scan` / `reset` / `serve --port N` | Utilities |
+
+Global options: `--path <dir>` (repeatable; prefix `codex:` for Codex logs), `--home <dir>`, `--no-titles`, `--no-color`.
+
+### Claude Code status line
+
+Add to `~/.claude/settings.json`:
+
+```json
+{ "statusLine": { "type": "command", "command": "burnrate statusline" } }
+```
+
+```
+◆ $3.12 session · $20.97 today · 75% block · $5.96/h · limit ~17:44
+```
+
+### macOS menu bar (xbar / SwiftBar)
+
+```bash
+cp integrations/burnrate.1m.sh ~/Library/Application\ Support/xbar/plugins/
+```
+
+```
+🔥 $20.97 75% ⚠︎
+```
+
+## How limits work
+
+Vendors don't publish exact subscription quotas, so Burnrate combines three signals:
+
+1. **Your budget:** `burnrate budget --block 40` or *Budgets & plan* in the dashboard.
+2. **Learned caps:** when a "limit reached" message appears in your Claude Code logs, Burnrate records how much you had spent in the 5 hours before it. With no budget set, it uses the smallest of your last three hits as the cap.
+3. **Reported limits:** Codex logs its own 5-hour and weekly used-percentages and reset times, and Burnrate shows them as-is.
+
+**Blocks** start at your first message after the previous block ended, floored to the hour, and last 5 hours. **Burn rate** is the spend over the last hour of the active block. The forecast is `now + (budget − spent) / burn rate`.
+
+## Data & privacy
+
+| What | Where |
+|---|---|
+| Claude Code logs (read-only) | `~/.claude/projects/**/*.jsonl` (+ `$CLAUDE_CONFIG_DIR`), subagents included |
+| Codex CLI logs (read-only) | `~/.codex/sessions/**/*.jsonl` (+ `$CODEX_HOME`) |
+| Burnrate's cache & config | `~/.burnrate/` (`$BURNRATE_HOME`): `events.ndjson`, `state.json`, `meta.json`, `config.json`, optional `prices.json` |
+
+Burnrate stores token counts, timestamps, model, project path and the **first 80 characters of each session's first prompt** (as its title). Use `--no-titles` to skip titles. Scans are incremental (byte offsets per file), so refreshing costs milliseconds.
+
+**Custom prices.** Costs are *API-equivalent estimates* from public per-token prices (see [`src/pricing.ts`](src/pricing.ts)). To add or override a price, create `~/.burnrate/prices.json`:
+
+```json
+{ "my-model": { "input": 1, "output": 4, "cacheRead": 0.1 } }
+```
+
+## Development
+
+```bash
+npm install
+npm test           # vitest: pricing, parsers, incremental store, blocks & forecast
+npm run build      # tsc → dist/, copies the dashboard
+node dist/cli.js demo
+```
+
+```
+src/
+  cli.ts            commands
+  parsers/          claude.ts · codex.ts — defensive line parsers
+  store.ts          incremental ingest, dedupe, ~/.burnrate cache
+  pricing.ts        price table + cost engine
+  aggregate.ts      totals, 5-hour blocks, forecast, learned caps, breakdowns
+  server.ts         localhost dashboard API (DNS-rebinding + CSRF guarded)
+  dashboard/        index.html · styles.css · app.js (vanilla, hand-built SVG charts)
+  demo.ts           deterministic synthetic logs in both formats
+```
+
+Docs: [Product requirements](docs/PRD.md) · [Design](docs/DESIGN.md)
+
+**Releasing.** Bump `version` in `package.json` and push to `main`. The release workflow publishes to npm with provenance (trusted publishing, or an `NPM_TOKEN` secret), then creates the tag and GitHub release.
+
+## License
+
+MIT

package/dist/aggregate.js

@@ -0,0 +1,213 @@
+export const BLOCK_MS = 5 * 3600_000;
+const HOUR = 3600_000;
+const DAY = 86400_000;
+export function localDate(ts) {
+    const d = new Date(ts);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+function startOfDay(ts) {
+    const d = new Date(ts);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+export function priceAll(events, prices) {
+    return events
+        .map((e) => {
+        const c = prices.cost(e);
+        return {
+            ...e,
+            cost: c ?? 0,
+            priced: c !== null,
+            tokens: e.input + e.output + e.cacheRead + e.cacheWrite5m + e.cacheWrite1h,
+        };
+    })
+        .sort((a, b) => a.ts - b.ts);
+}
+/**
+ * Splits activity into 5-hour blocks the way subscription windows work:
+ * a block opens at the first message after the previous block ended (floored to the hour).
+ */
+export function computeBlocks(events) {
+    const blocks = [];
+    let cur = null;
+    for (const e of events) {
+        if (!cur || e.ts >= cur.end) {
+            const start = Math.floor(e.ts / HOUR) * HOUR;
+            cur = { start, end: start + BLOCK_MS, cost: 0, tokens: 0, events: 0, firstTs: e.ts, lastTs: e.ts };
+            blocks.push(cur);
+        }
+        cur.cost += e.cost;
+        cur.tokens += e.tokens;
+        cur.events++;
+        cur.lastTs = e.ts;
+    }
+    return blocks;
+}
+export function summarize(events, sessions, limits, rateLimits, cfg, prices, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const days = opts.days ?? 30;
+    const priced = priceAll(events, prices).filter((e) => e.ts <= now + 60_000);
+    const today0 = startOfDay(now);
+    const month0 = new Date(new Date(now).getFullYear(), new Date(now).getMonth(), 1).getTime();
+    const daysInMonth = new Date(new Date(now).getFullYear(), new Date(now).getMonth() + 1, 0).getDate();
+    const dayOfMonth = new Date(now).getDate();
+    let today = 0, yesterday = 0, last7 = 0, mtd = 0, allTime = 0, tokensToday = 0, savings = 0;
+    const since30 = now - 30 * DAY;
+    for (const e of priced) {
+        allTime += e.cost;
+        if (e.ts >= today0) {
+            today += e.cost;
+            tokensToday += e.tokens;
+        }
+        else if (e.ts >= today0 - DAY)
+            yesterday += e.cost;
+        if (e.ts >= now - 7 * DAY)
+            last7 += e.cost;
+        if (e.ts >= month0)
+            mtd += e.cost;
+        if (e.ts >= since30 && e.priced) {
+            const p = prices.lookup(e.model);
+            savings += (e.cacheRead * (p.input - p.cacheRead)) / 1e6;
+        }
+    }
+    const avgDaily7 = last7 / 7;
+    const monthProjection = mtd + avgDaily7 * (daysInMonth - dayOfMonth + (1 - (now - today0) / DAY));
+    // Blocks & forecast
+    const blocks = computeBlocks(priced);
+    const learnedCaps = [];
+    // The vendor's window isn't visible to us, so estimate the cap as spend in the 5 hours before the hit.
+    const limitRows = limits.slice(-20).map((l) => {
+        const window = priced.filter((e) => e.ts > l.ts - BLOCK_MS && e.ts <= l.ts);
+        const blockCost = window.length ? window.reduce((s, e) => s + e.cost, 0) : null;
+        if (blockCost && l.agent === "claude-code")
+            learnedCaps.push(blockCost);
+        return { ...l, blockCost };
+    });
+    // Conservative: the smallest observed cap among the most recent three hits.
+    const learnedCap = learnedCaps.length ? Math.min(...learnedCaps.slice(-3)) : null;
+    const last = blocks[blocks.length - 1];
+    let block = null;
+    if (last) {
+        const active = now < last.end && now >= last.start;
+        const blockEvents = priced.filter((e) => e.ts >= last.start && e.ts < last.end);
+        const windowStart = Math.max(last.start, now - HOUR);
+        const recent = blockEvents.filter((e) => e.ts >= windowStart).reduce((s, e) => s + e.cost, 0);
+        const elapsedH = Math.max((now - windowStart) / HOUR, 1 / 6);
+        const burnPerHour = active ? recent / elapsedH : 0;
+        const remainingMs = active ? last.end - now : 0;
+        const budget = cfg.budgets.blockUsd ?? learnedCap ?? null;
+        const projected = last.cost + burnPerHour * (remainingMs / HOUR);
+        let hitsBudgetAt = null;
+        if (active && budget && burnPerHour > 0) {
+            const t = last.cost >= budget ? now : now + ((budget - last.cost) / burnPerHour) * HOUR;
+            if (t < last.end)
+                hitsBudgetAt = t;
+        }
+        const series = [];
+        let cum = 0, idx = 0;
+        const stop = active ? now : last.lastTs;
+        for (let t = last.start; t <= stop + 10 * 60_000; t += 10 * 60_000) {
+            while (idx < blockEvents.length && blockEvents[idx].ts < t)
+                cum += blockEvents[idx++].cost;
+            series.push({ t: Math.min(t, stop), cost: cum });
+            if (t >= stop)
+                break;
+        }
+        block = {
+            start: last.start,
+            end: last.end,
+            active,
+            cost: last.cost,
+            tokens: last.tokens,
+            burnPerHour,
+            projected,
+            budget,
+            budgetSource: cfg.budgets.blockUsd ? "user" : learnedCap ? "learned" : null,
+            percent: budget ? last.cost / budget : null,
+            hitsBudgetAt,
+            remainingMs,
+            series,
+        };
+    }
+    // Daily series
+    const dayMap = new Map();
+    for (let i = days - 1; i >= 0; i--)
+        dayMap.set(localDate(now - i * DAY), { total: 0, tokens: 0, byAgent: {} });
+    for (const e of priced) {
+        const row = dayMap.get(localDate(e.ts));
+        if (!row)
+            continue;
+        row.total += e.cost;
+        row.tokens += e.tokens;
+        row.byAgent[e.agent] = (row.byAgent[e.agent] ?? 0) + e.cost;
+    }
+    // Breakdown tables (within the selected range)
+    const rangeStart = startOfDay(now - (days - 1) * DAY);
+    const inRange = priced.filter((e) => e.ts >= rangeStart);
+    const agents = new Map();
+    const models = new Map();
+    const sess = new Map();
+    for (const e of inRange) {
+        const a = agents.get(e.agent) ?? { cost: 0, tokens: 0, events: 0 };
+        a.cost += e.cost;
+        a.tokens += e.tokens;
+        a.events++;
+        agents.set(e.agent, a);
+        const m = models.get(e.model) ?? { model: e.model, cost: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, priced: e.priced };
+        m.cost += e.cost;
+        m.input += e.input;
+        m.output += e.output;
+        m.cacheRead += e.cacheRead;
+        m.cacheWrite += e.cacheWrite5m + e.cacheWrite1h;
+        models.set(e.model, m);
+        const meta = sessions[e.session];
+        const s = sess.get(e.session) ?? {
+            id: e.session, title: meta?.title ?? null, agent: e.agent, project: meta?.project || e.project,
+            cost: 0, tokens: 0, start: e.ts, end: e.ts, models: [], modelSet: new Set(),
+        };
+        s.cost += e.cost;
+        s.tokens += e.tokens;
+        s.end = Math.max(s.end, e.ts);
+        s.start = Math.min(s.start, e.ts);
+        s.modelSet.add(e.model);
+        sess.set(e.session, s);
+    }
+    const sessionList = [...sess.values()].map(({ modelSet, ...s }) => ({ ...s, models: [...modelSet] }));
+    const projects = new Map();
+    for (const s of sessionList) {
+        const p = projects.get(s.project) ?? { project: s.project, cost: 0, tokens: 0, sessions: 0, lastTs: 0 };
+        p.cost += s.cost;
+        p.tokens += s.tokens;
+        p.sessions++;
+        p.lastTs = Math.max(p.lastTs, s.end);
+        projects.set(s.project, p);
+    }
+    const weekBudget = cfg.budgets.weekUsd ?? null;
+    const monthBudget = cfg.budgets.monthUsd ?? null;
+    const plan = cfg.plan
+        ? { ...cfg.plan, valueMultiple: cfg.plan.monthlyUsd > 0 ? monthProjection / cfg.plan.monthlyUsd : null }
+        : null;
+    return {
+        generatedAt: now,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        totals: {
+            today, yesterday, last7, mtd, monthProjection, allTime, tokensToday,
+            cacheSavings30d: savings,
+            firstEventTs: priced[0]?.ts ?? null,
+        },
+        plan,
+        block,
+        week: { cost: last7, budget: weekBudget, percent: weekBudget ? last7 / weekBudget : null },
+        month: { cost: mtd, budget: monthBudget, percent: monthBudget ? mtd / monthBudget : null, projected: monthProjection },
+        learnedCap,
+        daily: [...dayMap.entries()].map(([date, v]) => ({ date, ...v })),
+        agents: [...agents.entries()].map(([agent, v]) => ({ agent, ...v })).sort((a, b) => b.cost - a.cost),
+        models: [...models.values()].sort((a, b) => b.cost - a.cost),
+        projects: [...projects.values()].sort((a, b) => b.cost - a.cost),
+        sessions: sessionList.sort((a, b) => b.cost - a.cost).slice(0, 100),
+        limits: limitRows.reverse(),
+        rateLimits: Object.values(rateLimits),
+        unpricedModels: [...new Set(priced.filter((e) => !e.priced).map((e) => e.model))],
+        eventCount: priced.length,
+    };
+}