ai-wrapped 0.0.1

package/.0spec/flows/ai-stats.toml

@@ -0,0 +1,400 @@
+[flow]
+name = "ai-stats"
+description = "AI analytics dashboard — Electrobun desktop app with React + Tailwind + Vite, reading AI agent session data"
+
+# ─── Phase 1: Research & Planning ───────────────────────
+
+[[stages]]
+id = "research-sessions"
+name = "Deep-Dive Agent Sessions Formats"
+type = "seq"
+team = "research"
+prompt = """
+Read AGENT_SESSIONS_REFERENCE.md (pre-seeded in project root) for the full reference.
+
+Then deep-dive into the actual session file formats on this machine:
+1. Explore ~/.claude/projects/ — find real Claude Code JSONL files, parse a few, note actual field structure
+2. Explore ~/.codex/sessions/ — find real Codex CLI JSONL files, parse a few, note actual field structure
+3. Check for Gemini (~/.gemini/tmp), Copilot (~/.copilot/session-state), OpenCode (~/.local/share/opencode)
+
+For each agent found, document:
+- Exact file discovery pattern (glob)
+- Sample parsed event with all fields
+- How to extract: session ID, timestamps, token counts, model, cost (if present), cwd, git branch
+
+Also read the Electrobun skill at ~/.agents/skills/electrobun-desktop-apps/ for framework API reference.
+
+Produce SESSION_FORMATS.md with verified, machine-specific findings merged with the pre-seeded reference.
+"""
+output = { format = "markdown", name = "session-formats.md" }
+
+[[stages]]
+id = "plan"
+name = "Architecture Planning"
+type = "par"
+team = "planners"
+depends_on = ["research-sessions"]
+input_from = ["research-sessions"]
+prompt = """
+Design the ai-stats desktop application architecture.
+
+App purpose: Analytics dashboard that reads AI coding agent session logs from disk
+(Claude Code, Codex CLI, Gemini CLI, etc.) and visualizes usage stats —
+tokens consumed, costs, session duration, model usage, tool calls — across all agents.
+
+Data source: Local JSONL session files (see SESSION_FORMATS.md from research stage).
+This is NOT an API-based dashboard — it reads the same files as the Agent Sessions macOS app
+(https://github.com/jazzyalex/agent-sessions) but runs cross-platform via Electrobun.
+
+Tech stack:
+- Electrobun (desktop shell) — BrowserWindow, Tray, ApplicationMenu, Typed RPC
+  (see skill at ~/.agents/skills/electrobun-desktop-apps/)
+- React + Tailwind CSS v4 + Vite (frontend, with HMR in dev)
+- SQLite via bun:sqlite (local index for parsed session data + aggregates)
+- Recharts (dashboard visualizations)
+
+Core features:
+1. Session discovery — scan agent session directories, parse JSONL, normalize events
+2. Dashboard view — token usage over time, cost breakdown by agent/model, session count, tool call frequency
+3. Session browser — list all sessions across agents, search, filter by date/agent/model/repo
+4. Session detail — view events timeline, token counts per message, tool calls
+5. System tray — quick stats (today's tokens, active sessions), minimize-to-tray
+6. Application menu — standard Edit + File (Rescan Sessions, Preferences) + View
+7. Local-first — all data stays on disk, no cloud sync, read-only access to session files
+
+Project structure (Electrobun + Vite pattern):
+```
+src/
+  bun/
+    index.ts            # Main process: window, tray, menu, RPC handlers
+    db.ts               # SQLite schema + queries (index of parsed sessions)
+    discovery/          # Session file discovery per agent
+    parsers/            # JSONL parsers per agent (Claude, Codex, Gemini, Copilot, etc.)
+    normalizer.ts       # Normalize raw events → unified SessionEvent schema
+  shared/
+    types.ts            # RPC type definitions + shared data models
+    schema.ts           # SessionEvent, Session, SessionSource types
+  mainview/
+    index.html
+    index.css
+    index.ts            # React app entry
+    App.tsx
+    components/         # Dashboard, SessionList, SessionDetail, Settings
+    hooks/              # useRPC, useSessions, useDashboardData
+    lib/                # Formatters, constants
+electrobun.config.ts
+vite.config.ts
+```
+
+Produce a unified architecture spec covering:
+- Normalized data model (SessionEvent schema from Agent Sessions reference)
+- SQLite tables (sessions, events index, daily aggregates)
+- Session discovery + parsing pipeline
+- RPC schema (bun <-> webview)
+- Component tree
+- File-by-file implementation plan
+- Build & dev workflow
+
+Output as markdown.
+"""
+output = { format = "markdown", name = "architecture.md" }
+
+[[stages]]
+id = "merge-plans"
+name = "Consolidate Architecture"
+type = "seq"
+team = "research"
+depends_on = ["plan"]
+input_from = ["plan", "research-sessions"]
+prompt = """
+Consolidate the architecture plans into a single, authoritative unified spec.
+Resolve any conflicts between parallel planner outputs.
+Ensure the spec references the verified session formats from research.
+Ensure the spec is actionable — an implementor should be able to build from this alone.
+
+Output as UNIFIED_SPEC.md.
+"""
+output = { format = "markdown", name = "unified-spec.md" }
+
+# ─── Phase 2: Scaffold ─────────────────────────────────
+
+[[stages]]
+id = "scaffold"
+name = "Project Scaffold"
+type = "seq"
+team = "implementors"
+depends_on = ["merge-plans"]
+input_from = ["merge-plans"]
+prompt = """
+Read the unified spec. Create the project scaffold as specified.
+
+Constraints:
+- Use Electrobun react-tailwind-vite pattern (Vite builds to dist/, copy config maps to views/)
+- Remove "type": "module" and "module" from package.json if present
+- SQLite via bun:sqlite (built into Bun, no extra deps)
+- Tailwind v4 via @tailwindcss/vite plugin
+- Use concurrently for dev:hmr script
+
+Only skeleton — stub files with empty exports/components. No business logic.
+
+Verify:
+- `bun install` succeeds
+- Vite build compiles without errors
+- Main process file parses without errors
+"""
+output = { format = "markdown", name = "scaffold.md" }
+
+[[stages]]
+id = "qa-scaffold"
+name = "QA Scaffold"
+type = "seq"
+team = "reviewers"
+depends_on = ["scaffold"]
+input_from = ["scaffold", "merge-plans"]
+prompt = """
+Verify the scaffold:
+1. `bun install` succeeds
+2. Vite build compiles without errors
+3. All files from the spec exist (check file tree)
+4. package.json has correct scripts (dev, dev:hmr, build)
+5. electrobun.config.ts is valid
+6. No "type": "module" in package.json
+
+Output JSON: { "verdict": "pass" or "fail", "issues": [...] }
+"""
+output = { format = "json", name = "qa-scaffold.json" }
+
+[[stages]]
+id = "fix-scaffold"
+name = "Fix Scaffold Issues"
+type = "loop"
+team = "implementors"
+depends_on = ["qa-scaffold"]
+input_from = ["qa-scaffold"]
+prompt = "Fix all issues from QA report."
+max_loops = 2
+loop_to = "qa-scaffold"
+condition = "qa-scaffold.verdict != 'pass'"
+output = { format = "diff", name = "scaffold-fixes.diff" }
+
+# ─── Phase 3: Parsers & Data Layer ─────────────────────
+
+[[stages]]
+id = "data-layer"
+name = "Session Parsers + SQLite + RPC"
+type = "seq"
+team = "implementors"
+depends_on = ["fix-scaffold"]
+input_from = ["merge-plans", "research-sessions"]
+prompt = """
+Read the unified spec and session formats reference. Implement:
+
+1. Session discovery (src/bun/discovery/):
+   - Discover Claude Code sessions: ~/.claude/projects/*/*.jsonl
+   - Discover Codex CLI sessions: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
+   - Discover other agents if present (Gemini, Copilot, OpenCode)
+   - Return file paths with agent source type
+
+2. JSONL parsers (src/bun/parsers/):
+   - Claude Code parser — handle nested message.content, uuid/parentUuid threading
+   - Codex CLI parser — handle top-level content, delta streaming chunks
+   - Generic parser fallback
+   - All parsers produce normalized SessionEvent[]
+
+3. Normalizer (src/bun/normalizer.ts):
+   - Map raw event types to SessionEventKind (user, assistant, tool_call, tool_result, error, meta)
+   - Extract text from various content formats
+   - Handle timestamp format variations (ISO 8601, epoch seconds/ms)
+
+4. SQLite database (src/bun/db.ts):
+   - Tables: sessions (id, source, start_time, end_time, model, file_path, event_count, cwd, repo_name)
+   - Tables: daily_stats (date, source, session_count, event_count, tool_call_count)
+   - Migration/init, upsert parsed sessions, query functions
+
+5. RPC types (src/shared/types.ts) + wiring (src/bun/index.ts):
+   - Bun handlers: getSessions, getSessionDetail, getDashboardStats, rescanSessions
+   - Webview handlers: refreshUI, showNotification
+
+Verify:
+- TypeScript compiles without errors
+- DB initializes and creates tables
+- At least one real session file parses successfully
+"""
+output = { format = "markdown", name = "data-layer.md" }
+
+[[stages]]
+id = "qa-data"
+name = "QA Data Layer"
+type = "seq"
+team = "reviewers"
+depends_on = ["data-layer"]
+input_from = ["data-layer", "merge-plans"]
+prompt = """
+Verify the data layer:
+1. SQLite schema matches the spec
+2. Session discovery finds real session files on this machine
+3. At least one Claude Code and one Codex session parses without errors
+4. Normalized events have correct kind, text, timestamps
+5. RPC types are complete and type-safe
+6. TypeScript compiles
+
+Output JSON: { "verdict": "pass" or "fail", "issues": [...] }
+"""
+output = { format = "json", name = "qa-data.json" }
+
+[[stages]]
+id = "fix-data"
+name = "Fix Data Layer Issues"
+type = "loop"
+team = "implementors"
+depends_on = ["qa-data"]
+input_from = ["qa-data"]
+prompt = "Fix all issues from QA report."
+max_loops = 2
+loop_to = "qa-data"
+condition = "qa-data.verdict != 'pass'"
+output = { format = "diff", name = "data-fixes.diff" }
+
+# ─── Phase 4: Dashboard UI ─────────────────────────────
+
+[[stages]]
+id = "dashboard-ui"
+name = "Dashboard UI Components"
+type = "seq"
+team = "implementors"
+depends_on = ["fix-data"]
+input_from = ["merge-plans"]
+prompt = """
+Read the unified spec. Implement the React dashboard UI:
+
+1. App shell (App.tsx) — sidebar nav + main content area
+2. Dashboard page — summary cards (total sessions, total events, tool calls today) + charts
+3. Charts — session count over time (line), events by agent (bar), tool call frequency (bar), model usage (pie)
+4. Session browser page — filterable list of all sessions, search by repo/agent/date
+5. Session detail page — event timeline with kind icons, expandable tool call details
+6. Settings page — configure watched directories, rescan interval
+7. useRPC hook — typed wrapper around Electroview RPC calls
+
+Use Tailwind v4 for all styling. Dark theme by default.
+Use Recharts for charts.
+
+Verify:
+- Vite build compiles without errors
+- All components render (no runtime crashes on import)
+"""
+output = { format = "markdown", name = "dashboard-ui.md" }
+
+[[stages]]
+id = "qa-ui"
+name = "QA Dashboard UI"
+type = "seq"
+team = "reviewers"
+depends_on = ["dashboard-ui"]
+input_from = ["dashboard-ui", "merge-plans"]
+prompt = """
+Verify the dashboard UI:
+1. Vite build compiles without errors
+2. All pages/components exist per spec
+3. RPC hooks are properly typed
+4. Tailwind classes are valid
+5. Dark theme is consistent
+6. No hardcoded data — all data comes through RPC
+
+Output JSON: { "verdict": "pass" or "fail", "issues": [...] }
+"""
+output = { format = "json", name = "qa-ui.json" }
+
+[[stages]]
+id = "fix-ui"
+name = "Fix UI Issues"
+type = "loop"
+team = "implementors"
+depends_on = ["qa-ui"]
+input_from = ["qa-ui"]
+prompt = "Fix all issues from QA report."
+max_loops = 2
+loop_to = "qa-ui"
+condition = "qa-ui.verdict != 'pass'"
+output = { format = "diff", name = "ui-fixes.diff" }
+
+# ─── Phase 5: Native Integration ───────────────────────
+
+[[stages]]
+id = "native"
+name = "Tray, Menu & Window Polish"
+type = "seq"
+team = "implementors"
+depends_on = ["fix-ui"]
+input_from = ["merge-plans"]
+prompt = """
+Read the unified spec. Implement native desktop integration:
+
+1. System tray:
+   - Show app icon in tray
+   - Tray menu: quick stats (today's sessions/events), "Show Dashboard", "Rescan Sessions", "Quit"
+   - Clicking tray icon shows/hides main window
+
+2. Application menu:
+   - Standard Edit menu (undo, redo, cut, copy, paste, selectAll)
+   - File menu: "Rescan Sessions" action, "Quit"
+   - View menu: "Toggle Dark Mode"
+
+3. Window behavior:
+   - Close button minimizes to tray (on macOS)
+   - Proper quit via menu or tray
+
+Verify:
+- Main process starts without errors
+- Tray icon appears
+- Menu items are functional
+"""
+output = { format = "markdown", name = "native.md" }
+
+[[stages]]
+id = "qa-native"
+name = "QA Native Integration"
+type = "seq"
+team = "reviewers"
+depends_on = ["native"]
+input_from = ["native", "merge-plans"]
+prompt = """
+Verify native integration:
+1. Tray icon creates without errors
+2. Application menu has all required items
+3. Menu actions are wired to handlers
+4. Window close behavior is correct
+5. Main process starts and creates window + tray
+
+Output JSON: { "verdict": "pass" or "fail", "issues": [...] }
+"""
+output = { format = "json", name = "qa-native.json" }
+
+[[stages]]
+id = "fix-native"
+name = "Fix Native Issues"
+type = "loop"
+team = "implementors"
+depends_on = ["qa-native"]
+input_from = ["qa-native"]
+prompt = "Fix all issues from QA report."
+max_loops = 2
+loop_to = "qa-native"
+condition = "qa-native.verdict != 'pass'"
+output = { format = "diff", name = "native-fixes.diff" }
+
+# ─── Phase 6: Final ────────────────────────────────────
+
+[[stages]]
+id = "commit"
+name = "Final Commit"
+type = "seq"
+team = "global"
+depends_on = ["fix-native"]
+prompt = """
+Review git diff. Stage all new/modified files. Commit with descriptive message:
+"feat: ai-stats — Electrobun desktop dashboard for AI agent session analytics"
+
+Do NOT push.
+"""
+tools = ["Read", "Glob", "Grep", "Bash"]
+output = { format = "markdown", name = "commit.md" }

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - run: bun install --frozen-lockfile
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,111 @@
+---
+description: Use Bun instead of Node.js, npm, pnpm, or vite.
+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
+alwaysApply: false
+---
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+// import .css files directly and it works
+import './index.css';
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.

package/README.md

@@ -0,0 +1,64 @@
+# AI Wrapped
+
+Spotify Wrapped-style desktop dashboard for your AI coding agent activity. A visual summary across multiple agents.
+
+Built on [Electrobun](https://electrobun.dev) — a TypeScript-first desktop framework using Bun + native webviews.
+
+Built on top of [agent-sessions](https://github.com/jazzyalex/agent-sessions) session format discovery — reads JSONL/JSON session logs that AI coding agents write to disk.
+
+## Supported Agents
+
+- **Claude Code** — `~/.claude/projects/` JSONL sessions + subagent logs
+- **OpenAI Codex** — Codex CLI session files
+- **Google Gemini CLI** — Gemini session logs
+- **OpenCode** — OpenCode session data
+- **Droid** — Droid session files
+- **GitHub Copilot** — Copilot session logs
+
+## What It Shows
+
+- Total sessions, messages, tool calls, tokens, and estimated cost
+- Daily activity timeline with per-agent and per-model breakdown
+- Cost breakdown by model (Claude Opus, Sonnet, GPT-4o, Gemini Pro, etc.)
+- Agent usage distribution (pie chart)
+- Active day coverage ring
+- System tray with today's stats at a glance
+
+## Stack
+
+- **Runtime**: [Bun](https://bun.sh)
+- **Desktop**: [Electrobun](https://electrobun.dev) (native webview, no Chromium bundling on macOS)
+- **Frontend**: React + Tailwind CSS + Recharts
+- **Build**: Vite (frontend) + Electrobun CLI (app bundle)
+- **Storage**: JSON files in `~/.ai-wrapped/`
+
+## Getting Started
+
+```bash
+bun install
+```
+
+### Development
+
+```bash
+bun run dev
+```
+
+Or with HMR for the frontend:
+
+```bash
+bun run dev:hmr
+```
+
+### Production Build
+
+```bash
+bun run build:prod
+```
+
+## How It Works
+
+1. On launch (and every 5 minutes by default), the app scans known session directories for each agent
+2. New or changed session files are parsed into a normalized format with token counts, tool calls, and cost estimates
+3. Aggregated daily stats are written to `~/.ai-stats/daily.json`
+4. The frontend fetches summaries over RPC and renders the Wrapped-style dashboard