@tokentop/ttop 0.2.2 → 0.4.0

package/README.md

@@ -11,8 +11,7 @@ Real-time terminal monitoring of LLM token usage and spending across providers a
 
 ![Tokentop Dashboard](assets/Screenshot.png)
 
-<!-- TODO: uncomment CI badge when GitHub Actions workflow is set up -->
-<!-- [![CI](https://img.shields.io/github/actions/workflow/status/tokentopapp/tokentop/ci.yml?style=flat-square&label=CI)](https://github.com/tokentopapp/tokentop/actions) -->
+[![CI](https://img.shields.io/github/actions/workflow/status/tokentopapp/tokentop/ci.yml?style=flat-square&label=CI)](https://github.com/tokentopapp/tokentop/actions)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
 [![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/)
@@ -37,11 +36,9 @@ That's tokentop.
 - Set **budget alerts** so you don't wake up to a surprise bill
 - Runs **100% locally** — your usage data never leaves your machine
 
-<!-- TODO: Replace with VHS recording
 ## Demo
 
-> _Coming soon: VHS terminal recording_
--->
+https://github.com/user-attachments/assets/0b0225c7-a137-454b-9b29-c858cdcbd86c
 
 ## Features
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokentop/ttop",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Real-time AI token usage monitor - htop for your API costs",
   "author": "Nigel Bazzeghin <nbazzeghin@gmail.com>",
   "license": "MIT",
@@ -23,7 +23,9 @@
     "start": "bun src/cli.ts",
     "build": "bun build ./src/cli.ts --outdir=dist --target=bun --minify",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
+    "lint": "biome check src/",
+    "format": "biome format src/",
+    "lint:fix": "biome check --write src/",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "driver": "bun src/tui/driver/cli.ts",
@@ -31,16 +33,17 @@
     "snapshot": "bun src/tui/debug/snapshot.tsx"
   },
   "dependencies": {
-    "@opentui/core": "0.1.79",
-    "@opentui/react": "0.1.79",
+    "@opentui/core": "0.1.81",
+    "@opentui/react": "0.1.81",
     "@tokentop/agent-claude-code": "^1.1.0",
     "@tokentop/agent-opencode": "^1.0.0",
     "@tokentop/plugin-sdk": "^1.1.0",
     "react": "^19.0.0",
     "react-devtools-core": "^7.0.1",
-    "zod": "^3.24.0"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.2",
     "@types/bun": "latest",
     "@types/react": "^19.0.0"
   },

package/src/agents/aggregator.ts

@@ -1,13 +1,13 @@
-import type { SessionUsageData } from '@/plugins/types/agent.ts';
+import type { SessionUsageData } from "@/plugins/types/agent.ts";
 import {
-  totalTokenCount,
   type AgentId,
   type AgentName,
   type AgentSessionAggregate,
   type AgentSessionStream,
   type StreamWindowedTokens,
   type TokenCounts,
-} from './types.ts';
+  totalTokenCount,
+} from "./types.ts";
 
 const ACTIVE_THRESHOLD_MS = 2 * 60 * 1000;
 
@@ -33,21 +33,29 @@ function sumTokens(a: TokenCounts, b: TokenCounts): TokenCounts {
     input: a.input + b.input,
     output: a.output + b.output,
   };
-  
+
   const cacheRead = (a.cacheRead ?? 0) + (b.cacheRead ?? 0);
   if (cacheRead > 0) result.cacheRead = cacheRead;
-  
+
   const cacheWrite = (a.cacheWrite ?? 0) + (b.cacheWrite ?? 0);
   if (cacheWrite > 0) result.cacheWrite = cacheWrite;
-  
+
   return result;
 }
 
 function computeWindowBoundaries(now: number) {
   const nowDate = new Date(now);
-  const startOfDay = new Date(nowDate.getFullYear(), nowDate.getMonth(), nowDate.getDate()).getTime();
+  const startOfDay = new Date(
+    nowDate.getFullYear(),
+    nowDate.getMonth(),
+    nowDate.getDate(),
+  ).getTime();
   const dayOfWeek = nowDate.getDay();
-  const startOfWeek = new Date(nowDate.getFullYear(), nowDate.getMonth(), nowDate.getDate() - dayOfWeek).getTime();
+  const startOfWeek = new Date(
+    nowDate.getFullYear(),
+    nowDate.getMonth(),
+    nowDate.getDate() - dayOfWeek,
+  ).getTime();
   const startOfMonth = new Date(nowDate.getFullYear(), nowDate.getMonth(), 1).getTime();
   return { startOfDay, startOfWeek, startOfMonth };
 }
@@ -60,16 +68,25 @@ interface StreamAccumulator {
 }
 
 export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAggregate[] {
-  const { agentId, agentName, rows, now = Date.now(), activeThresholdMs = ACTIVE_THRESHOLD_MS } = options;
+  const {
+    agentId,
+    agentName,
+    rows,
+    now = Date.now(),
+    activeThresholdMs = ACTIVE_THRESHOLD_MS,
+  } = options;
   const { startOfDay, startOfWeek, startOfMonth } = computeWindowBoundaries(now);
 
-  const sessionMap = new Map<string, {
-    sessionName?: string;
-    projectPath?: string;
-    timestamps: number[];
-    sessionUpdatedAt?: number;
-    streamMap: Map<string, StreamAccumulator>;
-  }>();
+  const sessionMap = new Map<
+    string,
+    {
+      sessionName?: string;
+      projectPath?: string;
+      timestamps: number[];
+      sessionUpdatedAt?: number;
+      streamMap: Map<string, StreamAccumulator>;
+    }
+  >();
 
   for (const row of rows) {
     const existing = sessionMap.get(row.sessionId);
@@ -89,7 +106,7 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
       if (row.sessionUpdatedAt) newSession.sessionUpdatedAt = row.sessionUpdatedAt;
       sessionMap.set(row.sessionId, newSession);
     }
-    
+
     const session = sessionMap.get(row.sessionId)!;
 
     session.timestamps.push(row.timestamp);
@@ -99,7 +116,10 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
     if (row.projectPath && !session.projectPath) {
       session.projectPath = row.projectPath;
     }
-    if (row.sessionUpdatedAt && (!session.sessionUpdatedAt || row.sessionUpdatedAt > session.sessionUpdatedAt)) {
+    if (
+      row.sessionUpdatedAt &&
+      (!session.sessionUpdatedAt || row.sessionUpdatedAt > session.sessionUpdatedAt)
+    ) {
       session.sessionUpdatedAt = row.sessionUpdatedAt;
     }
 
@@ -133,7 +153,7 @@ export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAg
     const startedAt = Math.min(...session.timestamps);
     const lastActivityAt = Math.max(...session.timestamps);
     const lastSeenAt = session.sessionUpdatedAt ?? lastActivityAt;
-    const status = (now - lastSeenAt) <= activeThresholdMs ? 'active' : 'idle';
+    const status = now - lastSeenAt <= activeThresholdMs ? "active" : "idle";
 
     const streams: AgentSessionStream[] = [];
     const streamWindowedTokens = new Map<string, StreamWindowedTokens>();

package/src/agents/costing.ts

@@ -1,16 +1,16 @@
-import { getPricing, estimateCost } from '@/pricing/index.ts';
-import type { AgentSessionAggregate, AgentSessionStream, StreamCostBreakdown } from './types.ts';
+import { estimateCost, getPricing } from "@/pricing/index.ts";
+import type { AgentSessionAggregate, AgentSessionStream, StreamCostBreakdown } from "./types.ts";
 
 export async function priceStream(stream: AgentSessionStream): Promise<AgentSessionStream> {
   const pricing = await getPricing(stream.providerId, stream.modelId);
-  
+
   if (!pricing) {
-    return { ...stream, pricingSource: 'unknown' };
+    return { ...stream, pricingSource: "unknown" };
   }
 
   const breakdown = estimateCost(stream.tokens, pricing);
-  const source = pricing.source === 'models.dev' ? 'models.dev' : 'fallback';
-  
+  const source = pricing.source === "models.dev" ? "models.dev" : "fallback";
+
   const costBreakdown: StreamCostBreakdown = {
     total: breakdown.total,
     input: breakdown.input ?? 0,
@@ -29,12 +29,12 @@ export async function priceStream(stream: AgentSessionStream): Promise<AgentSess
 
 export async function priceSession(session: AgentSessionAggregate): Promise<AgentSessionAggregate> {
   const pricedStreams = await Promise.all(session.streams.map(priceStream));
-  
+
   const totalCostUsd = pricedStreams.reduce((sum, s) => {
     return sum + (s.costUsd ?? 0);
   }, 0);
 
-  const hasAnyCost = pricedStreams.some(s => s.costUsd !== undefined);
+  const hasAnyCost = pricedStreams.some((s) => s.costUsd !== undefined);
 
   let costInDay = 0;
   let costInWeek = 0;
@@ -69,6 +69,8 @@ export async function priceSession(session: AgentSessionAggregate): Promise<Agen
   return result;
 }
 
-export async function priceSessions(sessions: AgentSessionAggregate[]): Promise<AgentSessionAggregate[]> {
+export async function priceSessions(
+  sessions: AgentSessionAggregate[],
+): Promise<AgentSessionAggregate[]> {
   return Promise.all(sessions.map(priceSession));
 }

package/src/agents/index.ts

@@ -1,12 +1,10 @@
+export { aggregateSessionUsage } from "./aggregator.ts";
+export { priceSession, priceSessions, priceStream } from "./costing.ts";
 export type {
-  AgentName,
   AgentId,
-  TokenCounts,
-  AgentSessionStream,
-  AgentSessionAggregate,
   AgentInfo,
-} from './types.ts';
-
-export { aggregateSessionUsage } from './aggregator.ts';
-
-export { priceStream, priceSession, priceSessions } from './costing.ts';
+  AgentName,
+  AgentSessionAggregate,
+  AgentSessionStream,
+  TokenCounts,
+} from "./types.ts";

package/src/agents/types.ts

@@ -29,7 +29,7 @@ export interface AgentSessionStream {
   requestCount: number;
   costUsd?: number;
   costBreakdown?: StreamCostBreakdown;
-  pricingSource?: 'models.dev' | 'fallback' | 'unknown';
+  pricingSource?: "models.dev" | "fallback" | "unknown";
 }
 
 export interface StreamWindowedTokens {
@@ -48,7 +48,7 @@ export interface AgentSessionAggregate {
   startedAt: number;
   lastActivityAt: number;
   endedAt?: number;
-  status: 'active' | 'idle';
+  status: "active" | "idle";
   totals: TokenCounts;
   totalCostUsd?: number;
   requestCount: number;

package/src/cli.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env bun
-import * as path from 'path';
-import { startTui, type TuiOptions } from './tui/index.tsx';
-import type { DemoPreset } from './demo/simulator.ts';
-import { VERSION } from './version.ts';
+import * as path from "path";
+import type { DemoPreset } from "./demo/simulator.ts";
+import { startTui, type TuiOptions } from "./tui/index.tsx";
+import { triggerShutdown } from "./tui/shutdown.ts";
+import { VERSION } from "./version.ts";
 
-const DEMO_PRESETS: DemoPreset[] = ['light', 'normal', 'heavy'];
+const DEMO_PRESETS: DemoPreset[] = ["light", "normal", "heavy"];
 
 function printHelp() {
   console.log(`
@@ -57,11 +58,11 @@ function printVersion() {
 
 async function main() {
   const args = process.argv.slice(2);
-  
+
   // Check for subcommands first
-  const subcommand = args[0] && !args[0].startsWith('-') ? args[0] : null;
+  const subcommand = args[0] && !args[0].startsWith("-") ? args[0] : null;
   const commandArgs = subcommand ? args.slice(1) : args;
-  
+
   let refreshInterval = 60000;
   let debug = false;
   let demo = false;
@@ -70,7 +71,7 @@ async function main() {
   const cliPlugins: string[] = [];
 
   // Handle demo subcommand
-  if (subcommand === 'demo') {
+  if (subcommand === "demo") {
     demo = true;
   } else if (subcommand !== null) {
     console.error(`Error: Unknown command "${subcommand}"`);
@@ -81,24 +82,24 @@ async function main() {
   for (let i = 0; i < commandArgs.length; i++) {
     const arg = commandArgs[i];
 
-    if (arg === '-h' || arg === '--help') {
+    if (arg === "-h" || arg === "--help") {
       printHelp();
       process.exit(0);
     }
 
-    if (arg === '-v' || arg === '--version') {
+    if (arg === "-v" || arg === "--version") {
       printVersion();
       process.exit(0);
     }
 
-    if (arg === '-d' || arg === '--debug') {
+    if (arg === "-d" || arg === "--debug") {
       debug = true;
     }
 
-    if (arg === '-p' || arg === '--plugin') {
+    if (arg === "-p" || arg === "--plugin") {
       const pluginPath = commandArgs[++i];
       if (!pluginPath) {
-        console.error('Error: --plugin requires a path');
+        console.error("Error: --plugin requires a path");
         process.exit(1);
       }
       const resolved = path.resolve(pluginPath);
@@ -106,38 +107,38 @@ async function main() {
     }
 
     // Demo subcommand options
-    if (arg === '--seed') {
+    if (arg === "--seed") {
       if (!demo) {
-        console.error('Error: --seed can only be used with the demo command');
+        console.error("Error: --seed can only be used with the demo command");
         process.exit(1);
       }
       const seedStr = commandArgs[++i];
       const seed = seedStr ? parseInt(seedStr, 10) : NaN;
       if (isNaN(seed)) {
-        console.error('Error: --seed requires a number');
+        console.error("Error: --seed requires a number");
         process.exit(1);
       }
       demoSeed = seed;
     }
 
-    if (arg === '--preset') {
+    if (arg === "--preset") {
       if (!demo) {
-        console.error('Error: --preset can only be used with the demo command');
+        console.error("Error: --preset can only be used with the demo command");
         process.exit(1);
       }
       const preset = commandArgs[++i] as DemoPreset;
       if (!preset || !DEMO_PRESETS.includes(preset)) {
-        console.error(`Error: --preset must be one of: ${DEMO_PRESETS.join(', ')}`);
+        console.error(`Error: --preset must be one of: ${DEMO_PRESETS.join(", ")}`);
         process.exit(1);
       }
       demoPreset = preset;
     }
 
-    if (arg === '-r' || arg === '--refresh') {
+    if (arg === "-r" || arg === "--refresh") {
       const intervalStr = commandArgs[++i];
       const interval = intervalStr ? parseInt(intervalStr, 10) : NaN;
       if (isNaN(interval) || interval < 1000) {
-        console.error('Error: --refresh must be a number >= 1000');
+        console.error("Error: --refresh must be a number >= 1000");
         process.exit(1);
       }
       refreshInterval = interval;
@@ -159,9 +160,13 @@ async function main() {
     launchOptions.demoPreset = demoPreset;
   }
   await startTui(launchOptions);
+
+  const handleSignal = () => void triggerShutdown();
+  process.on("SIGINT", handleSignal);
+  process.on("SIGTERM", handleSignal);
 }
 
 main().catch((err) => {
-  console.error('Fatal error:', err);
+  console.error("Fatal error:", err);
   process.exit(1);
 });

package/src/config/schema.test.ts

@@ -1,24 +1,24 @@
-import * as fs from 'fs/promises';
-import { afterEach, describe, expect, spyOn, test } from 'bun:test';
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import * as fs from "fs/promises";
 
-import { DEFAULT_CONFIG, loadConfig } from './schema.ts';
+import { DEFAULT_CONFIG, loadConfig } from "./schema.ts";
 
-const readFileSpies: Array<ReturnType<typeof spyOn<typeof fs, 'readFile'>>> = [];
+const readFileSpies: Array<ReturnType<typeof spyOn<typeof fs, "readFile">>> = [];
 
 function mockReadFileWithJson(config: unknown) {
-  const spy = spyOn(fs, 'readFile');
+  const spy = spyOn(fs, "readFile");
   spy.mockResolvedValue(JSON.stringify(config));
   readFileSpies.push(spy);
 }
 
 function mockReadFileWithRaw(content: string) {
-  const spy = spyOn(fs, 'readFile');
+  const spy = spyOn(fs, "readFile");
   spy.mockResolvedValue(content);
   readFileSpies.push(spy);
 }
 
 function mockReadFileError(error: Error) {
-  const spy = spyOn(fs, 'readFile');
+  const spy = spyOn(fs, "readFile");
   spy.mockRejectedValue(error);
   readFileSpies.push(spy);
 }
@@ -30,28 +30,28 @@ afterEach(() => {
   readFileSpies.length = 0;
 });
 
-describe('DEFAULT_CONFIG', () => {
-  test('has expected top-level structure', () => {
+describe("DEFAULT_CONFIG", () => {
+  test("has expected top-level structure", () => {
     expect(Object.keys(DEFAULT_CONFIG).sort()).toEqual(
       [
-        'alerts',
-        'budgets',
-        'configVersion',
-        'display',
-        'notifications',
-        'pluginConfig',
-        'plugins',
-        'providers',
-        'refresh',
-      ].sort()
+        "alerts",
+        "budgets",
+        "configVersion",
+        "display",
+        "notifications",
+        "pluginConfig",
+        "plugins",
+        "providers",
+        "refresh",
+      ].sort(),
     );
   });
 
-  test('uses expected default values', () => {
+  test("uses expected default values", () => {
     expect(DEFAULT_CONFIG.refresh.intervalMs).toBe(60000);
-    expect(DEFAULT_CONFIG.display.defaultTimeWindow).toBe('1h');
-    expect(DEFAULT_CONFIG.display.theme).toBe('tokyo-night');
-    expect(DEFAULT_CONFIG.display.colorScheme).toBe('auto');
+    expect(DEFAULT_CONFIG.display.defaultTimeWindow).toBe("1h");
+    expect(DEFAULT_CONFIG.display.theme).toBe("tokyo-night");
+    expect(DEFAULT_CONFIG.display.colorScheme).toBe("auto");
 
     expect(DEFAULT_CONFIG.budgets.daily).toBeNull();
     expect(DEFAULT_CONFIG.budgets.weekly).toBeNull();
@@ -66,21 +66,21 @@ describe('DEFAULT_CONFIG', () => {
   });
 });
 
-describe('loadConfig', () => {
+describe("loadConfig", () => {
   test("returns defaults when config file doesn't exist", async () => {
-    mockReadFileError(new Error('ENOENT'));
+    mockReadFileError(new Error("ENOENT"));
 
     const loaded = await loadConfig();
 
     expect(loaded).toEqual(DEFAULT_CONFIG);
   });
 
-  test('merges partial overrides with defaults', async () => {
+  test("merges partial overrides with defaults", async () => {
     mockReadFileWithJson({
       refresh: { intervalMs: 15000 },
       budgets: { daily: 25 },
       alerts: { warningPercent: 70 },
-      plugins: { local: ['~/plugins/local-theme.ts'] },
+      plugins: { local: ["~/plugins/local-theme.ts"] },
     });
 
     const loaded = await loadConfig();
@@ -91,40 +91,42 @@ describe('loadConfig', () => {
     expect(loaded.budgets.weekly).toBeNull();
     expect(loaded.alerts.warningPercent).toBe(70);
     expect(loaded.alerts.criticalPercent).toBe(DEFAULT_CONFIG.alerts.criticalPercent);
-    expect(loaded.plugins.local).toEqual(['~/plugins/local-theme.ts']);
+    expect(loaded.plugins.local).toEqual(["~/plugins/local-theme.ts"]);
     expect(loaded.plugins.npm).toEqual([]);
   });
 
-  test('applies nested display overrides without dropping sibling defaults', async () => {
+  test("applies nested display overrides without dropping sibling defaults", async () => {
     mockReadFileWithJson({
-      display: { theme: 'dracula' },
+      display: { theme: "dracula" },
     });
 
     const loaded = await loadConfig();
 
-    expect(loaded.display.theme).toBe('dracula');
+    expect(loaded.display.theme).toBe("dracula");
     expect(loaded.display.defaultTimeWindow).toBe(DEFAULT_CONFIG.display.defaultTimeWindow);
     expect(loaded.display.colorScheme).toBe(DEFAULT_CONFIG.display.colorScheme);
     expect(loaded.display.timeFormat).toBe(DEFAULT_CONFIG.display.timeFormat);
   });
 
-  test('deep merges display.sparkline.style while preserving other sparkline defaults', async () => {
+  test("deep merges display.sparkline.style while preserving other sparkline defaults", async () => {
     mockReadFileWithJson({
       display: {
         sparkline: {
-          style: 'block',
+          style: "block",
         },
       },
     });
 
     const loaded = await loadConfig();
 
-    expect(loaded.display.sparkline.style).toBe('block');
+    expect(loaded.display.sparkline.style).toBe("block");
     expect(loaded.display.sparkline.orientation).toBe(DEFAULT_CONFIG.display.sparkline.orientation);
-    expect(loaded.display.sparkline.showBaseline).toBe(DEFAULT_CONFIG.display.sparkline.showBaseline);
+    expect(loaded.display.sparkline.showBaseline).toBe(
+      DEFAULT_CONFIG.display.sparkline.showBaseline,
+    );
   });
 
-  test('falls back to defaults for invalid JSON', async () => {
+  test("falls back to defaults for invalid JSON", async () => {
     mockReadFileWithRaw(`{
       // comments are not valid JSON
       "display": { "theme": "dracula" }
@@ -134,7 +136,7 @@ describe('loadConfig', () => {
     expect(loaded.display.theme).toBe(DEFAULT_CONFIG.display.theme);
   });
 
-  test('parses valid JSON with budget overrides', async () => {
+  test("parses valid JSON with budget overrides", async () => {
     mockReadFileWithRaw(`{
       "budgets": { "daily": 100 }
     }`);
@@ -143,7 +145,7 @@ describe('loadConfig', () => {
     expect(loaded.budgets.daily).toBe(100);
   });
 
-  test('parses valid JSON with multiple overrides', async () => {
+  test("parses valid JSON with multiple overrides", async () => {
     mockReadFileWithRaw(`{
       "budgets": { "daily": 50, "weekly": 200 },
       "alerts": { "warningPercent": 90 }
@@ -155,12 +157,12 @@ describe('loadConfig', () => {
     expect(loaded.alerts.warningPercent).toBe(90);
   });
 
-  test('does not strip // inside string values', async () => {
+  test("does not strip // inside string values", async () => {
     mockReadFileWithRaw(`{
       "plugins": { "local": ["~/my-plugin // v2"] }
     }`);
 
     const loaded = await loadConfig();
-    expect(loaded.plugins.local).toEqual(['~/my-plugin // v2']);
+    expect(loaded.plugins.local).toEqual(["~/my-plugin // v2"]);
   });
 });