@tokentop/ttop 0.5.0 → 0.6.1

package/README.md

@@ -1,5 +1,4 @@
- > [!CAUTION]
-> **tokentop is under active development and not yet ready for general use.** APIs and configuration may change without notice. If you're interested, star the repo and check back soon.
+ > **Early release** — tokentop is functional and actively developed. Please [report issues](https://github.com/tokentopapp/tokentop/issues)!
 
 <div align="center">
 
@@ -16,8 +15,11 @@ Real-time terminal monitoring of LLM token usage and spending across providers a
 [![GitHub release](https://img.shields.io/github/v/release/tokentopapp/tokentop?style=flat-square)](https://github.com/tokentopapp/tokentop/releases)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Bun](https://img.shields.io/badge/Bun-runtime-f9f1e1?style=flat-square&logo=bun&logoColor=black)](https://bun.sh)
+[![Visitors](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Ftokentopapp%2Ftokentop&labelColor=%23697689&countColor=%23ba68c8&style=flat-square)](https://visitorbadge.io/status?path=https://github.com/tokentopapp/tokentop)
 
-[Features](#features) · [Install](#installation) · [Quick Start](#quick-start) · [Keyboard Shortcuts](#keyboard-shortcuts) · [Configuration](#configuration) · [Plugins](#plugin-system)
+[Features](#features) · [Install](#installation) · [Quick Start](#quick-start) · [Agents](#agents) · [Plugins](#plugin-system) · [Docs](https://tokentop.app/docs/getting-started/)
+
+**[tokentop.app](https://tokentop.app)**
 
 </div>
 
@@ -25,26 +27,26 @@ Real-time terminal monitoring of LLM token usage and spending across providers a
 
 ## Why tokentop?
 
-You're coding with AI agents all day. Claude Code, OpenCode, Cursor — they're burning through tokens and you have no idea how fast.
+You're coding with AI agents all day. Claude Code, OpenCode, Cursor, Copilot CLI — they're burning through tokens and you have no idea how fast.
 
 You check the Anthropic dashboard. It's hours behind. You check OpenAI. Different dashboard, different login. Want to see it all in one place? In real time? In your terminal, where you already live?
 
 That's tokentop.
 
 - See every session, every model, every dollar — **live**
-- Track costs across **10 providers** from a single dashboard
+- Track costs across **11 providers** from a single dashboard
 - Set **budget alerts** so you don't wake up to a surprise bill
 - Runs **100% locally** — your usage data never leaves your machine
 
 ## Demo
 
-https://github.com/user-attachments/assets/0b0225c7-a137-454b-9b29-c858cdcbd86c
+<https://github.com/user-attachments/assets/0b0225c7-a137-454b-9b29-c858cdcbd86c>
 
 ## Features
 
 - **Real-time dashboard** — Live token counts, costs, burn rate, and activity sparklines
-- **10 providers** — Anthropic, OpenAI, Google Gemini, GitHub Copilot, Codex, Perplexity, Antigravity, MiniMax, Zai, OpenCode Zen
-- **Session tracking** — See every coding agent session with model, tokens, cost, and duration
+- **11 providers** — Anthropic, OpenAI, Google Gemini, GitHub Copilot, Codex, Perplexity, Antigravity, MiniMax, Zai, OpenCode Zen, Chutes
+- **7 coding agents** — Claude Code, OpenCode, Cursor, Copilot CLI, Gemini CLI, Antigravity, and Windsurf. See every session with model, tokens, cost, and duration
 - **Budget guardrails** — Daily, weekly, and monthly limits with visual warnings at limit percentages you set
 - **Smart sidebar** — Adaptive panel that breaks down spending by model, project, or agent
 - **Efficiency insights** — Cache leverage, output verbosity, and cost-per-request analysis to help you spend less
@@ -52,11 +54,11 @@ https://github.com/user-attachments/assets/0b0225c7-a137-454b-9b29-c858cdcbd86c
 - **Projects view** — See which codebase is costing you the most
 - **Provider limits** — Visual gauges showing how close you are to rate limits
 - **Live pricing** — Fetches current model pricing from [models.dev](https://models.dev) with local caching
-- **15 built-in themes** — Dark: Tokyo Night (default), Dracula, Nord, Catppuccin Mocha, Gruvbox Dark, One Dark, Rosé Pine, Kanagawa, OpenCode, Claude Code · Light: Catppuccin Latte, Gruvbox Light, GitHub Light, Solarized Light, Rosé Pine Dawn
+- **[15 built-in themes](https://tokentop.app/docs/themes/built-in/)** — Tokyo Night, Dracula, Nord, Catppuccin, Gruvbox, Rosé Pine, Kanagawa, and more. Dark and light variants. Create your own with the [theme plugin API](https://tokentop.app/docs/themes/custom-themes/)
 - **Plugin system** — Extend with custom providers, agents, themes, and notifications
 - **Responsive layout** — Adapts to any terminal size; sidebar, KPI strip, header, and tables all reflow automatically from ultrawide to laptop-width
 - **Demo mode** — Explore the UI with synthetic data, no API keys needed
-- **Zero config** — Auto-discovers credentials from Claude Code, environment variables, and CLI auth files
+- **Zero config** — Auto-discovers credentials from Claude Code, OpenCode, Cursor, Copilot CLI, Gemini CLI, environment variables, and CLI auth files
 
 ## Installation
 
@@ -140,9 +142,21 @@ tokentop has 4 main views, switchable with `1`–`4`:
 | `3` | **Trends** | ASCII step charts of cost over 7/30/90 days |
 | `4` | **Projects** | Cost and token breakdown by local project/repo |
 
-<!-- TODO: Add VHS recordings of each view
-> _Screenshots coming soon_
--->
+## Agents
+
+tokentop tracks sessions from 7 coding agents. Each agent is a standalone plugin — built-in agents ship with the app, community agents install from npm.
+
+| Agent | What it tracks | Plugin |
+|-------|---------------|--------|
+| [Claude Code](https://tokentop.app/docs/agents/claude-code/) | Sessions, OAuth tokens, multi-provider usage | [`@tokentop/agent-claude-code`](https://github.com/tokentopapp/agent-claude-code) |
+| [OpenCode](https://tokentop.app/docs/agents/opencode/) | Sessions, OAuth credentials, multi-provider support | [`@tokentop/agent-opencode`](https://github.com/tokentopapp/agent-opencode) |
+| [Cursor](https://tokentop.app/docs/agents/cursor/) | Sessions, CSV server log enrichment | [`@tokentop/agent-cursor`](https://github.com/tokentopapp/agent-cursor) |
+| [Copilot CLI](https://tokentop.app/docs/agents/copilot-cli/) | Sessions, GitHub token auth | [`@tokentop/agent-copilot-cli`](https://github.com/tokentopapp/agent-copilot-cli) |
+| [Gemini CLI](https://tokentop.app/docs/agents/gemini-cli/) | Sessions, Google OAuth | [`@tokentop/agent-gemini`](https://github.com/tokentopapp/agent-gemini) |
+| [Antigravity](https://tokentop.app/docs/agents/antigravity/) | Sessions, Google OAuth | [`@tokentop/agent-gemini`](https://github.com/tokentopapp/agent-gemini) |
+| [Windsurf](https://tokentop.app/docs/agents/windsurf/) | Sessions, Codeium auth | [`@tokentop/agent-windsurf`](https://github.com/tokentopapp/agent-windsurf) |
+
+All agents are auto-discovered — if you have the tool installed, tokentop finds it. See the [agent docs](https://tokentop.app/docs/agents/) for details.
 
 ## Keyboard Shortcuts
 
@@ -218,7 +232,7 @@ tokentop is built on a plugin architecture with four extension points:
 
 All plugins run in a **permission sandbox** — they must declare network, filesystem, and environment access upfront. Anyone can publish community plugins to npm — no org membership needed.
 
-See the [Plugin Guide](docs/plugins.md) for installation, configuration, and development details.
+See the [Plugin Guide](https://tokentop.app/docs/plugins/overview/) for installation, configuration, and development details.
 
 ## How It Works
 
@@ -231,6 +245,15 @@ Costs are calculated from token counts and live pricing data from [models.dev](h
 
 All data is stored in a **local SQLite database**. Nothing is sent anywhere. No telemetry, no analytics, no network calls except to the provider APIs you've already authenticated with.
 
+## Alternatives
+
+| Tool | Approach | Tokentop Difference |
+|------|----------|---------------------|
+| Provider dashboards | Web, hours behind | Real-time, in terminal |
+| [tokentap](https://github.com/nicholasgasior/tokentap) | MitM proxy (abandoned) | Native API polling, no proxy |
+| [toktop](https://github.com/jnsahaj/toktop) | Rust TUI, 2 providers | 11 providers, 7 agents, plugins |
+| [sniffly](https://github.com/chiphuyen/sniffly) | Python dashboard | Terminal-native, multi-agent |
+
 ## Development
 
 ```bash
@@ -238,7 +261,7 @@ bun install          # Install dependencies
 bun run dev          # Dev mode with hot reload
 bun test             # Run tests
 bun run typecheck    # TypeScript check
-bun run lint         # ESLint
+bun run lint         # Biome
 ```
 
 ### Demo mode for development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokentop/ttop",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Real-time AI token usage monitor - htop for your API costs",
   "author": "Nigel Bazzeghin <nbazzeghin@gmail.com>",
   "license": "MIT",
@@ -30,16 +30,18 @@
     "test:watch": "bun test --watch",
     "driver": "bun src/tui/driver/cli.ts",
     "driver:help": "bun src/tui/driver/cli.ts --help",
-    "snapshot": "bun src/tui/debug/snapshot.tsx"
+    "snapshot": "bun src/tui/debug/snapshot.tsx",
+    "analytics": "bun .opencode/skills/analytics/scripts/analytics.ts"
   },
   "dependencies": {
-    "@opentui/core": "0.1.84",
-    "@opentui/react": "0.1.84",
+    "@opentui/core": "0.1.87",
+    "@opentui/react": "0.1.87",
     "@tokentop/agent-claude-code": "^1.1.0",
+    "@tokentop/agent-copilot-cli": "^1.0.0",
     "@tokentop/agent-cursor": "^1.2.0",
+    "@tokentop/agent-gemini": "^1.0.0",
     "@tokentop/agent-opencode": "^1.0.0",
-    "@tokentop/agent-copilot-cli": "^1.0.0",
-    "@tokentop/plugin-sdk": "^1.3.0",
+    "@tokentop/plugin-sdk": "^1.4.0",
     "react": "^19.0.0",
     "react-devtools-core": "^7.0.1",
     "zod": "^4.0.0"

package/src/agents/aggregator.test.ts

@@ -0,0 +1,306 @@
+import { describe, expect, test } from "bun:test";
+import { aggregateSessionUsage, deduplicateAggregates } from "./aggregator.ts";
+import type { AgentSessionAggregate } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Helper: build a minimal AgentSessionAggregate for dedup tests
+// ---------------------------------------------------------------------------
+function makeAggregate(
+  overrides: Partial<AgentSessionAggregate> & Pick<AgentSessionAggregate, "sessionId" | "agentId">,
+): AgentSessionAggregate {
+  return {
+    agentName: overrides.agentId,
+    startedAt: 0,
+    lastActivityAt: 0,
+    status: "idle",
+    totals: { input: 0, output: 0 },
+    totalCostUsd: 0,
+    requestCount: 0,
+    streams: [],
+    costInDay: 0,
+    costInWeek: 0,
+    costInMonth: 0,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// deduplicateAggregates
+// ---------------------------------------------------------------------------
+describe("deduplicateAggregates", () => {
+  test("returns empty array for empty input", () => {
+    expect(deduplicateAggregates([])).toEqual([]);
+  });
+
+  test("passes through unique sessions unchanged", () => {
+    const a = makeAggregate({ sessionId: "s1", agentId: "antigravity" });
+    const b = makeAggregate({ sessionId: "s2", agentId: "antigravity" });
+    const c = makeAggregate({ sessionId: "s3", agentId: "gemini-cli" });
+
+    const result = deduplicateAggregates([a, b, c]);
+    expect(result).toHaveLength(3);
+    expect(result.map((r) => r.sessionId).sort()).toEqual(["s1", "s2", "s3"]);
+  });
+
+  test("removes exact duplicates (same sessionId from two agents)", () => {
+    const fromAntigravity = makeAggregate({
+      sessionId: "dup-1",
+      agentId: "antigravity",
+      agentName: "Antigravity",
+      requestCount: 5,
+      streams: [
+        {
+          providerId: "google",
+          modelId: "gemini-3-flash",
+          tokens: { input: 100, output: 50 },
+          requestCount: 5,
+        },
+      ],
+    });
+    const fromGeminiCli = makeAggregate({
+      sessionId: "dup-1",
+      agentId: "gemini-cli",
+      agentName: "Gemini CLI",
+      requestCount: 5,
+      streams: [
+        {
+          providerId: "google",
+          modelId: "gemini-3-flash",
+          tokens: { input: 100, output: 50 },
+          requestCount: 5,
+        },
+      ],
+    });
+
+    const result = deduplicateAggregates([fromAntigravity, fromGeminiCli]);
+    expect(result).toHaveLength(1);
+    // First one encountered wins when equal
+    expect(result[0]!.agentId).toBe("antigravity");
+  });
+
+  test("keeps the aggregate with more streams", () => {
+    const fewer = makeAggregate({
+      sessionId: "dup-2",
+      agentId: "agent-a",
+      requestCount: 10,
+      streams: [
+        {
+          providerId: "google",
+          modelId: "gemini-3-flash",
+          tokens: { input: 100, output: 50 },
+          requestCount: 10,
+        },
+      ],
+    });
+    const more = makeAggregate({
+      sessionId: "dup-2",
+      agentId: "agent-b",
+      requestCount: 10,
+      streams: [
+        {
+          providerId: "google",
+          modelId: "gemini-3-flash",
+          tokens: { input: 80, output: 40 },
+          requestCount: 7,
+        },
+        {
+          providerId: "google",
+          modelId: "gemini-2.5-pro",
+          tokens: { input: 20, output: 10 },
+          requestCount: 3,
+        },
+      ],
+    });
+
+    // Regardless of order, the one with more streams wins
+    expect(deduplicateAggregates([fewer, more])[0]!.agentId).toBe("agent-b");
+    expect(deduplicateAggregates([more, fewer])[0]!.agentId).toBe("agent-b");
+  });
+
+  test("breaks stream-count tie by preferring more requests", () => {
+    const lessRequests = makeAggregate({
+      sessionId: "dup-3",
+      agentId: "agent-a",
+      requestCount: 3,
+      streams: [
+        {
+          providerId: "google",
+          modelId: "gemini-3-flash",
+          tokens: { input: 50, output: 25 },
+          requestCount: 3,
+        },
+      ],
+    });
+    const moreRequests = makeAggregate({
+      sessionId: "dup-3",
+      agentId: "agent-b",
+      requestCount: 7,
+      streams: [
+        {
+          providerId: "google",
+          modelId: "gemini-3-flash",
+          tokens: { input: 100, output: 50 },
+          requestCount: 7,
+        },
+      ],
+    });
+
+    expect(deduplicateAggregates([lessRequests, moreRequests])[0]!.agentId).toBe("agent-b");
+    expect(deduplicateAggregates([moreRequests, lessRequests])[0]!.agentId).toBe("agent-b");
+  });
+
+  test("keeps first encountered when streams and requests are equal", () => {
+    const first = makeAggregate({
+      sessionId: "dup-4",
+      agentId: "first",
+      requestCount: 5,
+      streams: [
+        { providerId: "google", modelId: "m", tokens: { input: 1, output: 1 }, requestCount: 5 },
+      ],
+    });
+    const second = makeAggregate({
+      sessionId: "dup-4",
+      agentId: "second",
+      requestCount: 5,
+      streams: [
+        { providerId: "google", modelId: "m", tokens: { input: 1, output: 1 }, requestCount: 5 },
+      ],
+    });
+
+    expect(deduplicateAggregates([first, second])[0]!.agentId).toBe("first");
+    expect(deduplicateAggregates([second, first])[0]!.agentId).toBe("second");
+  });
+
+  test("handles mix of unique and duplicate sessions", () => {
+    const unique1 = makeAggregate({ sessionId: "u1", agentId: "antigravity" });
+    const unique2 = makeAggregate({ sessionId: "u2", agentId: "opencode" });
+    const dupA = makeAggregate({
+      sessionId: "d1",
+      agentId: "antigravity",
+      requestCount: 5,
+      streams: [
+        { providerId: "google", modelId: "m", tokens: { input: 1, output: 1 }, requestCount: 5 },
+      ],
+    });
+    const dupB = makeAggregate({
+      sessionId: "d1",
+      agentId: "gemini-cli",
+      requestCount: 5,
+      streams: [
+        { providerId: "google", modelId: "m", tokens: { input: 1, output: 1 }, requestCount: 5 },
+      ],
+    });
+
+    const result = deduplicateAggregates([unique1, dupA, unique2, dupB]);
+    expect(result).toHaveLength(3);
+    expect(result.map((r) => r.sessionId).sort()).toEqual(["d1", "u1", "u2"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// aggregateSessionUsage — basic sanity
+// ---------------------------------------------------------------------------
+describe("aggregateSessionUsage", () => {
+  const NOW = Date.now();
+
+  test("groups rows by sessionId", () => {
+    const result = aggregateSessionUsage({
+      agentId: "test",
+      agentName: "Test",
+      now: NOW,
+      rows: [
+        {
+          sessionId: "s1",
+          providerId: "google",
+          modelId: "m1",
+          tokens: { input: 10, output: 5 },
+          timestamp: NOW,
+        },
+        {
+          sessionId: "s1",
+          providerId: "google",
+          modelId: "m1",
+          tokens: { input: 20, output: 10 },
+          timestamp: NOW - 1000,
+        },
+        {
+          sessionId: "s2",
+          providerId: "google",
+          modelId: "m1",
+          tokens: { input: 30, output: 15 },
+          timestamp: NOW - 2000,
+        },
+      ],
+    });
+
+    expect(result).toHaveLength(2);
+
+    const s1 = result.find((r) => r.sessionId === "s1");
+    expect(s1).toBeDefined();
+    expect(s1!.requestCount).toBe(2);
+    expect(s1!.totals.input).toBe(30);
+    expect(s1!.totals.output).toBe(15);
+
+    const s2 = result.find((r) => r.sessionId === "s2");
+    expect(s2).toBeDefined();
+    expect(s2!.requestCount).toBe(1);
+  });
+
+  test("splits different models into separate streams", () => {
+    const result = aggregateSessionUsage({
+      agentId: "test",
+      agentName: "Test",
+      now: NOW,
+      rows: [
+        {
+          sessionId: "s1",
+          providerId: "google",
+          modelId: "flash",
+          tokens: { input: 10, output: 5 },
+          timestamp: NOW,
+        },
+        {
+          sessionId: "s1",
+          providerId: "google",
+          modelId: "pro",
+          tokens: { input: 20, output: 10 },
+          timestamp: NOW,
+        },
+      ],
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]!.streams).toHaveLength(2);
+    expect(result[0]!.requestCount).toBe(2);
+  });
+
+  test("marks session active when within threshold", () => {
+    const result = aggregateSessionUsage({
+      agentId: "test",
+      agentName: "Test",
+      now: NOW,
+      activeThresholdMs: 60_000,
+      rows: [
+        {
+          sessionId: "active",
+          providerId: "g",
+          modelId: "m",
+          tokens: { input: 1, output: 1 },
+          timestamp: NOW - 10_000,
+        },
+        {
+          sessionId: "idle",
+          providerId: "g",
+          modelId: "m",
+          tokens: { input: 1, output: 1 },
+          timestamp: NOW - 120_000,
+        },
+      ],
+    });
+
+    const active = result.find((r) => r.sessionId === "active");
+    const idle = result.find((r) => r.sessionId === "idle");
+    expect(active!.status).toBe("active");
+    expect(idle!.status).toBe("idle");
+  });
+});

package/src/agents/aggregator.ts

@@ -85,6 +85,7 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
       timestamps: number[];
       sessionUpdatedAt?: number;
       streamMap: Map<string, StreamAccumulator>;
+      hasEstimated: boolean;
     }
   >();
 
@@ -97,9 +98,11 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
         timestamps: number[];
         sessionUpdatedAt?: number;
         streamMap: Map<string, StreamAccumulator>;
+        hasEstimated: boolean;
       } = {
         timestamps: [],
         streamMap: new Map(),
+        hasEstimated: false,
       };
       if (row.sessionName) newSession.sessionName = row.sessionName;
       if (row.projectPath) newSession.projectPath = row.projectPath;
@@ -107,7 +110,8 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
       sessionMap.set(row.sessionId, newSession);
     }
 
-    const session = sessionMap.get(row.sessionId)!;
+    const session = sessionMap.get(row.sessionId);
+    if (!session) continue;
 
     session.timestamps.push(row.timestamp);
     if (row.sessionName && !session.sessionName) {
@@ -145,6 +149,9 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
     if (row.timestamp >= startOfDay) stream.windowed.dayTokens += msgTokens;
     if (row.timestamp >= startOfWeek) stream.windowed.weekTokens += msgTokens;
     if (row.timestamp >= startOfMonth) stream.windowed.monthTokens += msgTokens;
+    if ((row.metadata?.isEstimated as boolean) === true) {
+      session.hasEstimated = true;
+    }
   }
 
   const results: AgentSessionAggregate[] = [];
@@ -190,10 +197,8 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
     if (session.sessionName) aggregate.sessionName = session.sessionName;
     if (session.projectPath) aggregate.projectPath = session.projectPath;
 
-    // Propagate metadata — session is estimated if any row is estimated
-    const sessionRows = rows.filter((r) => r.sessionId === sessionId);
-    const anyEstimated = sessionRows.some((r) => (r.metadata?.isEstimated as boolean) === true);
-    if (anyEstimated) {
+    // Propagate metadata — collected during the first pass (O(1) per session)
+    if (session.hasEstimated) {
       aggregate.metadata = { isEstimated: true };
     }
     results.push(aggregate);
@@ -201,3 +206,33 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
 
   return results.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
 }
+
+/**
+ * Deduplicate aggregates that share the same sessionId.
+ *
+ * This happens when multiple agent plugins scan the same directory
+ * (e.g. both agent-antigravity and agent-gemini-cli read ~/.gemini/tmp/).
+ * For each duplicate sessionId, the richer aggregate is kept:
+ *  1. More streams (more provider/model pairs)
+ *  2. If tied, more requests
+ *  3. If still tied, the first one encountered
+ */
+export function deduplicateAggregates(
+  aggregates: AgentSessionAggregate[],
+): AgentSessionAggregate[] {
+  const deduped = new Map<string, AgentSessionAggregate>();
+  for (const agg of aggregates) {
+    const existing = deduped.get(agg.sessionId);
+    if (!existing) {
+      deduped.set(agg.sessionId, agg);
+      continue;
+    }
+    if (
+      agg.streams.length > existing.streams.length ||
+      (agg.streams.length === existing.streams.length && agg.requestCount > existing.requestCount)
+    ) {
+      deduped.set(agg.sessionId, agg);
+    }
+  }
+  return Array.from(deduped.values());
+}

package/src/cli.ts

@@ -19,6 +19,7 @@ Commands:
   demo                    Run with demo data (no real providers)
 
 Options:
+  -t, --theme <id>        Launch with a specific theme (e.g. dracula, nord)
   -r, --refresh <ms>      Refresh interval in milliseconds (default: 60000)
   -p, --plugin <path>     Load a local plugin (file or directory, repeatable)
   -d, --debug             Enable debug mode (verbose logging)
@@ -69,6 +70,7 @@ async function main() {
   let demoSeed: number | undefined;
   let demoPreset: DemoPreset | undefined;
   const cliPlugins: string[] = [];
+  let cliTheme: string | undefined;
 
   // Handle demo subcommand
   if (subcommand === "demo") {
@@ -96,6 +98,15 @@ async function main() {
       debug = true;
     }
 
+    if (arg === "-t" || arg === "--theme") {
+      const themeId = commandArgs[++i];
+      if (!themeId) {
+        console.error("Error: --theme requires a theme ID (e.g. dracula, nord, tokyo-night)");
+        process.exit(1);
+      }
+      cliTheme = themeId;
+    }
+
     if (arg === "-p" || arg === "--plugin") {
       const pluginPath = commandArgs[++i];
       if (!pluginPath) {
@@ -159,6 +170,9 @@ async function main() {
   if (demoPreset !== undefined) {
     launchOptions.demoPreset = demoPreset;
   }
+  if (cliTheme !== undefined) {
+    launchOptions.cliTheme = cliTheme;
+  }
   await startTui(launchOptions);
 
   const handleSignal = () => void triggerShutdown();

package/src/config/schema.ts

@@ -82,7 +82,7 @@ export const DEFAULT_CONFIG: AppConfig = {
   },
   notifications: {
     toastsEnabled: true,
-    soundEnabled: false,
+    soundEnabled: true,
   },
   budgets: {
     daily: null,

package/src/demo/simulator.ts

@@ -488,7 +488,7 @@ export class DemoSimulator {
         limitReached: newPercent > 95,
         limits: {
           primary: {
-            ...existing.limits!.primary!,
+            ...existing.limits?.primary,
             usedPercent: newPercent,
           },
         },

package/src/plugins/agents/index.ts

@@ -1,4 +1,5 @@
 export { default as claudeCodeAgentPlugin } from "@tokentop/agent-claude-code";
 export { default as copilotCliAgentPlugin } from "@tokentop/agent-copilot-cli";
 export { default as cursorAgentPlugin } from "@tokentop/agent-cursor";
+export { default as geminiAgentPlugin } from "@tokentop/agent-gemini";
 export { default as opencodeAgentPlugin } from "@tokentop/agent-opencode";

package/src/plugins/lifecycle.ts

@@ -153,7 +153,7 @@ class PluginLifecycleManager {
     const ctx = this.makeCtx(entry);
     await safeInvoke(pluginId, "onConfigChange", () =>
       runInPluginGuard(pluginId, plugin.permissions, () =>
-        Promise.resolve(plugin.onConfigChange!(newConfig, ctx)),
+        Promise.resolve(plugin.onConfigChange?.(newConfig, ctx)),
       ),
     );
   }

package/src/plugins/notification-bus.ts

@@ -18,6 +18,16 @@ class NotificationBus {
   private plugins: NotificationPlugin[] = [];
   private recentEvents = new Map<string, DedupEntry>();
   private pluginConfigs = new Map<string, Record<string, unknown>>();
+  private toastHandler: ((event: NotificationEvent) => void) | null = null;
+  private flashHandler: ((severity: NotificationEvent["severity"]) => void) | null = null;
+
+  setToastHandler(handler: ((event: NotificationEvent) => void) | null): void {
+    this.toastHandler = handler;
+  }
+
+  setFlashHandler(handler: ((severity: NotificationEvent["severity"]) => void) | null): void {
+    this.flashHandler = handler;
+  }
 
   registerPlugins(plugins: NotificationPlugin[]): void {
     this.plugins = plugins;
@@ -124,6 +134,23 @@ class NotificationBus {
         );
       }),
     );
+
+    this.toastHandler?.(event);
+    this.flashHandler?.(event.severity);
+  }
+
+  async testNotification(): Promise<void> {
+    const event: NotificationEvent = {
+      type: "budget.thresholdCrossed",
+      severity: "warning",
+      title: "Test Notification",
+      message: "This is a test notification from tokentop.",
+      timestamp: Date.now(),
+      data: {},
+    };
+    // Bypass dedup for test
+    await this.emit("__test__", event);
+    this.recentEvents.delete("__test__");
   }
 
   private isDuplicate(key: string): boolean {