burntokens 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanket Gangani
+
+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,115 @@
-# Temporary Holding Version
+# TokenBurn 🔥
 
-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.
+**Watch your Claude Code tokens burn in real time. Local, open source, slightly judgmental.**
+
+```bash
+npx burntokens
+```
+
+TokenBurn reads the transcript logs Claude Code already writes on your machine and turns them into a live dashboard: a big glowing counter that ticks while you work, history by day / week / month / project / model, what it all *would* have cost at API prices, and a lake that slowly drains as your estimated water footprint grows.
+
+It runs 100% locally. No accounts, no telemetry, nothing leaves your machine.
+
+> Not affiliated with or endorsed by Anthropic.
+
+## Install
+
+Requires Node 20+. The npm package is called `burntokens` (the name `tokenburn` was too close to an existing package). Once installed, the command is `tokenburn` (`burntokens` works too).
+
+```bash
+npx burntokens           # one-off: parse logs, start the dashboard, open the browser
+npm i -g burntokens      # or install globally; this gives you the `tokenburn` command
+```
+
+## Modes
+
+| Command | What it does |
+|---|---|
+| `tokenburn` | Dashboard at `http://127.0.0.1:4242`, live-updating as you use Claude Code |
+| `tokenburn --summary` | Compact table in the terminal |
+| `tokenburn --json` | All aggregates as JSON, for scripting |
+| `tokenburn statusline` | One line for Claude Code's custom status line |
+
+Options: `--dir <path>` (logs location), `--port <n>`, `--no-open`, `--no-cache`, `--days <n>`, `--project <key>`, `--model <id>`. Run `tokenburn --help` for the full list.
+
+## Status line
+
+Claude Code can show a custom status line under its prompt. Add this to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "tokenburn statusline"
+  }
+}
+```
+
+It prints something like:
+
+```
+302.6M session · 🔥 331.2M today · $128.73 api-eq · ≈11 water bottles
+```
+
+Claude Code passes the current `session_id` on stdin, which is how the session figure is found. The command only reads files modified today (plus the current session's file), so it stays fast with gigabytes of history. Use a global install (`npm i -g burntokens`) rather than `npx` here so it does not hit the network on every refresh.
+
+## Where the numbers come from
+
+**Tokens.** Claude Code writes JSONL transcripts to `~/.claude/projects/**/*.jsonl` (or `$CLAUDE_CONFIG_DIR/projects`). Each assistant turn carries `model` and `usage` with input, output, cache-write and cache-read token counts. The same message is written several times (once per content block), so TokenBurn de-duplicates on message id + request id across all files. Subagent transcripts are included. The observed format is documented in [docs/log-format.md](docs/log-format.md).
+
+**Cost.** Every cost in the UI is **API-equivalent**: what the same tokens would cost on pay-as-you-go at the prices on [Anthropic's pricing page](https://platform.claude.com/docs/en/about-claude/pricing). Prices live in [`src/pricing.json`](src/pricing.json) with the date they were checked. If you are on a Pro or Max subscription you are not billed per token, so treat it as a "what if". Models missing from the table are shown with cost "unknown" rather than a guess. Cache writes are priced by TTL (5-minute vs 1-hour) when the log records the split.
+
+**Water and energy (the lake).** There is no official per-token figure from Anthropic, so this is deliberately labelled *rough estimate, for fun*. The defaults in [`src/footprint.json`](src/footprint.json):
+
+- 600 Wh per million **output** tokens, derived from the widely cited ~0.3 Wh per typical chat response of a few hundred tokens ([Epoch AI](https://epoch.ai/gradient-updates/how-much-energy-does-chatgpt-use)) and consistent with the ~0.34 Wh median for frontier-scale models in [Energy Use of AI Inference (2025)](https://arxiv.org/abs/2509.20241).
+- Input, cache-write and cache-read tokens are weighted at 0.1, 0.1 and 0.01 of an output token. Prefill is far cheaper than generation and cache hits cheaper still; the exact ratios are a judgement call, not a measurement.
+- 2 litres of water per kWh, a blend of on-site cooling and a share of power-generation water ([Making AI Less "Thirsty"](https://arxiv.org/abs/2304.03271)).
+
+The result is then expressed on a ladder: sips → cups → bottles → buckets → bathtubs → hot tubs → backyard pools → Olympic pools → a small lake. The lake drains on a log scale from one sip to one small lake. Every factor is editable in the dashboard settings and saved to `~/.tokenburn/config.json`. Please do not quote these numbers as fact.
+
+## Privacy
+
+- Reads log files only. Never writes to them.
+- Reads only the `usage`, `model`, `timestamp`, id and `cwd` fields. Prompt and response content is never parsed, stored or displayed.
+- The server binds to `127.0.0.1` only and rejects cross-origin requests.
+- No network calls, ever. No fonts, analytics or update checks.
+- The only files TokenBurn writes are `~/.tokenburn/config.json` (your settings) and `~/.tokenburn/cache.json` (parsed token counts, so large histories load fast). Delete them any time; `--no-cache` skips the cache.
+
+## FAQ
+
+**Does this include claude.ai web or desktop chat usage?**
+No. Those don't expose token counts and scraping undocumented endpoints is fragile. TokenBurn covers Claude Code only.
+
+**Why is cost "unknown" for some sessions?**
+The model id isn't in `src/pricing.json`. Add it (or open a PR) and the cost appears.
+
+**Why are cache reads such a big share?**
+Claude Code sends your whole conversation on every turn and most of it is served from the prompt cache. That's normal, and it's why cache-read pricing is ~10x cheaper. Use "Without cache reads" on the tokens chart to see the rest.
+
+**The numbers don't match `/usage` exactly.**
+`/usage` is per session and live. TokenBurn de-duplicates across files and counts subagent usage, so small differences are expected. Large differences are a bug: please file an issue with `tokenburn --json` output (it contains no content).
+
+**Logs live somewhere else.**
+`tokenburn --dir /path/to/.claude` or set `CLAUDE_CONFIG_DIR`.
+
+**Windows?**
+Logs are read from `%USERPROFILE%\.claude\projects`. The dashboard and summary modes work; the status line works with `tokenburn statusline` too.
+
+## Development
+
+```bash
+npm install
+npm start              # build everything, then run the dashboard (easiest)
+npm run dev            # build the dashboard, run the CLI from TypeScript source
+npm test               # vitest, synthetic fixtures only
+npm run build          # tsc + vite → dist/
+npm run dev:web        # vite dev server for the dashboard (proxies /api to :4242)
+```
+
+If port 4242 is taken (for example an older TokenBurn is still running), the next free port is used and printed in the terminal.
+
+Layout: `src/` is the CLI + server (discover → parse → aggregate → cost/footprint → server/watch), `web/` is the Vite + React dashboard, `test/fixtures/` holds synthetic JSONL (no real data).
+
+## License
+
+MIT. Not affiliated with or endorsed by Anthropic. Costs are estimates; water and energy figures are rough and for fun.

package/dist/aggregate.js

@@ -0,0 +1,218 @@
+import { costBreakdownOfEvent, costOf, costOfEvent } from "./cost.js";
+export function filterEvents(events, f = {}) {
+    const projects = f.projects?.length ? new Set(f.projects) : null;
+    const models = f.models?.length ? new Set(f.models) : null;
+    return events.filter((e) => (f.from === undefined || e.ts >= f.from) &&
+        (f.to === undefined || e.ts < f.to) &&
+        (!projects || projects.has(e.project)) &&
+        (!models || models.has(e.model)));
+}
+export function emptyTotals() {
+    return { input: 0, output: 0, cacheWrite: 0, cacheRead: 0, total: 0 };
+}
+export function addEvent(t, e) {
+    t.input += e.input;
+    t.output += e.output;
+    t.cacheWrite += e.cacheWrite5m + e.cacheWrite1h;
+    t.cacheRead += e.cacheRead;
+    t.total += e.input + e.output + e.cacheWrite5m + e.cacheWrite1h + e.cacheRead;
+    return t;
+}
+export function tokenTotals(events) {
+    const t = emptyTotals();
+    for (const e of events)
+        addEvent(t, e);
+    return t;
+}
+const pad = (n) => String(n).padStart(2, "0");
+/** Local-time calendar day: YYYY-MM-DD */
+export function dayKey(ts) {
+    const d = new Date(ts);
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/** Local-time month: YYYY-MM */
+export function monthKey(ts) {
+    const d = new Date(ts);
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}`;
+}
+/** Local-time week, keyed by its Monday: YYYY-MM-DD */
+export function weekKey(ts) {
+    return dayKey(startOfWeek(ts));
+}
+export function startOfDay(ts) {
+    const d = new Date(ts);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+export function startOfWeek(ts) {
+    const d = new Date(startOfDay(ts));
+    const dow = (d.getDay() + 6) % 7; // Monday = 0
+    d.setDate(d.getDate() - dow);
+    return d.getTime();
+}
+export function startOfMonth(ts) {
+    const d = new Date(ts);
+    return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+}
+export function groupBy(events, keyOf) {
+    const map = new Map();
+    for (const e of events) {
+        const k = keyOf(e);
+        let b = map.get(k);
+        if (!b) {
+            b = { key: k, ...emptyTotals(), usd: 0, unknownTokens: 0, requests: 0 };
+            map.set(k, b);
+        }
+        addEvent(b, e);
+        b.requests++;
+        const c = costOfEvent(e);
+        if (c === null)
+            b.unknownTokens += e.input + e.output + e.cacheWrite5m + e.cacheWrite1h + e.cacheRead;
+        else
+            b.usd += c;
+    }
+    return [...map.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+export const byDay = (ev) => groupBy(ev, (e) => dayKey(e.ts));
+export const byWeek = (ev) => groupBy(ev, (e) => weekKey(e.ts));
+export const byMonth = (ev) => groupBy(ev, (e) => monthKey(e.ts));
+export const byModel = (ev) => groupBy(ev, (e) => e.model).sort((a, b) => b.total - a.total);
+export function byProject(ev) {
+    const labels = new Map();
+    const list = [...ev];
+    for (const e of list)
+        if (!labels.has(e.project))
+            labels.set(e.project, e.projectLabel);
+    return groupBy(list, (e) => e.project)
+        .map((b) => ({ ...b, label: labels.get(b.key) ?? b.key }))
+        .sort((a, b) => b.total - a.total);
+}
+/** Fill in missing days between first and last so charts show gaps honestly. */
+export function fillDays(buckets, from, to) {
+    if (!buckets.length && from === undefined)
+        return [];
+    const start = from !== undefined ? startOfDay(from) : Date.parse(buckets[0].key + "T00:00");
+    const end = to !== undefined ? startOfDay(to - 1) : Date.parse(buckets[buckets.length - 1].key + "T00:00");
+    const have = new Map(buckets.map((b) => [b.key, b]));
+    const out = [];
+    const d = new Date(start);
+    while (d.getTime() <= end) {
+        const k = dayKey(d.getTime());
+        out.push(have.get(k) ?? { key: k, ...emptyTotals(), usd: 0, unknownTokens: 0, requests: 0 });
+        d.setDate(d.getDate() + 1);
+    }
+    return out;
+}
+export function sessions(events) {
+    const map = new Map();
+    for (const e of events) {
+        let s = map.get(e.sessionId);
+        if (!s) {
+            s = {
+                sessionId: e.sessionId,
+                project: e.project,
+                projectLabel: e.projectLabel,
+                model: e.model,
+                models: [],
+                start: e.ts,
+                end: e.ts,
+                durationMs: 0,
+                ...emptyTotals(),
+                usd: 0,
+                unknownTokens: 0,
+                requests: 0,
+                modelTokens: new Map(),
+            };
+            map.set(e.sessionId, s);
+        }
+        addEvent(s, e);
+        s.requests++;
+        s.start = Math.min(s.start, e.ts);
+        s.end = Math.max(s.end, e.ts);
+        const c = costOfEvent(e);
+        if (c === null)
+            s.unknownTokens += e.input + e.output + e.cacheWrite5m + e.cacheWrite1h + e.cacheRead;
+        else
+            s.usd += c;
+        const tk = e.input + e.output + e.cacheWrite5m + e.cacheWrite1h + e.cacheRead;
+        s.modelTokens.set(e.model, (s.modelTokens.get(e.model) ?? 0) + tk);
+    }
+    return [...map.values()]
+        .map(({ modelTokens, ...s }) => {
+        const sorted = [...modelTokens.entries()].sort((a, b) => b[1] - a[1]);
+        return { ...s, model: sorted[0]?.[0] ?? s.model, models: sorted.map((x) => x[0]), durationMs: s.end - s.start };
+    })
+        .sort((a, b) => b.end - a.end);
+}
+export function periodCard(label, events, from, now) {
+    const slice = filterEvents(events, { from, to: now + 1 });
+    const t = tokenTotals(slice);
+    const c = costOf(slice);
+    const models = byModel(slice);
+    return { label, from, ...t, usd: c.usd, unknownTokens: c.unknownTokens, topModel: models[0]?.key ?? null, requests: slice.length };
+}
+/** Tokens and cost by local hour of day (0-23). */
+export function byHourOfDay(events) {
+    const out = Array.from({ length: 24 }, (_, h) => ({ key: String(h), ...emptyTotals(), usd: 0, unknownTokens: 0, requests: 0 }));
+    for (const e of events) {
+        const b = out[new Date(e.ts).getHours()];
+        addEvent(b, e);
+        b.requests++;
+        const c = costOfEvent(e);
+        if (c === null)
+            b.unknownTokens += e.input + e.output + e.cacheWrite5m + e.cacheWrite1h + e.cacheRead;
+        else
+            b.usd += c;
+    }
+    return out;
+}
+export function costByKind(events) {
+    const t = { input: 0, output: 0, cacheWrite: 0, cacheRead: 0, cacheSavings: 0 };
+    for (const e of events) {
+        const b = costBreakdownOfEvent(e);
+        if (!b)
+            continue;
+        t.input += b.input;
+        t.output += b.output;
+        t.cacheWrite += b.cacheWrite;
+        t.cacheRead += b.cacheRead;
+        t.cacheSavings += b.cacheSavings;
+    }
+    return t;
+}
+export function buildSummary(all, f = {}, now = Date.now(), sessionLimit = 50) {
+    const events = filterEvents(all, f);
+    const t = tokenTotals(events);
+    const c = costOf(events);
+    const sess = sessions(events);
+    let first = null;
+    let last = null;
+    for (const e of events) {
+        if (first === null || e.ts < first)
+            first = e.ts;
+        if (last === null || e.ts > last)
+            last = e.ts;
+    }
+    // Period cards respect project/model filters but always use the calendar window.
+    const scoped = filterEvents(all, { projects: f.projects, models: f.models });
+    return {
+        generatedAt: now,
+        range: { from: f.from ?? null, to: f.to ?? null },
+        totals: { ...t, usd: c.usd, unknownTokens: c.unknownTokens, unknownModels: c.unknownModels, requests: events.length, sessions: sess.length },
+        costByKind: costByKind(events),
+        hours: byHourOfDay(events),
+        periods: {
+            today: periodCard("Today", scoped, startOfDay(now), now),
+            week: periodCard("This week", scoped, startOfWeek(now), now),
+            month: periodCard("This month", scoped, startOfMonth(now), now),
+        },
+        days: fillDays(byDay(events), f.from, f.to),
+        weeks: byWeek(events),
+        months: byMonth(events),
+        models: byModel(events),
+        projects: byProject(events),
+        sessions: sess.slice(0, sessionLimit),
+        first,
+        last,
+    };
+}

package/dist/cli.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { resolveProjectsDir } from "./discover.js";
+import { UsageStore } from "./store.js";
+import { buildSummary, startOfDay } from "./aggregate.js";
+import { footprintOf } from "./footprint.js";
+import { loadConfig } from "./config.js";
+import { modelLabel, pricing } from "./cost.js";
+import { c, fmtDuration, fmtLiters, fmtTokens, fmtUSD, fmtWh } from "./format.js";
+import { createApp } from "./server.js";
+import { watchProjects } from "./watch.js";
+import { statusLine } from "./statusline.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8"));
+const VERSION = pkg.version;
+function parseArgs(argv) {
+    const a = { mode: "dashboard", port: 4242, open: true, noCache: false };
+    for (let i = 0; i < argv.length; i++) {
+        const x = argv[i];
+        const next = () => argv[++i];
+        if (x === "statusline")
+            a.mode = "statusline";
+        else if (x === "--summary" || x === "summary")
+            a.mode = "summary";
+        else if (x === "--json" || x === "json")
+            a.mode = "json";
+        else if (x === "--help" || x === "-h")
+            a.mode = "help";
+        else if (x === "--version" || x === "-v")
+            a.mode = "version";
+        else if (x === "--dir")
+            a.dir = next();
+        else if (x.startsWith("--dir="))
+            a.dir = x.slice(6);
+        else if (x === "--port")
+            a.port = Number(next());
+        else if (x.startsWith("--port="))
+            a.port = Number(x.slice(7));
+        else if (x === "--no-open")
+            a.open = false;
+        else if (x === "--no-cache")
+            a.noCache = true;
+        else if (x === "--days")
+            a.days = Number(next());
+        else if (x.startsWith("--days="))
+            a.days = Number(x.slice(7));
+        else if (x === "--project")
+            (a.projects ??= []).push(next());
+        else if (x === "--model")
+            (a.models ??= []).push(next());
+        else {
+            console.error(`unknown argument: ${x}`);
+            a.mode = "help";
+        }
+    }
+    return a;
+}
+const HELP = `tokenburn ${VERSION} — watch your Claude Code tokens burn.
+
+usage:
+  tokenburn                 parse logs, start the dashboard, open the browser
+  tokenburn --summary       print a compact table to the terminal
+  tokenburn --json          dump aggregates as JSON (for scripting)
+  tokenburn statusline      one-line summary for Claude Code's status line
+
+options:
+  --dir <path>      logs directory (default: ~/.claude/projects or $CLAUDE_CONFIG_DIR)
+  --port <n>        dashboard port (default 4242, binds to 127.0.0.1 only)
+  --no-open         do not open the browser
+  --no-cache        ignore ~/.tokenburn/cache.json and re-read every file
+  --days <n>        only the last n days (summary/json)
+  --project <key>   filter by project folder key (repeatable)
+  --model <id>      filter by model id (repeatable)
+
+Costs are API-equivalent estimates. Water/energy numbers are rough and for fun.
+`;
+function filtersFrom(a) {
+    const f = {};
+    if (a.days)
+        f.from = startOfDay(Date.now() - (a.days - 1) * 86_400_000);
+    if (a.projects)
+        f.projects = a.projects;
+    if (a.models)
+        f.models = a.models;
+    return f;
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        /* ignore */
+    }
+}
+function printSummary(store, f) {
+    const cfg = loadConfig();
+    const s = buildSummary(store.events, f);
+    const fp = footprintOf(s.totals, cfg.footprint);
+    const row = (label, v) => `  ${c.gray(label.padEnd(14))} ${v}`;
+    const t = s.totals;
+    console.log("");
+    console.log(`  ${c.ember("🔥 tokenburn")} ${c.dim(`v${VERSION} · ${store.fileCount} files · ${store.projectsDir}`)}`);
+    console.log("");
+    console.log(`  ${c.bold(c.ember(fmtTokens(t.total)))} ${c.dim("tokens burned all time")}  ${c.bold(fmtUSD(t.usd))} ${c.dim("API-equivalent")}`);
+    console.log("");
+    console.log(row("input", fmtTokens(t.input)));
+    console.log(row("output", fmtTokens(t.output)));
+    console.log(row("cache write", fmtTokens(t.cacheWrite)));
+    console.log(row("cache read", fmtTokens(t.cacheRead)));
+    console.log(row("requests", t.requests.toLocaleString("en-US")));
+    console.log(row("sessions", t.sessions.toLocaleString("en-US")));
+    if (t.unknownModels.length)
+        console.log(row("unpriced", `${fmtTokens(t.unknownTokens)} tokens from ${t.unknownModels.join(", ")}`));
+    console.log("");
+    const period = (p) => `${p.label.padEnd(11)} ${fmtTokens(p.total).padStart(8)}  ${fmtUSD(p.usd).padStart(9)}  ${p.topModel ? c.dim(modelLabel(p.topModel)) : ""}`;
+    console.log(`  ${c.bold("period")}      ${"tokens".padStart(8)}  ${"api-eq".padStart(9)}  top model`);
+    for (const p of [s.periods.today, s.periods.week, s.periods.month])
+        console.log("  " + period(p));
+    console.log("");
+    console.log(`  ${c.bold("by model")}`);
+    for (const m of s.models.slice(0, 8))
+        console.log(`  ${modelLabel(m.key).padEnd(12)} ${fmtTokens(m.total).padStart(8)}  ${fmtUSD(m.usd).padStart(9)}  ${c.dim(m.requests.toLocaleString("en-US") + " req")}`);
+    console.log("");
+    console.log(`  ${c.bold("by project")}`);
+    for (const p of s.projects.slice(0, 8))
+        console.log(`  ${p.label.slice(0, 24).padEnd(24)} ${fmtTokens(p.total).padStart(8)}  ${fmtUSD(p.usd).padStart(9)}`);
+    console.log("");
+    console.log(`  ${c.bold("recent sessions")}`);
+    for (const x of s.sessions.slice(0, 6))
+        console.log(`  ${x.projectLabel.slice(0, 18).padEnd(18)} ${modelLabel(x.model).padEnd(10)} ${fmtDuration(x.durationMs).padStart(7)} ${fmtTokens(x.total).padStart(8)}  ${fmtUSD(x.usd).padStart(9)}`);
+    console.log("");
+    console.log(`  ${c.blue("💧 the lake")}  ${fp.water.text} ${c.dim(`(${fmtLiters(fp.liters)})`)}  ${c.dim("·")}  ⚡ ${fp.energy.text} ${c.dim(`(${fmtWh(fp.wh)})`)}`);
+    console.log(`  ${c.dim(fp.water.quip)}`);
+    console.log("");
+    console.log(c.dim(`  Costs are API-equivalent (pricing checked ${pricing.checked}); subscription users are not billed per token.`));
+    console.log(c.dim(`  Water & energy are rough third-party estimates, for fun. Edit factors in the dashboard settings.`));
+    if (store.warnings.malformedLines)
+        console.log(c.dim(`  Skipped ${store.warnings.malformedLines} malformed lines.`));
+    console.log("");
+}
+async function main() {
+    const a = parseArgs(process.argv.slice(2));
+    if (a.mode === "help")
+        return console.log(HELP);
+    if (a.mode === "version")
+        return console.log(VERSION);
+    const projectsDir = resolveProjectsDir({ dir: a.dir });
+    if (a.mode === "statusline") {
+        let stdin = null;
+        if (!process.stdin.isTTY) {
+            try {
+                stdin = fs.readFileSync(0, "utf8");
+            }
+            catch {
+                stdin = null;
+            }
+        }
+        process.stdout.write(statusLine(projectsDir, stdin) + "\n");
+        return;
+    }
+    if (!fs.existsSync(projectsDir)) {
+        console.error(`No Claude Code logs found at ${projectsDir}. Use --dir to point at them.`);
+        process.exit(1);
+    }
+    const store = new UsageStore(projectsDir);
+    const t0 = Date.now();
+    store.loadAll({ cache: !a.noCache });
+    const loadMs = Date.now() - t0;
+    if (a.mode === "json") {
+        const cfg = loadConfig();
+        const s = buildSummary(store.events, filtersFrom(a), Date.now(), 1000);
+        console.log(JSON.stringify({ version: VERSION, projectsDir, loadMs, warnings: store.warnings, pricing: { source: pricing.source, checked: pricing.checked }, summary: s, footprint: footprintOf(s.totals, cfg.footprint) }, null, 2));
+        return;
+    }
+    if (a.mode === "summary")
+        return printSummary(store, filtersFrom(a));
+    // dist/cli.js serves dist/web; `tsx src/cli.ts` (npm run dev) serves the built dist/web too.
+    const webDir = [path.join(here, "web"), path.join(here, "..", "dist", "web")].find((d) => fs.existsSync(path.join(d, "index.html"))) ??
+        path.join(here, "web");
+    if (!fs.existsSync(path.join(webDir, "index.html"))) {
+        console.error(c.ember("\n  The dashboard has not been built yet. Run: npm run build\n"));
+    }
+    let port = 0;
+    let app = null;
+    // If the port is busy (e.g. an older tokenburn is still running), try the next few.
+    for (let attempt = 0; attempt < 10; attempt++) {
+        const tryPort = a.port + attempt;
+        const candidate = createApp({ store, webDir, port: tryPort, version: VERSION });
+        try {
+            port = await candidate.listen();
+            app = candidate;
+            if (attempt > 0)
+                console.log(c.dim(`  port ${a.port} was busy, using ${port} instead`));
+            break;
+        }
+        catch (e) {
+            if (e?.code !== "EADDRINUSE")
+                throw e;
+        }
+    }
+    if (!app) {
+        console.error(`ports ${a.port}-${a.port + 9} are all busy. try --port <n>.`);
+        process.exit(1);
+    }
+    const url = `http://127.0.0.1:${port}`;
+    console.log(`\n  ${c.ember("🔥 tokenburn")} ${c.dim(`v${VERSION}`)}\n  ${c.dim(`read ${store.fileCount} files in ${loadMs}ms · ${fmtTokens(store.events.length)} requests`)}\n  ${c.bold(url)} ${c.dim("(127.0.0.1 only)")}\n  ${c.dim("watching " + projectsDir)}\n`);
+    const server = app;
+    const watcher = watchProjects(projectsDir, (file) => {
+        const added = store.loadFile(file);
+        if (added.length) {
+            server.broadcast(added);
+            store.saveCacheSoon();
+        }
+    });
+    if (a.open)
+        openBrowser(url);
+    let closing = false;
+    const shutdown = async () => {
+        if (closing)
+            return;
+        closing = true;
+        // Never hang on exit: if something refuses to close, leave anyway.
+        setTimeout(() => process.exit(0), 1500).unref();
+        await watcher.close();
+        store.saveCache();
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { defaultFootprint } from "./footprint.js";
+export function configDir(env = process.env) {
+    return env.TOKENBURN_HOME ?? path.join(os.homedir(), ".tokenburn");
+}
+export function configPath(env) {
+    return path.join(configDir(env), "config.json");
+}
+export function loadConfig(env) {
+    const base = { footprint: structuredClone(defaultFootprint), theme: "dark" };
+    try {
+        const raw = JSON.parse(fs.readFileSync(configPath(env), "utf8"));
+        return mergeConfig(base, raw);
+    }
+    catch {
+        return base;
+    }
+}
+export function mergeConfig(base, patch) {
+    const out = structuredClone(base);
+    if (patch && typeof patch === "object") {
+        const fp = patch.footprint;
+        if (fp && typeof fp === "object") {
+            if (typeof fp.whPerMillionOutputTokens === "number" && fp.whPerMillionOutputTokens >= 0)
+                out.footprint.whPerMillionOutputTokens = fp.whPerMillionOutputTokens;
+            if (typeof fp.litersPerKWh === "number" && fp.litersPerKWh >= 0)
+                out.footprint.litersPerKWh = fp.litersPerKWh;
+            if (fp.tokenWeights && typeof fp.tokenWeights === "object") {
+                for (const k of ["input", "output", "cacheWrite", "cacheRead"]) {
+                    const v = fp.tokenWeights[k];
+                    if (typeof v === "number" && v >= 0)
+                        out.footprint.tokenWeights[k] = v;
+                }
+            }
+        }
+        if (patch.theme === "dark" || patch.theme === "light")
+            out.theme = patch.theme;
+    }
+    return out;
+}
+export function saveConfig(cfg, env) {
+    const dir = configDir(env);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(configPath(env), JSON.stringify(cfg, null, 2) + "\n");
+}