@caius_kong/ccusage-dashboard 0.1.0 → 0.2.0

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/lib/index.html

@@ -53,6 +53,8 @@
   .range input{background:var(--panel-2);border:1px solid var(--border);color:var(--text);border-radius:6px;padding:5px 8px;font-size:12px;font-family:inherit}
   .range button{background:var(--panel-2);border:1px solid var(--border);color:var(--text);border-radius:6px;padding:5px 12px;cursor:pointer;font-size:12px}
   .range button:hover{border-color:var(--accent)}
+  .range button.active{background:var(--accent);border-color:var(--accent);color:#0d1117;font-weight:600}
+  .sessid{font-variant-numeric:tabular-nums;letter-spacing:.3px}
   .budget-band{margin:2px 0 14px;background:var(--panel-2);border-radius:8px;padding:12px 16px;display:flex;flex-direction:column;gap:8px}
   .budget-band .bl{display:flex;justify-content:space-between;font-size:13px;color:var(--muted)}
   .budget-band .bl b{color:var(--text)}
@@ -74,6 +76,7 @@
   <div class="tab" data-tab="week">This Week</div>
   <div class="tab" data-tab="month">This Month</div>
   <div class="tab" data-tab="range">Custom Range</div>
+  <div class="tab" data-tab="sessions">Sessions</div>
   <div class="tab-budget">
     <span class="budget-pill" id="budgetPill">budget …</span>
   </div>
@@ -104,12 +107,27 @@
 
 <div class="panel"><h2>Models <span class="tot" id="modelSum"></span></h2><div id="modelList"><div class="empty">loading…</div></div></div>
 
+<div class="panel" id="sessionsPanel" style="display:none">
+  <h2>Sessions <span class="tot" id="sessSum"></span>
+    <span class="pill" id="sessRange"></span>
+  </h2>
+  <div class="range" style="margin-bottom:12px">
+    <span class="pill">last</span>
+    <button data-sdays="7" class="sday">7d</button>
+    <button data-sdays="30" class="sday active">30d</button>
+    <button data-sdays="90" class="sday">90d</button>
+    <button data-sdays="365" class="sday">all</button>
+    <span class="pill" style="margin-left:auto" id="sessHint"></span>
+  </div>
+  <div id="sessionsList"><div class="empty">loading…</div></div>
+</div>
+
 <div class="hint">auto-refresh: today 15s · others 60s · costs in USD · <span id="lastUpd"></span></div>
 
 <script>
 const $=(id)=>document.getElementById(id);
-const tabs={today:{label:"Today",len:0},week:{label:"This Week",len:0},month:{label:"This Month",len:0},range:{label:"Custom Range",len:1}};
-let active="today", modelCtx=[];
+const tabs={today:{label:"Today",len:0},week:{label:"This Week",len:0},month:{label:"This Month",len:0},range:{label:"Custom Range",len:1},sessions:{label:"Sessions",len:0}};
+let active="today", modelCtx=[], sessDays=30;
 
 function fmtUsd(n){return "$"+(n==null?"–":Number(n).toFixed(2));}
 function fmtTok(n){
@@ -152,6 +170,32 @@ function applyBudget(month){
   const p=$("budgetPill");p.className="budget-pill "+cls;p.textContent=txt;
 }
 
+async function loadSessions(){
+  $("sessionsList").innerHTML='<div class="empty">loading sessions…</div>';
+  const data=await(await fetch(`/api/sessions?days=${sessDays}`)).json();
+  if(data.error)throw new Error(data.error);
+  renderSessions(data);
+}
+
+function renderSessions(data){
+  const list=data.sessions||[];
+  const total=data.total||0;
+  const sum=list.reduce((a,s)=>a+(s.cost||0),0);
+  $("sessSum").textContent=fmtUsd(sum);
+  $("sessRange").textContent=`${total} sessions · last ${sessDays===365?"year":sessDays+"d"}`;
+  if(!list.length){$("sessionsList").innerHTML='<div class="empty">no sessions in range</div>';return;}
+  $("sessionsList").innerHTML=list.map(s=>{
+    const label = s.hasCwd
+      ? `<span class="name">${esc(s.dirName||s.cwd)} <span class="pill sessid">${esc(s.id.slice(0,8))}</span></span>`
+      : `<span class="name muted">${esc(s.id.slice(0,8))}</span>`;
+    const last=(s.lastActivity||"").slice(0,10);
+    return `<div class="row">
+      <div class="row-top"><span>${label} <span class="pill">${esc(s.agent)}</span></span><span class="cost">${fmtUsd(s.cost)}</span></div>
+      <div class="toks">${last?`<span>${esc(last)}</span>`:""}<span title="input">in ${fmtTok(s.inputTokens)}</span><span title="output">out ${fmtTok(s.outputTokens)}</span><span title="cache read">read ${fmtTok(s.cacheReadTokens)}</span><span title="cache write">write ${fmtTok(s.cacheCreationTokens)}</span></div>
+    </div>`;
+  }).join("");
+}
+
 function applyCards(data){
   const total=data.totalCost||0;
   $("c1").innerHTML=fmtUsd(total)+(total?"<small> USD</small>":"");
@@ -263,15 +307,26 @@ document.querySelectorAll(".tab").forEach(t=>{
     t.classList.add("active");
     active=t.dataset.tab;
     $("rangeRow").style.display = active==="range"?"block":"none";
+    $("sessionsPanel").style.display = active==="sessions"?"block":"none";
     if(active==="range"){
       if(!$("fromDate").value){const e=new Date();$("toDate").value=e.toISOString().slice(0,10);const s=new Date();s.setDate(s.getDate()-6);$("fromDate").value=s.toISOString().slice(0,10);}
       rangeApply();
+    }else if(active==="sessions"){
+      loadSessions();
     }else{
       loadModels();
     }
   });
 });
 $("rangeGo").addEventListener("click",rangeApply);
+document.querySelectorAll(".sday").forEach(b=>{
+  b.addEventListener("click",()=>{
+    document.querySelectorAll(".sday").forEach(x=>x.classList.remove("active"));
+    b.classList.add("active");
+    sessDays=parseInt(b.dataset.sdays,10);
+    loadSessions();
+  });
+});
 
 tick();
 setInterval(tick,15000);

package/lib/server.py

@@ -94,7 +94,7 @@ def _node() -> str:
     return n
 
 BUDGET = 300.0  # monthly cap in USD (override via --budget or CCUSAGE_BUDGET)
-TTL = {"/api/today": 15, "/api/week": 60, "/api/month": 60, "/api/range": 120, "/api/trend": 120}
+TTL = {"/api/today": 15, "/api/week": 60, "/api/month": 60, "/api/range": 120, "/api/trend": 120, "/api/sessions": 60}
 
 
 def run_ccusage(args: list[str], ttl: float) -> dict:
@@ -193,6 +193,81 @@ def trend(days: int = 30) -> dict:
     return {"start": start.isoformat(), "end": end.isoformat(), "days": out}
 
 
+def sessions(since_days: int = 30) -> dict:
+    """Return ccusage's session report, with each session's cwd (projectPath) when
+    ccusage provides it. Data comes 100% from ccusage — we only re-shape it.
+    """
+    data = run_ccusage(
+        ["session", "--by-agent", "--json", "--offline"],
+        TTL["/api/sessions"],
+    )
+    rows = data.get("session") or []
+
+    cutoff = date.today() - timedelta(days=since_days)
+    out = []
+    for r in rows:
+        meta = r.get("metadata") or {}
+        sid = r.get("period")  # session id in ccusage's session report
+        last_activity = meta.get("lastActivity") or ""
+        # date filter by last activity
+        if last_activity:
+            try:
+                act_date = date.fromisoformat(last_activity[:10])
+            except ValueError:
+                act_date = None
+            if act_date is not None and act_date < cutoff:
+                continue
+        project_raw = meta.get("projectPath") or ""
+        cwd = _decode_cwd(project_raw)
+        dir_name = _basename(project_raw)
+        out.append(
+            {
+                "id": sid or "",
+                "agent": r.get("agent", "?"),
+                "cost": round(r.get("totalCost", 0) or 0, 4),
+                "inputTokens": r.get("inputTokens", 0),
+                "outputTokens": r.get("outputTokens", 0),
+                "cacheReadTokens": r.get("cacheReadTokens", 0),
+                "cacheCreationTokens": r.get("cacheCreationTokens", 0),
+                "lastActivity": last_activity,
+                "cwd": cwd,          # absolute-ish path, empty if ccusage didn't provide it
+                "dirName": dir_name,  # last path segment; empty if ccusage didn't provide
+                "hasCwd": bool(project_raw),
+            }
+        )
+    out.sort(key=lambda s: s["cost"], reverse=True)
+    return {"total": len(out), "sessions": out}
+
+
+def _decode_cwd(raw: str) -> str:
+    """Best-effort decode of ccusage's projectPath into a readable path.
+
+    pi's projectPath is a Claude-Code-style encoded dir name where '/' became '-'.
+    Example: '--Users-caius-kong-Documents-...-AutoTrans--' -> /Users/caius_kong/.../AutoTrans
+    """
+    if not raw:
+        return ""
+    return raw.replace("-", "/")
+
+
+def _basename(raw: str) -> str:
+    """Last path segment of projectPath as a readable dir name.
+
+    Works even for encoded paths (the trailing segment is unaffected by the
+    dash encoding except when the real dir name itself contains '-'s).
+    """
+    if not raw:
+        return ""
+    cleaned = raw.strip("/-\\")
+    if not cleaned:
+        return ""
+    parts = cleaned.replace("-", "/").split("/")
+    last = parts[-1] if parts else cleaned
+    # If the real dir name itself got dash-encoded (e.g. 'my-proj' -> 'my_proj'),
+    # we can't perfectly recover it; fall back to a reasonable label.
+    return last or cleaned
+
+
 class Handler(BaseHTTPRequestHandler):
     server_version = "ccusage-ui/0.2"
 
@@ -243,6 +318,10 @@ class Handler(BaseHTTPRequestHandler):
             days = max(1, min(366, int(params.get("days", "30"))))
             self._json(trend(days))
             return
+        elif path == "/api/sessions":
+            days = max(1, min(366, int(params.get("days", "30"))))
+            self._json(sessions(days))
+            return
         else:
             self._send(404, b"not found", "text/plain")
             return
@@ -276,6 +355,7 @@ def main() -> None:
             threading.Thread(target=warm_one, args=(lambda: run_ccusage(["daily", "--last", "1", "--json", "--offline"], TTL["/api/today"]),)),
             threading.Thread(target=warm_one, args=(lambda: run_ccusage(["weekly", "--last", "1", "--json", "--offline"], TTL["/api/week"]),)),
             threading.Thread(target=warm_one, args=(lambda: run_ccusage(["monthly", "--last", "1", "--json", "--offline"], TTL["/api/month"]),)),
+            threading.Thread(target=warm_one, args=(lambda: run_ccusage(["session", "--by-agent", "--json", "--offline"], TTL["/api/sessions"]),)),
             threading.Thread(target=warm_one, args=(lambda: trend(30),)),
         ]
         for t in threads:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caius_kong/ccusage-dashboard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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"
   }
-}
+}