@tokentop/ttop 0.5.0 → 0.6.0

package/README.md

@@ -16,6 +16,7 @@ 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)
 
@@ -25,26 +26,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
+- **Session tracking** — See every coding agent session with model, tokens, cost, and duration. Built-in support for Claude Code, OpenCode, Cursor, and Copilot CLI
 - **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
@@ -56,7 +57,7 @@ https://github.com/user-attachments/assets/0b0225c7-a137-454b-9b29-c858cdcbd86c
 - **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, environment variables, and CLI auth files
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokentop/ttop",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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.86",
+    "@opentui/react": "0.1.86",
     "@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/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)),
       ),
     );
   }