claude-session-dashboard 0.5.0 → 0.5.1

package/README.md

@@ -0,0 +1,218 @@
+# Claude Session Dashboard
+
+[![CI](https://github.com/dlupiak/claude-session-dashboard/actions/workflows/ci.yml/badge.svg)](https://github.com/dlupiak/claude-session-dashboard/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/dlupiak/claude-session-dashboard/actions/workflows/codeql.yml/badge.svg)](https://github.com/dlupiak/claude-session-dashboard/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/dlupiak/claude-session-dashboard)](https://securityscorecards.dev/viewer/?uri=github.com/dlupiak/claude-session-dashboard)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12094/badge)](https://www.bestpractices.dev/projects/12094)
+[![codecov](https://codecov.io/gh/dlupiak/claude-session-dashboard/graph/badge.svg)](https://codecov.io/gh/dlupiak/claude-session-dashboard)
+[![Socket](https://img.shields.io/badge/Socket-secured-green?logo=socket.dev)](https://socket.dev/npm/package/claude-session-dashboard)
+[![npm version](https://img.shields.io/npm/v/claude-session-dashboard)](https://www.npmjs.com/package/claude-session-dashboard)
+[![npm downloads](https://img.shields.io/npm/dm/claude-session-dashboard)](https://www.npmjs.com/package/claude-session-dashboard)
+[![Node.js](https://img.shields.io/node/v/claude-session-dashboard)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A read-only, local observability dashboard for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) sessions. Scans your `~/.claude` directory to visualize session history, tool usage, token consumption, cost estimates, and activity trends -- all without sending data anywhere.
+
+```bash
+npx claude-session-dashboard
+```
+
+## Why?
+
+Claude Code stores all session data locally in `~/.claude/projects/`, but there is no built-in way to browse, search, or analyze past sessions. As you accumulate hundreds of sessions across dozens of projects, questions start piling up:
+
+- How many tokens did that refactoring session actually use?
+- Which tools does Claude call most often in my codebase?
+- How much am I spending per project, per day, per model?
+- Is the context window filling up mid-session?
+- When am I most active -- mornings or late nights?
+
+This dashboard gives you answers. It reads your local session files, parses the JSONL logs, and presents everything in a fast, searchable web UI that runs entirely on your machine.
+
+## Features
+
+**Session browsing and search**
+- Full-text search across session names, projects, and branches
+- Filter by status (active / completed), project, model, and date range
+- Sortable columns with pagination
+- Active session indicator with real-time status polling
+
+**Session detail view**
+- Context window utilization breakdown (input, output, cache read, cache creation)
+- Tool usage frequency and duration statistics
+- Agent dispatch history with nested tool calls
+- Gantt-style timeline chart with zoom controls for tool calls, agent runs, and skill invocations
+- Per-session and per-agent cost estimates with per-model and per-category breakdowns
+
+![Session Detail](screenshots/session-detail-full.png)
+
+**Analytics and stats**
+- GitHub-style contribution heatmap showing token usage intensity over the past year
+- Token usage over time -- stacked area chart with daily/weekly toggle, top 5 models + "Other"
+- Model usage distribution across all sessions
+- Hourly activity distribution chart
+- Aggregate metrics: total sessions, messages, tokens, estimated cost
+
+![Stats Overview](screenshots/stats-overview-full.png)
+
+**Per-project analytics**
+- Dedicated "Projects" tab with sortable table
+- Sessions, messages, tokens, and duration aggregated per project
+- Drill-down links to filtered session lists
+
+![Per-Project Analytics](screenshots/stats-projects.png)
+
+**Cost estimation**
+- Configurable API pricing per model (Claude Sonnet 4, Opus 4, Haiku, etc.)
+- Subscription tier support (Free, Pro, Max 5x/20x) with appropriate rate adjustments
+- Settings persisted to `~/.claude-dashboard/settings.json`
+
+![Settings Page](screenshots/settings-page.png)
+
+**Data export**
+- Export stats and session data in CSV or JSON format
+- Four export formats: session summaries, model usage, daily activity, project analytics
+- Client-side export -- no server round-trip needed
+
+**Real-time monitoring**
+- Active sessions badge in the sidebar with 3-second status polling
+- Active session banner on detail pages with adaptive refresh intervals
+- Automatic data refresh for in-progress sessions
+
+**Privacy mode**
+- Toggle to anonymize project names, file paths, branch names, and usernames
+- Analytics data anonymized consistently across all views
+- Safe for screenshot sharing and presentations
+
+## Quick Start
+
+### Using npx (recommended)
+
+```bash
+npx claude-session-dashboard
+```
+
+### Using npm (global install)
+
+```bash
+npm install -g claude-session-dashboard
+claude-dashboard
+```
+
+### From source
+
+```bash
+git clone https://github.com/dlupiak/claude-session-dashboard.git
+cd claude-session-dashboard/apps/web
+npm install
+npm run build
+npm start
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+### Updating
+
+**npx** — always fetches the latest published version automatically. No action needed.
+
+**Global install** — check your current version and update:
+
+```bash
+claude-dashboard --version           # see current version
+npm install -g claude-session-dashboard@latest
+```
+
+**From source** — pull the latest changes and rebuild:
+
+```bash
+cd claude-session-dashboard
+git pull
+cd apps/web && npm install && npm run build
+```
+
+## CLI Options
+
+```
+  -p, --port <number>   Port to listen on (default: 3000)
+  --host <hostname>     Host to bind to (default: localhost)
+  -o, --open            Open browser after starting
+  -v, --version         Show version number
+  -h, --help            Show this help message
+```
+
+> **Note:** The dashboard runs entirely on localhost and only reads files from `~/.claude`. It never modifies any Claude Code data and never sends data over the network.
+
+## Tech Stack
+
+- [TanStack Start](https://tanstack.com/start) -- SSR framework on Vite
+- [TanStack Router](https://tanstack.com/router) -- file-based routing with type-safe search params
+- [TanStack Query](https://tanstack.com/query) -- data fetching with caching and automatic background refetch
+- [Tailwind CSS v4](https://tailwindcss.com/) -- utility-first styling with CSS-first configuration
+- [Recharts](https://recharts.org/) -- composable charting library for timeline, heatmap, and stats visualizations
+- [Zod](https://zod.dev/) -- runtime validation for server functions and URL params
+- Node.js >= 18
+
+## Project Structure
+
+```
+apps/web/src/
+  routes/                        # File-based routes (TanStack Router)
+    _dashboard/
+      sessions/
+        index.tsx                # Sessions list page
+        $sessionId.tsx           # Session detail page
+      stats.tsx                  # Stats + per-project analytics page
+      settings.tsx               # Settings page
+  features/                      # Vertical Slice Architecture
+    sessions/                    # Session list, filters, active badge
+    session-detail/              # Session detail, timeline, context window
+    stats/                       # Activity chart, heatmap, token trends, model usage
+    project-analytics/           # Per-project aggregated metrics
+    cost-estimation/             # Cost calculation and display
+    settings/                    # Subscription tier, pricing editor
+    privacy/                     # Privacy mode toggle and anonymization
+  lib/
+    scanner/                     # Filesystem scanner for ~/.claude
+    parsers/                     # JSONL session file parsers
+    cache/                       # Persistent disk cache (heatmap data)
+    utils/                       # Formatting, export utilities
+  components/                    # Shared UI components (ExportDropdown, etc.)
+```
+
+## How It Works
+
+1. **Scanning** -- The server reads `~/.claude/projects/` to discover all session `.jsonl` files. An mtime-based cache avoids re-parsing unchanged files.
+2. **Parsing** -- Session files are parsed to extract metadata (project, branch, duration, model), tool calls, agent dispatches, token usage, and errors.
+3. **Server Functions** -- TanStack Start server functions (`createServerFn`) expose parsed data to the client via type-safe RPC. All file I/O stays on the server.
+4. **React Query** -- The UI fetches data through React Query with automatic background refetch for live updates. Active sessions use adaptive polling intervals.
+5. **Caching** -- Parsed session summaries and heatmap data are cached in memory (mtime-based invalidation) and on disk (`~/.claude-dashboard/cache/`) for fast startup.
+
+## Development
+
+```bash
+cd apps/web
+
+npm run dev          # Dev server on localhost:3000
+npm run build        # Production build
+npm run typecheck    # TypeScript type checking
+npm run lint         # ESLint
+npm run test         # Unit tests (Vitest)
+npm run e2e          # End-to-end tests (Playwright)
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and conventions. Check [good first issues](https://github.com/dlupiak/claude-session-dashboard/labels/good%20first%20issue) for beginner-friendly tasks.
+
+If you find this project useful, consider giving it a star -- it helps others discover it.
+
+## Links
+
+- [GitHub](https://github.com/dlupiak/claude-session-dashboard)
+- [npm](https://www.npmjs.com/package/claude-session-dashboard)
+- [Issues](https://github.com/dlupiak/claude-session-dashboard/issues)
+- [Discussions](https://github.com/dlupiak/claude-session-dashboard/discussions)
+
+## License
+
+MIT

package/dist/server/assets/{project-analytics.api-6b5TIBNn.js → project-analytics.api-B6FCr_cZ.js}

@@ -1,5 +1,5 @@
 import { c as createServerRpc } from "./createServerRpc-D_-6bKnO.js";
-import { s as scanAllSessions } from "./session-scanner-CECpfGFh.js";
+import { a as scanAllSessions } from "./session-scanner-GwtZjgds.js";
 import { c as createServerFn } from "../server.js";
 import "node:fs";
 import "node:path";

package/dist/server/assets/{session-scanner-CECpfGFh.js → session-scanner-GwtZjgds.js}

@@ -94,7 +94,7 @@ async function getActiveSessions() {
   return all.filter((s) => s.isActive);
 }
 export {
-  scanAllSessionsWithPaths as a,
+  scanAllSessions as a,
   getActiveSessions as g,
-  scanAllSessions as s
+  scanAllSessionsWithPaths as s
 };

package/dist/server/assets/{sessions.api-CQ-Lrk5S.js → sessions.api-BHD6I0Q1.js}

@@ -1,6 +1,6 @@
 import { c as createServerRpc } from "./createServerRpc-D_-6bKnO.js";
 import { z } from "zod";
-import { s as scanAllSessions, g as getActiveSessions } from "./session-scanner-CECpfGFh.js";
+import { a as scanAllSessions, g as getActiveSessions } from "./session-scanner-GwtZjgds.js";
 import { c as createServerFn } from "../server.js";
 import "node:fs";
 import "node:path";

package/dist/server/assets/{stats.api-tIZqhk4B.js → stats.api-B9I1HZQw.js}

@@ -4,7 +4,7 @@ import { g as getStatsPath, p as parseDetail } from "./session-parser-DKZZMuh6.j
 import * as path from "node:path";
 import * as os from "node:os";
 import { z } from "zod";
-import { a as scanAllSessionsWithPaths } from "./session-scanner-CECpfGFh.js";
+import { s as scanAllSessionsWithPaths } from "./session-scanner-GwtZjgds.js";
 import { c as createServerFn } from "../server.js";
 import "node:fs/promises";
 import "node:readline";

package/dist/server/server.js

@@ -89,33 +89,33 @@ async function getStartManifest(matchedRoutes) {
     injectedHeadScripts
   };
 }
-const manifest = { "39e65590d2bc41f653f54a9b6a9e0a72f185da275304c0a4a595d811cf185572": {
-  functionName: "getProjectAnalytics_createServerFn_handler",
-  importer: () => import("./assets/project-analytics.api-6b5TIBNn.js")
-}, "44af69d3bfcf3ec46fffb3f297d2b12cd7fe4db36c654b8a322df34d549c6493": {
+const manifest = { "44af69d3bfcf3ec46fffb3f297d2b12cd7fe4db36c654b8a322df34d549c6493": {
   functionName: "getStats_createServerFn_handler",
-  importer: () => import("./assets/stats.api-tIZqhk4B.js")
+  importer: () => import("./assets/stats.api-B9I1HZQw.js")
+}, "39e65590d2bc41f653f54a9b6a9e0a72f185da275304c0a4a595d811cf185572": {
+  functionName: "getProjectAnalytics_createServerFn_handler",
+  importer: () => import("./assets/project-analytics.api-B6FCr_cZ.js")
 }, "71794080473579a94431392ab409ebd02772f6a9f6a08386cadbb8c0d3cf804a": {
   functionName: "getSessionDetail_createServerFn_handler",
   importer: () => import("./assets/session-detail.api-BQts3iQn.js")
+}, "04ac41a7e3e644815167d098c2d6c3375d00a72a11e5af0d37033ba771081ba9": {
+  functionName: "getAppInfo_createServerFn_handler",
+  importer: () => import("./assets/app-info.api-CrHplh0q.js")
 }, "72f81ef9e8fa751bab60a8bdabd7e77816e2a6723a5e6e26e03712c01b3a249c": {
   functionName: "getSettings_createServerFn_handler",
   importer: () => import("./assets/settings.api-Cq5KPUxN.js")
 }, "7fe8c2b131c4fc81aa9a2570aec79640ff84603fe0060d13c24928b7329cb236": {
   functionName: "saveSettings_createServerFn_handler",
   importer: () => import("./assets/settings.api-Cq5KPUxN.js")
-}, "04ac41a7e3e644815167d098c2d6c3375d00a72a11e5af0d37033ba771081ba9": {
-  functionName: "getAppInfo_createServerFn_handler",
-  importer: () => import("./assets/app-info.api-CrHplh0q.js")
 }, "8fd6c4e5b4d5590acf1ec73da75f249978e8aced6dd2be23de06ade8431033be": {
   functionName: "getSessionList_createServerFn_handler",
-  importer: () => import("./assets/sessions.api-CQ-Lrk5S.js")
+  importer: () => import("./assets/sessions.api-BHD6I0Q1.js")
 }, "946cc550946f64ee7985dc35913a690eb13183d7ba83cffe398e424e697b4265": {
   functionName: "getActiveSessionList_createServerFn_handler",
-  importer: () => import("./assets/sessions.api-CQ-Lrk5S.js")
+  importer: () => import("./assets/sessions.api-BHD6I0Q1.js")
 }, "e574977967ea9b3387e72d70704b6ca87230e72becaf69f0b98cbc91c9cd1339": {
   functionName: "getPaginatedSessions_createServerFn_handler",
-  importer: () => import("./assets/sessions.api-CQ-Lrk5S.js")
+  importer: () => import("./assets/sessions.api-BHD6I0Q1.js")
 } };
 async function getServerFnById(id) {
   const serverFnInfo = manifest[id];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-session-dashboard",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Local observability dashboard for Claude Code sessions",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,7 @@
     "e2e:ui": "playwright test --ui",
     "e2e:headed": "playwright test --headed",
     "lint": "eslint src/",
+    "prepack": "cp ../../README.md ./README.md",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {