# 📊 Claude Code Usage Dashboard — Project Plan

## Vision
A premium, self-hosted web dashboard for visualizing Claude Code usage metrics.
Think: **Linear meets Vercel's analytics** — clean, data-dense, beautiful.

**Port:** `7733` (unused, memorable: "77" = CC in hex-ish, "33" = code)

---

## 🎯 Data Sources (from ccusage JSON)
| Endpoint | Source Command | Data |
|----------|---------------|------|
| `/api/daily` | `ccusage daily --json` | Daily token usage + costs |
| `/api/monthly` | `ccusage monthly --json` | Monthly aggregation |
| `/api/sessions` | `ccusage session --json` | Per-session breakdown |
| `/api/projects` | `ccusage daily --instances --json` | Per-project breakdown |

### Available Projects
- `bounce-stats` (main project — $370+ alone)
- `clawd` (this workspace)
- `gekkostay`
- `tlxstats`
- `firstpeak-ventures`
- `fdv-comparator`
- `clawd/scripts`

### Available Models
- `claude-opus-4-6` (97.7% of cost — $583.74)
- `claude-haiku-4-5` ($8.94)
- `claude-sonnet-4-5` ($5.02)
- `claude-opus-45` (legacy, ~$0)

---

## 🏗️ Architecture

### Stack
- **Backend:** Python + FastAPI (lightweight, already on the NUC)
- **Frontend:** Single HTML file with embedded CSS/JS (zero build step)
- **Charts:** Chart.js (CDN, lightweight, beautiful)
- **Data refresh:** On-demand via API (ccusage reads local files, <2s)
- **Service:** systemd unit for auto-start

### Why this stack?
- No npm build pipeline needed
- Single `pip install fastapi uvicorn` 
- Deploys in seconds
- Chart.js handles all the viz needs without React/Next overhead

---

## 🎨 Design System

### Theme
**Dark mode (default) / Light mode toggle**

Dark:
- Background: `#0a0a0f` (near-black with blue tint)
- Cards: `#13131a` with `1px border rgba(255,255,255,0.06)`
- Accent: `#6366f1` (indigo-500) — used for primary metrics, active states
- Success/Up: `#10b981` (emerald-500)
- Warning: `#f59e0b` (amber-500)
- Danger/Expensive: `#ef4444` (red-500)
- Text primary: `#f1f5f9`
- Text secondary: `#94a3b8`

Light:
- Background: `#fafbfc`
- Cards: `#ffffff` with subtle shadow
- Same accent colors, slightly darker variants

### Typography
- Font: `Inter` (Google Fonts) — clean, modern, excellent for data
- Monospace numbers: `JetBrains Mono` for costs/tokens
- Sizes: 13px body, 11px labels, 24px hero numbers, 48px main KPI

### Card Design
```
╭─────────────────────────────╮
│ 📊 Title           ● ● ●   │
│                              │
│  $597.70                     │  ← Hero number (48px, mono)
│  Total Estimated Cost        │  ← Subtitle (13px, muted)
│                              │
│  ████████████░░░ 82%         │  ← Optional progress bar
│  ▲ +12.3% vs last week       │  ← Trend indicator
╰─────────────────────────────╯
```

### Emoji Icon System
| Section | Emoji | Meaning |
|---------|-------|---------|
| Total Cost | 💰 | Money saved |
| Tokens | 🔤 | Token consumption |
| Sessions | 💬 | Conversations |
| Projects | 📁 | Project breakdown |
| Models | 🤖 | Model distribution |
| Daily Trend | 📈 | Usage over time |
| Cache | ⚡ | Cache efficiency |
| Peak Usage | 🔥 | Heaviest days |
| Savings | 💎 | Pro Max value |

---

## 📐 Layout (6 sections)

### 1. 🏠 Hero Banner (top)
Full-width gradient strip with the main KPIs:

```
┌──────────────────────────────────────────────────────────────────┐
│  🔮 Claude Code Dashboard                    🌙/☀️  ⟳ Refresh  │
│                                                                  │
│  💰 $597.70        🔤 958M tokens      💬 47 sessions           │
│  Total Est. Cost    Total Tokens        Active Sessions          │
│                                                                  │
│  💎 You saved $597.70 this month with Pro Max                   │
└──────────────────────────────────────────────────────────────────┘
```

### 2. 📈 Daily Usage Chart (main)
**Type:** Area chart with gradient fill
- X-axis: dates
- Y-axis (left): tokens
- Y-axis (right): cost ($)
- Hover: detailed tooltip with all token types + cost
- Stacked areas by model (Opus = indigo, Haiku = emerald, Sonnet = amber)
- Toggle: Tokens / Cost view

### 3. 🤖 Model Distribution (left card)
**Type:** Donut chart
- Opus 4.6: 97.7% — indigo
- Haiku 4.5: 1.5% — emerald
- Sonnet 4.5: 0.8% — amber
- Center: total cost
- Legend below with cost per model

### 4. 📁 Project Breakdown (right card)
**Type:** Horizontal bar chart (sorted by cost)
- bounce-stats: $370.97 ████████████████
- clawd: $XXX       ████████
- gekkostay: $XX     ███
- etc.
- Clean project names (strip `/home/gekko/` prefix)
- Click to drill down (filter all charts to that project)

### 5. ⚡ Cache Efficiency (bottom-left)
**Type:** Stats card + mini bar chart
- Cache Read: 932M tokens (97.3% of total)
- Cache Creation: 24.6M tokens
- Direct Input: 178K tokens
- Direct Output: 624K tokens
- **Efficiency Score:** visual gauge showing cache hit ratio
- This is interesting because high cache = cheaper per effective token

### 6. 🔥 Top Sessions Table (bottom-right)
**Type:** Sortable data table
- Columns: Project | Session | Last Active | Tokens | Cost | Models
- Sorted by cost desc
- Clickable rows → expand to show model breakdown
- Search/filter by project name
- Paginated (10 per page)

---

## 📱 Responsive Design
- **Desktop (>1200px):** 2-column grid for sections 3-6
- **Tablet (768-1200px):** single column, cards stack
- **Mobile (<768px):** full-width cards, compact numbers

---

## ⚙️ Features

### Must Have (v1)
- [ ] Dark/Light theme toggle with localStorage persistence
- [ ] Auto-refresh toggle (every 5 min) + manual refresh button
- [ ] All 6 sections above
- [ ] Responsive layout
- [ ] Date range picker (quick: 7d, 14d, 30d, all)
- [ ] Project filter (dropdown)
- [ ] Loading skeletons while data fetches
- [ ] Smooth number animations on load

### Nice to Have (v2)
- [ ] Export to PNG/PDF
- [ ] Cost alerts (notify if daily cost exceeds threshold)
- [ ] Session timeline (Gantt-like view)
- [ ] Comparison mode (this week vs last week)
- [ ] Keyboard shortcuts (T = theme, R = refresh)

---

## 🚀 Implementation Plan

### Phase 1: Backend (30 min)
- [ ] Create `~/clawd/projects/ccusage-dashboard/`
- [ ] FastAPI app with 4 API endpoints
- [ ] Each endpoint shells out to `npx ccusage@18.0.5 <cmd> --json`
- [ ] Simple caching (5 min TTL) to avoid repeated ccusage calls
- [ ] CORS headers for local dev

### Phase 2: Frontend Shell (45 min)
- [ ] Single `index.html` with embedded CSS
- [ ] CSS custom properties for theming
- [ ] Grid layout with all 6 sections
- [ ] Theme toggle with transition animation
- [ ] Loading states

### Phase 3: Charts & Data (45 min)
- [ ] Wire up Chart.js
- [ ] Daily area chart with model stacking
- [ ] Model donut chart
- [ ] Project bar chart
- [ ] Cache efficiency gauge
- [ ] Number formatting (K, M, B for tokens)

### Phase 4: Interactivity (30 min)
- [ ] Date range picker
- [ ] Project filter → re-renders all charts
- [ ] Session table with sort/search
- [ ] Auto-refresh
- [ ] Smooth transitions

### Phase 5: Deploy (15 min)
- [ ] systemd unit file
- [ ] Enable + start service
- [ ] Verify on port 7733
- [ ] Test from browser

---

## 📦 File Structure
```
~/clawd/projects/ccusage-dashboard/
├── app.py              # FastAPI backend
├── static/
│   └── index.html      # Full frontend (embedded CSS/JS)
├── requirements.txt    # fastapi, uvicorn
├── ccusage-dashboard.service  # systemd unit
└── README.md
```

---

---

## 🔮 Future: Venice/OpenClaw DIEM Tracking (v2)

**Idea:** Add a Venice AI panel to the dashboard showing DIEM burn rate.

### What's available
- **Venice API** (`GET /api/v1/api_keys/rate_limits`) — returns live DIEM balance, tier, rate limits per model. Costs zero inference (plain HTTP call, no LLM).
- **No local token logs** — OpenClaw doesn't persist per-request token usage like Claude Code's JSONL files.

### Implementation plan
1. **Cron script** (Python, no LLM) — poll Venice API every hour, save snapshot to `~/clawd/data/diem/daily/YYYY-MM-DD.json`
2. **New API endpoint** (`/api/venice`) — serves historical DIEM snapshots + live balance
3. **Dashboard panel** — DIEM balance gauge, daily burn rate chart, per-model rate limits table
4. Over time, the hourly snapshots build a picture of daily/weekly DIEM consumption patterns

### Limitation
No per-conversation or per-model cost breakdown from Venice (unlike ccusage for Claude Code). Only aggregate DIEM balance over time.

---

## Estimated Total: ~3 hours via Claude Code (FREE on Pro Max)
