@zhangferry-dev/tokendash 1.3.0 → 1.4.2

package/README.md

@@ -1,23 +1,50 @@
 # tokendash
 
-A beautiful, local web dashboard for visualizing your Claude Code, Codex, and OpenClaw token usage statistics.
+A beautiful, local web dashboard for visualizing your Claude Code, Codex, OpenClaw, and OpenCode token usage statistics.
 
 It runs locally and parses token usage data directly from local session files, presenting it in a clean, interactive React dashboard. No external CLI dependencies required.
 
-![Product Screenshoot](resources/product_screenshoot.png)
+![Web Dashboard](resources/product_screenshoot.png)
 
 ## Features
 
-- **Multi-Agent Support:** View usage for Claude Code, Codex, and OpenClaw.
-- **Direct JSONL Parsing:** Reads `~/.claude/projects/` JSONL files directly — no `ccusage` CLI dependency, 100x faster data loading.
+- **Multi-Agent Support:** View usage for Claude Code, Codex, OpenClaw, and OpenCode.
+- **Direct JSONL Parsing:** Reads local session files directly — 100x faster data loading.
 - **Detailed Metrics:** Track total tokens, cost (USD), active days, cache hit rates, and output/input ratio.
-- **Code Analytics:** Visualize code change trends, tool call frequency, and productivity KPIs (Claude Code & OpenClaw only).
-- **Pricing Transparency:** Toggle Cost metric to see per-model pricing formula and rates.
+- **Today by Hour:** 24-hour token consumption panel showing hourly breakdown for the current day.
+- **Code Analytics:** Visualize code change trends, tool call frequency, and productivity KPIs.
 - **Interactive Charts:** Bar/line/area charts with tooltips, model breakdowns, and time range filtering.
 - **24-Hour Heatmap:** Activity distribution by hour and day of week, with timezone awareness.
 - **Model & Project Distribution:** See which models and projects drive your usage.
 - **Persistent Filters:** Your selected time range, project, and metric mode are saved automatically.
-- **Test Coverage:** Unit tests (Vitest) and E2E tests (Playwright) for reliability.
+
+## macOS Menu Bar App
+
+TokenDash ships as a native macOS menu-bar-only application — no Dock icon, no window clutter. It lives quietly in your status bar and gives you instant access to your AI token usage at a glance.
+
+![macOS Menu Bar](resources/product_menu.png)
+
+**Status Bar Badge**
+- Displays real-time token count (e.g. `1.2K`, `32.0M`) directly in the macOS status bar
+- Updates every 5 seconds automatically
+- Shows cost and cache hit rate in the tooltip on hover
+- Resilient badge: transient network or data errors won't clear your existing badge value
+
+**Popover Dashboard**
+- Click the status bar icon to open a compact popover with today's full breakdown:
+  - Total tokens, input/output/cache metrics at a glance
+  - Hourly consumption bar chart with peak value highlight
+  - Agent filter dropdown (show only Claude Code, Codex, etc.)
+  - Settings: launch at login, check for updates, quit
+- The popover syncs rendered totals back to the status bar badge for maximum accuracy
+
+**Native Integration**
+- Written in Swift (`trayHelper.swift`) for macOS 14+ compatibility
+- Menu-bar-only (`LSUIElement: true`) — no Dock icon, runs silently in the background
+- Dark mode support with automatic theme switching
+- Custom app icon
+- Distributed as a standard macOS DMG installer
+- Port auto-detection with fallback — works even if port 3456 is already in use
 
 ## Requirements
 
@@ -43,6 +70,10 @@ By default, the backend server runs on port `3456`. When running the production
 
 During development (`npm run dev`), Vite starts a separate development server on port `5173` with hot-module replacement. You should access the dashboard at `http://localhost:5173` while developing.
 
+### macOS Menu Bar App
+
+Download the latest `TokenDash-<version>-arm64.dmg` from [GitHub Releases](https://github.com/zhangferry/tokendash/releases). Open the DMG and drag TokenDash to your Applications folder. Launch it and the status bar icon appears immediately — no setup needed.
+
 ### Command Line Options
 
 ```bash
@@ -87,21 +118,10 @@ If you want to contribute or modify the dashboard locally:
 
 - **Frontend:** React 19, Recharts, Tailwind CSS (via Vite plugin), built with Vite.
 - **Backend:** Express, TypeScript.
-- **Data Source:** All agent data is parsed directly from local session files (`~/.claude/projects/`, `~/.codex/sessions/`). No external CLI dependencies.
+- **Data Source:** All agent data is parsed directly from local session files (`~/.claude/projects/`, `~/.codex/sessions/`) and OpenCode's SQLite database (`~/.local/share/opencode/opencode.db`). No external CLI dependencies.
 - **Caching:** Persistent disk cache (`/tmp/tokendash-cache/`) with stale-while-revalidate pattern for snappy UI updates.
 - **Testing:** Vitest (unit), Playwright (E2E). Run with `npm test` and `npm run test:e2e`.
-
-## Changelog
-
-### v1.2.0
-- **Replaced `ccusage` CLI** with direct JSONL parser — data loads in 1-2ms instead of 12-30s
-- **Added code analytics** — code change trend, tool call trend, daily KPIs
-- **Added persistent disk cache** with stale-while-revalidate pattern
-- **Fixed heatmap** — cost metric now shows real data (was always $0)
-- **Fixed timezone handling** — correct date/hour grouping for non-UTC users
-- **Added pricing info popup** — shows per-model pricing formula in Cost mode
-- **Added test suite** — 49 unit tests + 6 E2E tests
-- **Layout improvements** — model trend bar chart, side-by-side analytics panels
+- **CI:** GitHub Actions pipeline for automated testing on every push and PR.
 
 ## License
 

package/bin/tokendash.js

@@ -1,2 +1,6 @@
 #!/usr/bin/env node
-import "../dist/server/index.js";
+import { main } from "../dist/server/index.js";
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});