@tokentop/ttop 0.6.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">
 
@@ -18,7 +17,9 @@ Real-time terminal monitoring of LLM token usage and spending across providers a
 [![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>
 
@@ -45,7 +46,7 @@ That's tokentop.
 
 - **Real-time dashboard** — Live token counts, costs, burn rate, and activity sparklines
 - **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
+- **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
@@ -53,11 +54,11 @@ That's tokentop.
 - **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, OpenCode, Cursor, Copilot CLI, 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
 
@@ -141,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
 
@@ -219,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
 
@@ -232,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
@@ -239,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.6.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",
@@ -34,8 +34,8 @@
     "analytics": "bun .opencode/skills/analytics/scripts/analytics.ts"
   },
   "dependencies": {
-    "@opentui/core": "0.1.86",
-    "@opentui/react": "0.1.86",
+    "@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",

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/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 {

package/src/plugins/notifications/terminal-bell.ts

@@ -4,6 +4,80 @@ import type {
   NotificationPlugin,
 } from "@tokentop/plugin-sdk";
 
+const SEVERITY_ORDER = ["info", "warning", "critical"];
+
+/**
+ * Write directly to stderr so the escape sequences bypass OpenTUI's
+ * stdout render pipeline. Most terminals still interpret BEL and OSC
+ * sequences arriving on fd 2.
+ */
+function writeEsc(data: string): void {
+  process.stderr.write(data);
+}
+
+/**
+ * OSC 777 (notify;title;body) — supported by iTerm2, Kitty, WezTerm, rxvt-unicode.
+ * OSC 9 (notify;body)         — supported by Windows Terminal, ConEmu.
+ * BEL (\x07)                  — universal fallback (if terminal has bell enabled).
+ *
+ * We send all three; unsupported sequences are silently ignored.
+ */
+function sendDesktopNotification(title: string, body: string): void {
+  writeEsc(`\x1b]777;notify;${title};${body}\x07`);
+  writeEsc(`\x1b]9;${title}: ${body}\x07`);
+  writeEsc("\x07");
+}
+
+/**
+ * macOS: afplay with system sounds (Ping, Funk, Glass, etc.)
+ * Linux: paplay → aplay → canberra-gtk-play (first available)
+ *
+ * Fire-and-forget — errors are silently ignored so a missing
+ * sound binary never breaks notifications.
+ */
+const SEVERITY_SOUNDS: Record<string, string> = {
+  critical: "Funk.aiff",
+  warning: "Ping.aiff",
+  info: "Pop.aiff",
+};
+
+function playSystemSound(severity: string): void {
+  const platform = process.platform;
+
+  if (platform === "darwin") {
+    const sound = SEVERITY_SOUNDS[severity] ?? "Ping.aiff";
+    Bun.spawn(["afplay", `/System/Library/Sounds/${sound}`], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return;
+  }
+
+  if (platform === "linux") {
+    const xdgSound =
+      severity === "critical"
+        ? "dialog-error"
+        : severity === "warning"
+          ? "dialog-warning"
+          : "dialog-information";
+
+    Bun.spawn(["canberra-gtk-play", "-i", xdgSound], {
+      stdout: "ignore",
+      stderr: "ignore",
+    }).exited.then((code) => {
+      if (code !== 0) {
+        Bun.spawn(["paplay", "/usr/share/sounds/freedesktop/stereo/bell.oga"], {
+          stdout: "ignore",
+          stderr: "ignore",
+        });
+      }
+    });
+    return;
+  }
+
+  // Windows / other — BEL only (already sent via sendDesktopNotification)
+}
+
 export const terminalBellPlugin: NotificationPlugin = {
   apiVersion: 2,
   id: "terminal-bell",
@@ -12,7 +86,7 @@ export const terminalBellPlugin: NotificationPlugin = {
   version: "1.0.0",
 
   meta: {
-    description: "Simple terminal bell (BEL character) for alerts",
+    description: "Desktop notification + system sound alerts",
   },
 
   permissions: {},
@@ -50,30 +124,20 @@ export const terminalBellPlugin: NotificationPlugin = {
   },
 
   async notify(ctx: NotificationContext, event: NotificationEvent): Promise<void> {
-    const severityOrder = ["info", "warning", "critical"];
     const minSeverity = (ctx.config.minSeverity as string) ?? "warning";
 
-    if (severityOrder.indexOf(event.severity) < severityOrder.indexOf(minSeverity)) {
+    if (SEVERITY_ORDER.indexOf(event.severity) < SEVERITY_ORDER.indexOf(minSeverity)) {
       return;
     }
 
-    const bellCount = event.severity === "critical" ? 3 : 1;
-
-    for (let i = 0; i < bellCount; i++) {
-      process.stdout.write("\x07");
-      if (i < bellCount - 1) {
-        await sleep(200);
-      }
-    }
+    sendDesktopNotification(event.title, event.message);
+    playSystemSound(event.severity);
   },
 
   async test(ctx: NotificationContext): Promise<boolean> {
     ctx.logger.info("Testing terminal bell...");
-    process.stdout.write("\x07");
+    sendDesktopNotification("tokentop", "Test notification");
+    playSystemSound("warning");
     return true;
   },
 };
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/plugins/notifications/visual-flash.ts

@@ -12,7 +12,7 @@ export const visualFlashPlugin: NotificationPlugin = {
   version: "1.0.0",
 
   meta: {
-    description: "Visual screen flash using ANSI escape sequences",
+    description: "Visual screen flash for alerts (rendered via TUI overlay)",
   },
 
   permissions: {},
@@ -27,7 +27,7 @@ export const visualFlashPlugin: NotificationPlugin = {
     duration: {
       type: "number",
       label: "Flash duration (ms)",
-      default: 100,
+      default: 150,
       description: "Flash duration in milliseconds",
     },
   },
@@ -44,26 +44,13 @@ export const visualFlashPlugin: NotificationPlugin = {
     ctx.logger.debug("Visual flash notification plugin initialized");
   },
 
-  async notify(ctx: NotificationContext, event: NotificationEvent): Promise<void> {
-    const duration = (ctx.config.duration as number) ?? 100;
-
-    const colorCode =
-      event.severity === "critical" ? "41" : event.severity === "warning" ? "43" : "42";
-
-    process.stdout.write(`\x1b[${colorCode}m`);
-    await sleep(duration);
-    process.stdout.write("\x1b[0m");
+  async notify(_ctx: NotificationContext, _event: NotificationEvent): Promise<void> {
+    // Flash is handled by the NotificationFlash React component via
+    // notificationBus.flashHandler — raw ANSI escapes conflict with OpenTUI.
   },
 
   async test(ctx: NotificationContext): Promise<boolean> {
     ctx.logger.info("Testing visual flash...");
-    process.stdout.write("\x1b[44m");
-    await sleep(100);
-    process.stdout.write("\x1b[0m");
     return true;
   },
 };
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/tui/App.tsx

@@ -16,6 +16,7 @@ import { copyToClipboard } from "@/utils/clipboard.ts";
 import { type CommandAction, CommandPalette } from "./components/CommandPalette.tsx";
 import { DebugPanel } from "./components/DebugPanel.tsx";
 import { Header } from "./components/Header.tsx";
+import { NotificationFlash } from "./components/NotificationFlash.tsx";
 import { SessionDetailsDrawer } from "./components/SessionDetailsDrawer.tsx";
 import { SettingsModal } from "./components/SettingsModal.tsx";
 import { StatusBar } from "./components/StatusBar.tsx";
@@ -35,6 +36,7 @@ import { RealTimeActivityProvider } from "./contexts/RealTimeActivityContext.tsx
 import { StorageProvider } from "./contexts/StorageContext.tsx";
 import { TimeWindowProvider } from "./contexts/TimeWindowContext.tsx";
 import { ToastProvider, useToastContext } from "./contexts/ToastContext.tsx";
+import { useNotificationBridge } from "./hooks/useNotificationBridge.ts";
 import { useSafeRenderer } from "./hooks/useSafeRenderer.ts";
 import { triggerShutdown } from "./shutdown.ts";
 import { Dashboard } from "./views/Dashboard.tsx";
@@ -68,6 +70,8 @@ function AppContent() {
   const { debugDataRef, activity, sparkData } = useDashboardRuntime();
   const burstRecorderRef = { current: null as BurstRecorder | null };
 
+  useNotificationBridge();
+
   const refreshInterval = config.refresh.pauseAutoRefresh ? 0 : config.refresh.intervalMs;
 
   const [lastRefresh, setLastRefresh] = useState<number | null>(null);
@@ -363,6 +367,8 @@ function AppContent() {
       {isDrawerOpen && selectedSession && (
         <SessionDetailsDrawer session={selectedSession} onClose={hideDrawer} />
       )}
+
+      <NotificationFlash />
     </box>
   );
 }

package/src/tui/components/NotificationFlash.tsx

@@ -0,0 +1,141 @@
+import type { NotificationEvent } from "@tokentop/plugin-sdk";
+import { useEffect, useRef, useState } from "react";
+import { notificationBus } from "@/plugins/notification-bus.ts";
+import { useColors } from "../contexts/ThemeContext.tsx";
+import { animationTick } from "../hooks/useAnimationTick.ts";
+import { Z_INDEX } from "./ModalBackdrop.tsx";
+
+/**
+ * Notification flash as an animated border glow.
+ *
+ * On notification:
+ *   0–15%   Overbright burst → alert color  (double border)
+ *   15–40%  Alert color fading              (double border)
+ *   40–100% Continuing fade → background    (single border, then unmount)
+ *
+ * Uses the global 30 Hz animation tick for smooth interpolation.
+ */
+
+const GLOW_DURATION_MS = 500;
+
+/** Bright, saturated alert colors — vivid regardless of theme */
+const GLOW_COLORS: Record<NotificationEvent["severity"], string> = {
+  critical: "#ff3333",
+  warning: "#ffaa22",
+  info: "#3399ff",
+};
+
+// ── Color math ──────────────────────────────────────────────
+
+function parseHex(hex: string): [number, number, number] {
+  const h = hex.replace("#", "");
+  return [
+    Number.parseInt(h.slice(0, 2), 16),
+    Number.parseInt(h.slice(2, 4), 16),
+    Number.parseInt(h.slice(4, 6), 16),
+  ];
+}
+
+function toHex(r: number, g: number, b: number): string {
+  const clamp = (v: number) => Math.max(0, Math.min(255, Math.round(v)));
+  return `#${[r, g, b].map((v) => clamp(v).toString(16).padStart(2, "0")).join("")}`;
+}
+
+/** Linearly interpolate two hex colors. t=0 → from, t=1 → to. */
+function lerpColor(from: string, to: string, t: number): string {
+  const [r1, g1, b1] = parseHex(from);
+  const [r2, g2, b2] = parseHex(to);
+  return toHex(r1 + (r2 - r1) * t, g1 + (g2 - g1) * t, b1 + (b2 - b1) * t);
+}
+
+/** Brighten a color by a factor (>1 = brighter). Clamps at 255. */
+function brighten(hex: string, factor = 1.4): string {
+  const [r, g, b] = parseHex(hex);
+  return toHex(r * factor, g * factor, b * factor);
+}
+
+/** easeOutCubic — fast attack, gentle tail */
+function easeOutCubic(t: number): number {
+  return 1 - (1 - t) ** 3;
+}
+
+// ── Component ───────────────────────────────────────────────
+
+export function NotificationFlash() {
+  const colors = useColors();
+  const [flash, setFlash] = useState<{
+    severity: NotificationEvent["severity"];
+    startTime: number;
+  } | null>(null);
+  const [borderColor, setBorderColor] = useState<string | null>(null);
+  const [borderStyle, setBorderStyle] = useState<"double" | "single">("double");
+  const unsubRef = useRef<(() => void) | null>(null);
+
+  // Register flash handler on the notification bus
+  useEffect(() => {
+    notificationBus.setFlashHandler((severity) => {
+      setFlash({ severity, startTime: Date.now() });
+    });
+    return () => notificationBus.setFlashHandler(null);
+  }, []);
+
+  // Drive the animation via the global 30 Hz tick
+  useEffect(() => {
+    if (!flash) {
+      setBorderColor(null);
+      return;
+    }
+
+    unsubRef.current?.();
+
+    const alertColor = GLOW_COLORS[flash.severity];
+    const brightColor = brighten(alertColor);
+    const bgColor = colors.background;
+
+    unsubRef.current = animationTick.subscribe((now) => {
+      const elapsed = now - flash.startTime;
+      const progress = Math.min(elapsed / GLOW_DURATION_MS, 1);
+
+      let currentColor: string;
+      if (progress < 0.15) {
+        // Burst phase: overbright → alert color
+        currentColor = lerpColor(brightColor, alertColor, progress / 0.15);
+      } else {
+        // Fade phase: alert → background (eased for gentle tail)
+        const fadeT = (progress - 0.15) / 0.85;
+        currentColor = lerpColor(alertColor, bgColor, easeOutCubic(fadeT));
+      }
+
+      setBorderColor(currentColor);
+      setBorderStyle(progress < 0.4 ? "double" : "single");
+
+      if (progress >= 1) {
+        unsubRef.current?.();
+        unsubRef.current = null;
+        setFlash(null);
+        setBorderColor(null);
+      }
+    });
+
+    return () => {
+      unsubRef.current?.();
+      unsubRef.current = null;
+    };
+  }, [flash, colors.background]);
+
+  if (!borderColor) return null;
+
+  return (
+    <box
+      position="absolute"
+      left={0}
+      top={0}
+      width="100%"
+      height="100%"
+      zIndex={Z_INDEX.TOAST + 1}
+      border
+      borderStyle={borderStyle}
+      borderColor={borderColor}
+    />
+  );
+}

package/src/tui/components/SettingsModal.tsx

@@ -2,6 +2,7 @@ import { useKeyboard, useTerminalDimensions } from "@opentui/react";
 import type { ConfigField, PluginType } from "@tokentop/plugin-sdk";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import type { AppConfig, SparklineOrientation, SparklineStyle } from "@/config/schema.ts";
+import { notificationBus } from "@/plugins/notification-bus.ts";
 import { formatBudgetDisplay, parseCurrencyInput } from "@/utils/currency.ts";
 import { useConfig } from "../contexts/ConfigContext.tsx";
 import { useDemoMode } from "../contexts/DemoModeContext.tsx";
@@ -20,10 +21,11 @@ interface SettingItem {
   description?: string;
   category: SettingCategory;
   pluginId?: string;
-  type: "toggle" | "select" | "number";
+  type: "toggle" | "select" | "number" | "action";
   options?: string[];
   getValue: (config: AppConfig) => string | number | boolean | null;
   setValue: (config: AppConfig, value: string | number | boolean | null) => AppConfig;
+  onAction?: () => void;
 }
 
 const BASE_SETTINGS: SettingItem[] = [
@@ -205,6 +207,16 @@ const BASE_SETTINGS: SettingItem[] = [
       notifications: { ...c.notifications, soundEnabled: v as boolean },
     }),
   },
+  {
+    key: "testNotification",
+    label: "Test Notifications",
+    description: "Send a test notification to verify toast, flash, and sound alerts are working.",
+    category: "notifications",
+    type: "action",
+    onAction: () => void notificationBus.testNotification(),
+    getValue: () => "▸ Run",
+    setValue: (c) => c,
+  },
 ];
 
 const CATEGORIES: { id: SettingCategory; label: string }[] = [
@@ -362,7 +374,7 @@ export function SettingsModal({ onClose }: SettingsModalProps) {
     provider: "Providers",
     agent: "Agents",
     theme: "Themes",
-    notification: "Delivery",
+    notification: "Notifications",
   };
 
   // Stable ordering for plugin type groups in sidebar
@@ -621,7 +633,9 @@ export function SettingsModal({ onClose }: SettingsModalProps) {
         setSelectedIndex((i) => Math.max(i - 1, 0));
       } else if (key.name === "return" || key.name === "space") {
         const setting = categorySettings[selectedIndex];
-        if (setting?.key === "theme") {
+        if (setting?.type === "action" && setting.onAction) {
+          setting.onAction();
+        } else if (setting?.key === "theme") {
           setShowThemePicker(true);
         } else if (setting?.type === "number") {
           startEditingNumber();
@@ -832,7 +846,9 @@ export function SettingsModal({ onClose }: SettingsModalProps) {
                       setting.type === "number" && editingSettingKey === setting.key;
 
                     let displayValue: string;
-                    if (setting.key === "theme") {
+                    if (setting.type === "action") {
+                      displayValue = "▸ Run";
+                    } else if (setting.key === "theme") {
                       const themeName = themes.find((t) => t.id === value)?.name ?? value;
                       displayValue = `${themeName} ▸`;
                     } else if (setting.type === "toggle") {

package/src/tui/components/Toast.tsx

@@ -8,7 +8,7 @@ interface ToastProps {
   type?: "info" | "success" | "warning" | "error";
 }
 
-export function Toast({ message, duration = 2000, onDismiss, type = "success" }: ToastProps) {
+export function Toast({ message, duration = 4000, onDismiss, type = "success" }: ToastProps) {
   const colors = useColors();
 
   useEffect(() => {

package/src/tui/contexts/PluginContext.tsx

@@ -241,6 +241,14 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
     initialize();
   }, []);
 
+  useEffect(() => {
+    if (!isInitialized) return;
+    notificationBus.setPluginConfig("terminal-bell", {
+      ...((config.pluginConfig ?? {})["terminal-bell"] ?? {}),
+      enabled: config.notifications.soundEnabled,
+    });
+  }, [config.notifications.soundEnabled, isInitialized]);
+
   const prevPluginConfigRef = useRef<Record<string, Record<string, unknown>>>({});
   useEffect(() => {
     if (!isInitialized) return;

package/src/tui/hooks/useNotificationBridge.ts

@@ -0,0 +1,29 @@
+import type { NotificationEvent } from "@tokentop/plugin-sdk";
+import { useEffect } from "react";
+import { notificationBus } from "@/plugins/notification-bus.ts";
+import { useToastContext } from "../contexts/ToastContext.tsx";
+
+function severityToToastType(
+  severity: NotificationEvent["severity"],
+): "info" | "warning" | "error" {
+  switch (severity) {
+    case "critical":
+      return "error";
+    case "warning":
+      return "warning";
+    default:
+      return "info";
+  }
+}
+
+export function useNotificationBridge(): void {
+  const { showToast } = useToastContext();
+
+  useEffect(() => {
+    const handler = (event: NotificationEvent) => {
+      showToast(event.title, severityToToastType(event.severity));
+    };
+    notificationBus.setToastHandler(handler);
+    return () => notificationBus.setToastHandler(null);
+  }, [showToast]);
+}

package/src/tui/views/SettingsView.tsx

@@ -2,6 +2,7 @@ import { useKeyboard, useTerminalDimensions } from "@opentui/react";
 import type { ConfigField } from "@tokentop/plugin-sdk";
 import { useCallback, useMemo, useState } from "react";
 import type { AppConfig } from "@/config/schema.ts";
+import { notificationBus } from "@/plugins/notification-bus.ts";
 import { useConfig } from "../contexts/ConfigContext.tsx";
 import { useDemoMode } from "../contexts/DemoModeContext.tsx";
 import { usePlugins } from "../contexts/PluginContext.tsx";
@@ -14,10 +15,11 @@ interface SettingItem {
   key: string;
   label: string;
   category: SettingCategory;
-  type: "toggle" | "select" | "number";
+  type: "toggle" | "select" | "number" | "action";
   options?: string[];
   getValue: (config: AppConfig) => string | number | boolean;
   setValue: (config: AppConfig, value: string | number | boolean) => AppConfig;
+  onAction?: () => void;
 }
 
 const SETTINGS: SettingItem[] = [
@@ -192,6 +194,15 @@ const SETTINGS: SettingItem[] = [
       notifications: { ...c.notifications, soundEnabled: v as boolean },
     }),
   },
+  {
+    key: "testNotification",
+    label: "Test Notifications",
+    category: "notifications",
+    type: "action",
+    onAction: () => void notificationBus.testNotification(),
+    getValue: () => "▸ Run",
+    setValue: (c) => c,
+  },
 ];
 
 const CATEGORIES: { id: SettingCategory; label: string }[] = [
@@ -384,6 +395,11 @@ export function SettingsView() {
       } else if (key.name === "up" || key.name === "k") {
         setSelectedIndex((i) => Math.max(i - 1, 0));
       } else if (key.name === "return" || key.name === "space") {
+        const setting = categorySettings[selectedIndex];
+        if (setting?.type === "action" && setting.onAction) {
+          setting.onAction();
+          return;
+        }
         toggleCurrentSetting();
       } else if (key.name === "left" || key.name === "h") {
         const setting = categorySettings[selectedIndex];
@@ -479,13 +495,15 @@ export function SettingsView() {
               >
                 <text fg={isSelected ? colors.background : colors.text}>{setting.label}</text>
                 <text fg={isSelected ? colors.background : colors.textMuted}>
-                  {setting.type === "toggle"
-                    ? value
-                      ? "● ON"
-                      : "○ OFF"
-                    : setting.type === "select"
-                      ? `◂ ${value} ▸`
-                      : String(value)}
+                  {setting.type === "action"
+                    ? "▸ Run"
+                    : setting.type === "toggle"
+                      ? value
+                        ? "● ON"
+                        : "○ OFF"
+                      : setting.type === "select"
+                        ? `◂ ${value} ▸`
+                        : String(value)}
                 </text>
               </box>
             );

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.6.0"; // x-release-please-version
+export const VERSION = "0.6.1"; // x-release-please-version