@caius_kong/ccusage-dashboard 0.1.0 → 0.1.1

package/README.md

@@ -1,41 +1,87 @@
-# ccusage-ui
+<div align="center">
 
-A tiny, zero-dependency local dashboard for [ccusage](https://github.com/ccusage/ccusage).
-Shows **today / this week / this month / custom range** cost & tokens grouped by model,
-a **30-day cost trend chart**, and a **monthly budget alert** (default cap $300).
-Auto-refreshing, numbers straight from ccusage.
+# ccusage-dashboard
 
-All numbers come directly from `ccusage ... --json`, so the figures always match
-what ccusage reports (no own pricing tables, no drift).
+**A tiny local dashboard built specifically for [ccusage](https://github.com/ccusage/ccusage).**
 
-## Run
+> ⚠️ **This is not a re-implementation.** Every number you see comes straight from
+> `ccusage ... --json`. No own pricing tables, no re-parsing of session logs — the
+> dashboard is a thin view over ccusage's own accurate cost engine. If `ccusage`
+> says it, this dashboard shows it.
+
+</div>
+
+---
+
+## What is this?
+
+[ccusage](https://github.com/ccusage/ccusage) is a powerful CLI that analyzes coding-agent
+token usage & cost from local data — accurate, but terminal-only and hard to *watch*.
+
+**ccusage-dashboard puts a live web UI on top of it**: today / this week / this month /
+custom-range cost grouped by model, a 30-day cost trend, and a monthly budget alert.
+It auto-refreshes while you work, so you can *see* spend happen instead of running reports.
+
+Because it shells out to `ccusage` for every number, **cost estimates are always identical
+to what ccusage itself reports** — the source you already trust.
+
+## One-command install & start
 
 ```bash
-python3 server.py                # → http://127.0.0.1:8799
-python3 server.py --port 9000     # different port
-python3 server.py --budget 500    # change monthly budget cap (default 300)
-python3 server.py --ccusage-path /path/to/ccusage   # use a specific binary
-./run.sh                         # opens the browser automatically
+npx @caius_kong/ccusage-dashboard
 ```
 
-Requires Python 3.8+ (stdlib only). The server resolves a fast local ccusage
-(npm/bun cache → PATH → `npx`), warms caches synchronously (~3s), then serves,
-so the first page load is instant rather than a 7s cold wait. Use `--no-warm`
-to skip that and accept a slower first load.
+That's it. npx downloads the package (including its own `ccusage` dependency),
+starts a local server on `http://127.0.0.1:8799`, and opens your browser.
+
+> Requirements: **Node.js** (for the launcher) and **Python 3.8+** (for the server).
+> On macOS: `brew install python3`. No other installs, no build step, no config.
+
+### CLI options
+
+```bash
+npx @caius_kong/ccusage-dashboard --port 9000     # change port
+npx @caius_kong/ccusage-dashboard --budget 500    # monthly budget cap (default $300)
+npx @caius_kong/ccusage-dashboard --no-warm       # skip 3s startup warm-up
+CCUSAGE_UI_NO_OPEN=1 npx @caius_kong/ccusage-dashboard   # don't auto-open browser
+```
 
-## Endpoints
+## What it shows
 
-| Path | What it returns |
+| | |
 |---|---|
-| `/` | the dashboard |
-| `/api/today` | today's totals + per-model breakdown (cached 15s) |
-| `/api/week` | this week's totals + per-model breakdown (cached 60s) |
-| `/api/month` | this month's totals per-model, plus `budget` + `budgetUsedPct` (cached 60s) |
-| `/api/range?from=YYYY-MM-DD&to=YYYY-MM-DD` | aggregated totals for a date range (cached 120s) |
-| `/api/trend?days=30` | per-day cost series for the last N days (2m cache, capped 366) |
-| `/api/health` | liveness check incl. current budget |
-
-## Files
-
-- `server.py` — Python stdlib HTTP server; resolves a local ccusage, shells out with `--json --offline`, warms caches on boot
-- `index.html` — single-file dashboard (no build step, no CDN)
+| **Today / This Week / This Month / Custom Range** | totals + tokens + cache breakdown |
+| **By model** | per-model cost, % of total, in/out/cache-read/cache-write tokens |
+| **30-day trend** | daily cost bar chart (hover for values, weekends marked) |
+| **Budget alert** | monthly cap (default $300) — green <80%, yellow <100%, red ≥100% |
+
+All costs in USD. Auto-refresh: today every 15s, others every 60s.
+
+## How it works
+
+```
+Browser (index.html)
+   │  fetch /api/...  (auto-refresh)
+   ▼
+server.py  (Python stdlib, zero deps)
+   │  spawns:  ccusage daily/monthly/weekly ... --json --offline
+   ▼
+ccusage   (bundled dependency — the real cost engine)
+```
+
+- `lib/server.py` — Python stdlib HTTP server. Resolves a local ccusage
+  (bundled dep → PATH → npx cache), warms caches on boot (~3s), then serves instant responses.
+- `lib/index.html` — single-file dashboard. No build step, no CDN.
+- `bin/ccusage-ui.js` — Node launcher (finds python3, starts server, opens browser).
+
+## Local development
+
+```bash
+python3 lib/server.py --budget 300    # run server directly from the repo
+# or
+node bin/ccusage-ui.js                # same as the npx experience
+```
+
+## License
+
+MIT © Caius Kong

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caius_kong/ccusage-dashboard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "One-command local dashboard for ccusage: today/week/month/custom cost by model, 30-day trend, monthly budget alert. Numbers straight from ccusage.",
   "license": "MIT",
   "type": "commonjs",
@@ -38,4 +38,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}