claude-usage-dashboard 1.3.13 → 1.4.0

package/README.md

@@ -1,33 +1,49 @@
 # Claude Usage Dashboard
 
 [![npm version](https://img.shields.io/npm/v/claude-usage-dashboard)](https://www.npmjs.com/package/claude-usage-dashboard)
+[![npm downloads](https://img.shields.io/npm/dm/claude-usage-dashboard)](https://www.npmjs.com/package/claude-usage-dashboard)
 
-A self-hosted dashboard that visualizes your [Claude Code](https://claude.ai/code) usage by parsing local JSONL session logs from `~/.claude/projects/`.
+> Find out what your Claude Code subscription is actually worth in API costs.
+
+Your $200/month Max plan might be consuming **$15,000+/month** in API-equivalent value. This dashboard shows you exactly how much — per project, per session, per model. One command to start. Completely local. No data leaves your machine.
+
+```bash
+npx claude-usage-dashboard
+```
 
 ![Dashboard Screenshot](docs/screenshots/dashboard.png)
 
-## Features
+## What You'll See
+
+### Know What You're Spending
+
+Real-time projected API cost at your current usage rate — weekly and monthly. At 5% quota utilization, you might be burning through **$3,600/week** equivalent. The dashboard calculates this from your actual quota window, not estimates.
+
+### Track Your Quota in Real Time
 
-- **Token tracking** — Total tokens with breakdown by input, output, cache read, and cache write
-- **Cost estimation** — API cost equivalent at standard pricing
-- **Subscription quota** — Real-time utilization gauges (5-hour, 7-day, per-model) pulled from the Anthropic API with auto-detection of your plan tier. Includes projected API cost at 100% quota utilization (weekly and monthly), calculated using the exact quota window derived from the 7-day reset time. Shows the quota window date range for transparency. Date picker defaults to the current quota period on page load
-- **Token consumption trend** — Stacked bar chart with hourly, daily, weekly, or monthly granularity. Toggle between tokens and dollar view. Includes period summary with avg/min/max stats, active hours heatmap, and smart date range limits per granularity
-- **Model distribution** — Donut chart showing usage across Claude models
-- **Cache efficiency** — Visual breakdown of cache read, cache creation, and uncached requests
-- **Project distribution** — Horizontal bar chart comparing token usage across projects
-- **Session details** — Sortable, paginated table of every session with cost and duration
-- **Auto-refresh** — Dashboard polls every 30s for new usage data; quota refreshes every 2 minutes
-- **Persistent settings** — Date range, granularity, auto-refresh, and y-axis mode are remembered across sessions via localStorage
+Live utilization gauges for 5-hour, 7-day, and per-model quotas pulled directly from the Anthropic API. Auto-detects your plan tier (Pro / Max 5x / Max 20x). Never get throttled by surprise again.
+
+### Find What's Eating Your Tokens
+
+Per-project and per-session cost breakdowns show exactly where your usage goes. Sortable session table with cost, duration, and full token breakdown. Spot the expensive sessions instantly.
+
+### Understand Your Cache Efficiency
+
+You'll probably discover that ~95% of your tokens are cache reads at 1/10th the cost. The dashboard visualizes cache read vs. cache write vs. uncached requests so you can see how efficiently Claude is using context.
+
+### Everything Else
+
+Hourly/daily/weekly/monthly token trends · Dollar and token toggle · Model distribution across Opus/Sonnet/Haiku · Active hours heatmap · Auto-refresh (30s) · Persistent filters via localStorage · Dark theme
 
 ## Quick Start
 
-Run directly without installing:
+Run directly — no install, no config, no API keys needed:
 
 ```bash
 npx claude-usage-dashboard
 ```
 
-Open http://localhost:3000 in your browser.
+Open [localhost:3000](http://localhost:3000). That's it.
 
 ### From Source
 
@@ -46,15 +62,9 @@ PORT=8080 npx claude-usage-dashboard
 
 ## How It Works
 
-The dashboard reads Claude Code session logs from `~/.claude/projects/` — if you use Claude Code, these already exist on your machine. Logs are automatically re-read every 5 seconds, and new usage appears without restarting the server.
-
-Subscription quota data is fetched from the Anthropic API using your local OAuth credentials (`~/.claude/.credentials.json`). Your plan tier (Pro / Max 5x / Max 20x) is auto-detected from the same file.
-
-## Tech Stack
+Reads the JSONL session logs that Claude Code already writes to `~/.claude/projects/` on your machine. If you use Claude Code, the data is already there. Logs are re-read every 5 seconds — new usage appears without restarting.
 
-- **Backend:** Node.js, Express 5
-- **Frontend:** Vanilla JS (ES modules), D3.js v7
-- **Tests:** Mocha + Chai
+Subscription quota data is fetched from the Anthropic API using your existing local OAuth credentials. Your plan tier is auto-detected.
 
 ## Running Tests
 

package/bin/cli.cjs

@@ -1,8 +1,20 @@
 #!/usr/bin/env node
 'use strict';
-const { join } = require('path');
+const { join, resolve } = require('path');
 const { spawnSync } = require('child_process');
 
+// Parse CLI args before spawning server
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--sync-dir' && args[i + 1]) {
+    process.env.CLAUDE_DASH_SYNC_DIR = resolve(args[i + 1]);
+    i++;
+  } else if (args[i] === '--machine-name' && args[i + 1]) {
+    process.env.CLAUDE_DASH_MACHINE_NAME = args[i + 1];
+    i++;
+  }
+}
+
 const serverPath = join(__dirname, '..', 'server', 'index.js');
 const result = spawnSync(process.execPath, [serverPath], { stdio: 'inherit' });
 process.exit(result.status || 0);

package/bin/cli.js

@@ -1,2 +1,16 @@
-#!/usr/bin/env node
-import '../server/index.js';
+#!/usr/bin/env node
+import path from 'path';
+
+// Parse CLI args before importing server
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--sync-dir' && args[i + 1]) {
+    process.env.CLAUDE_DASH_SYNC_DIR = path.resolve(args[i + 1]);
+    i++;
+  } else if (args[i] === '--machine-name' && args[i + 1]) {
+    process.env.CLAUDE_DASH_MACHINE_NAME = args[i + 1];
+    i++;
+  }
+}
+
+await import('../server/index.js');

package/bin/cli.sh

@@ -1,11 +1,11 @@
-#!/bin/sh
-# Resolve symlinks to find the real script location
-SCRIPT="$0"
-while [ -L "$SCRIPT" ]; do
-  DIR="$(cd -P "$(dirname "$SCRIPT")" && pwd)"
-  SCRIPT="$(readlink "$SCRIPT")"
-  case "$SCRIPT" in /*) ;; *) SCRIPT="$DIR/$SCRIPT" ;; esac
-done
-DIR="$(cd -P "$(dirname "$SCRIPT")" && pwd)"
-
-exec node "$DIR/../server/index.js" "$@"
+#!/bin/sh
+# Resolve symlinks to find the real script location
+SCRIPT="$0"
+while [ -L "$SCRIPT" ]; do
+  DIR="$(cd -P "$(dirname "$SCRIPT")" && pwd)"
+  SCRIPT="$(readlink "$SCRIPT")"
+  case "$SCRIPT" in /*) ;; *) SCRIPT="$DIR/$SCRIPT" ;; esac
+done
+DIR="$(cd -P "$(dirname "$SCRIPT")" && pwd)"
+
+exec node "$DIR/../server/index.js" "$@"

package/package.json

@@ -1,40 +1,43 @@
-{
-  "name": "claude-usage-dashboard",
-  "version": "1.3.13",
-  "description": "Dashboard that visualizes Claude Code usage from local session logs",
-  "main": "server/index.js",
-  "bin": {
-    "claude-usage-dashboard": "bin/cli.cjs"
-  },
-  "files": [
-    "bin/",
-    "server/",
-    "public/"
-  ],
-  "scripts": {
-    "start": "node server/index.js",
-    "test": "mocha test/**/*.test.js --timeout 5000"
-  },
-  "keywords": [
-    "claude",
-    "usage",
-    "dashboard",
-    "token",
-    "cost"
-  ],
-  "author": "",
-  "license": "ISC",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ludengz/claude-usage-dashboard.git"
-  },
-  "type": "module",
-  "dependencies": {
-    "d3": "^7.9.0",
-    "express": "^5.2.1"
-  },
-  "devDependencies": {
-    "chai": "^6.2.2",
-    "mocha": "^11.7.5"
-  }
-}
+{
+  "name": "claude-usage-dashboard",
+  "version": "1.4.0",
+  "description": "Dashboard that visualizes Claude Code usage from local session logs",
+  "main": "server/index.js",
+  "bin": {
+    "claude-usage-dashboard": "bin/cli.cjs"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "public/"
+  ],
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "mocha test/**/*.test.js --timeout 5000"
+  },
+  "keywords": [
+    "claude",
+    "usage",
+    "dashboard",
+    "token",
+    "cost"
+  ],
+  "author": "",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ludengz/claude-usage-dashboard.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "d3": "^7.9.0",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "chai": "^6.2.2",
+    "mocha": "^11.7.5"
+  }
+}