@settinghead/voxlert 0.3.8 → 0.3.10

package/README.md

@@ -12,7 +12,7 @@
 
 # Voxlert
 
-LLM-generated voice notifications for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com/docs/agent/hooks), [OpenAI Codex](https://developers.openai.com/codex/), and [OpenClaw](https://openclaw.dev), spoken by game characters like the StarCraft Adjutant, Kerrigan, C&C EVA, SHODAN, and more.
+LLM-generated voice notifications for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com/docs/agent/hooks), [OpenAI Codex](https://developers.openai.com/codex/), [pi](https://github.com/badlogic/pi-mono), and [OpenClaw](https://openclaw.dev), spoken by game characters like the StarCraft Adjutant, Kerrigan, C&C EVA, SHODAN, and more.
 
 ## Why Voxlert?
 
@@ -24,7 +24,7 @@ Voxlert makes each session speak in a distinct character voice with its own tone
 
 Voxlert is for users who:
 
-- Run two or more AI coding agent sessions concurrently (Claude Code, Cursor, Codex, OpenClaw)
+- Run two or more AI coding agent sessions concurrently (Claude Code, Cursor, Codex, pi, OpenClaw)
 - Get interrupted by notification chimes but can't tell which window needs attention
 - Want ambient audio feedback that doesn't require looking at a screen
 - Are comfortable installing local tooling (Node.js, optionally Python for TTS)
@@ -62,8 +62,7 @@ The setup wizard auto-detects running TTS backends. If none are running yet, set
 ### 2. Install and run setup
 
 ```bash
-npm install -g @settinghead/voxlert
-voxlert setup
+npx voxlert --onboard
 ```
 
 The setup wizard configures:
@@ -72,7 +71,7 @@ The setup wizard configures:
 - Voice pack downloads
 - Active voice pack
 - TTS backend
-- Platform hooks for Claude Code, Cursor, and Codex
+- Platform hooks for Claude Code, Cursor, Codex, and pi
 
 For OpenClaw, install the separate [OpenClaw plugin](docs/openclaw.md).
 
@@ -189,6 +188,27 @@ voxlert codex-notify
 
 `voxlert setup` can install or update the `notify` entry in `~/.codex/config.toml`. See [Codex integration](docs/codex.md).
 
+### pi
+
+Installed through `voxlert setup`, which copies a TypeScript extension to `~/.pi/agent/extensions/voxlert.ts`. Alternatively, install the pi package directly:
+
+```bash
+pi install npm:@settinghead/pi-voxlert
+```
+
+The extension hooks into pi's lifecycle events and pipes them through `voxlert hook`:
+
+| pi Event | Voxlert Event | Category |
+|---|---|---|
+| `agent_end` | Stop | `task.complete` |
+| `tool_result` (error) | PostToolUseFailure | `task.error` |
+| `session_shutdown` | SessionEnd | `session.end` |
+| `session_before_compact` | PreCompact | `resource.limit` |
+
+The extension also registers a `/voxlert` command (test, status) and a `voxlert_speak` tool that lets the LLM speak phrases on demand.
+
+Run `/reload` in pi or start a new session after installing. See the [pi-voxlert README](pi-package/README.md) for details.
+
 ### OpenClaw
 
 OpenClaw uses a separate plugin. See [OpenClaw integration](docs/openclaw.md) for installation, config, and troubleshooting.
@@ -219,6 +239,7 @@ flowchart TD
     A2[OpenClaw Plugin] --> B
     A3[Cursor Hook] --> B
     A4[Codex notify] --> B
+    A5[pi Extension] --> B
     B --> C[src/voxlert.js]
     C --> D{Event type?}
     D -- "Contextual (e.g. Stop)" --> E[LLM<br><i>generate in-character phrase</i>]
@@ -234,7 +255,7 @@ flowchart TD
     J --> K[afplay / ffplay]
 ```
 
-1. A hook or notify event fires from Claude Code, Cursor, Codex, or OpenClaw.
+1. A hook or notify event fires from Claude Code, Cursor, Codex, pi, or OpenClaw.
 2. Voxlert maps it to an event category and loads the active voice pack.
 3. Contextual events such as task completion or tool failure can use the configured LLM to generate a short in-character phrase.
 4. Other events use predefined fallback phrases from the pack.
@@ -279,7 +300,7 @@ Run `voxlert config path` to find `config.json`. You can edit it directly or use
 
 ### Event categories
 
-Event categories apply across Claude Code, Cursor, Codex, and OpenClaw where the corresponding event exists.
+Event categories apply across Claude Code, Cursor, Codex, pi, and OpenClaw where the corresponding event exists.
 
 | Category | Hook Event | Description | Default |
 |---|---|---|---|
@@ -322,9 +343,9 @@ You can also manage configuration interactively with the `/voxlert-config` slash
 
 ### Integration behavior
 
-- `voxlert setup` installs hooks for Claude Code, Cursor, and Codex.
+- `voxlert setup` installs hooks for Claude Code, Cursor, Codex, and pi.
 - Re-run setup anytime to add a platform you skipped earlier.
-- `voxlert uninstall` removes Claude Code, Cursor, and Codex integration.
+- `voxlert uninstall` removes Claude Code, Cursor, Codex, and pi integration.
 - OpenClaw is managed separately through its plugin.
 - The global `enabled` flag disables processing everywhere; there is no separate per-integration toggle in `config.json`.
 
@@ -354,7 +375,7 @@ voxlert notification           # Choose notification style (popup / system / off
 voxlert test "<text>"          # Run full pipeline: LLM -> TTS -> audio playback
 voxlert cost                   # Show accumulated token usage and estimated cost
 voxlert cost reset             # Clear the usage log
-voxlert uninstall              # Remove hooks from Claude Code, Cursor, and Codex, optionally config/cache
+voxlert uninstall              # Remove hooks from Claude Code, Cursor, Codex, and pi, optionally config/cache
 voxlert help                   # Show help
 voxlert --version              # Show version
 ```
@@ -372,7 +393,7 @@ voxlert uninstall
 npm uninstall -g @settinghead/voxlert
 ```
 
-This removes Voxlert hooks from Claude Code, Cursor, and Codex, the `voxlert-config` skill, and optionally your local config and cache in `~/.voxlert`.
+This removes Voxlert hooks from Claude Code, Cursor, Codex, and pi, the `voxlert-config` skill, and optionally your local config and cache in `~/.voxlert`.
 
 ## Advanced
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@settinghead/voxlert",
-  "version": "0.3.8",
-  "description": "LLM-generated voice notifications for Claude Code, Cursor, OpenAI Codex, and OpenClaw, spoken by game characters like the StarCraft Adjutant, Kerrigan, C&C EVA, SHODAN, and more.",
+  "version": "0.3.10",
+  "description": "LLM-generated voice notifications for Claude Code, Cursor, OpenAI Codex, pi, and OpenClaw, spoken by game characters like the StarCraft Adjutant, Kerrigan, C&C EVA, SHODAN, and more.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/settinghead/voxlert.git"
@@ -16,6 +16,7 @@
     "packs/*/pack.json",
     "packs/*/voice.wav",
     "skills/",
+    "pi-package/extensions/",
     "assets/*.png",
     "assets/*.jpg",
     "assets/*.gif",
@@ -33,8 +34,7 @@
     "test": "node --test ./test/*.test.js"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "license": "MIT",
   "dependencies": {

package/pi-package/extensions/voxlert.ts

@@ -0,0 +1,231 @@
+/**
+ * pi-voxlert — Voice notifications for pi coding sessions.
+ *
+ * Hooks into pi agent lifecycle events and pipes them through the Voxlert CLI
+ * to generate contextual, in-character voice notifications spoken by game
+ * characters (SHODAN, StarCraft Adjutant, C&C EVA, HEV Suit, etc.).
+ *
+ * Prerequisites:
+ *   npm install -g @settinghead/voxlert
+ *   voxlert setup
+ *
+ * The extension calls `voxlert hook` with the event data on stdin, so whatever
+ * TTS backend + voice pack + LLM backend you configured via `voxlert config`
+ * is used automatically.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { execSync, spawn } from "node:child_process";
+import { basename } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve the voxlert binary path, or null if not installed. */
+function findVoxlert(): string | null {
+  try {
+    return execSync("which voxlert", { encoding: "utf-8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Pipe an event through `voxlert hook` (fire-and-forget, async). */
+function fireVoxlert(
+  eventName: string,
+  cwd: string,
+  extra: Record<string, unknown> = {},
+): void {
+  const payload = JSON.stringify({
+    hook_event_name: eventName,
+    cwd,
+    source: "pi",
+    ...extra,
+  });
+
+  const child = spawn("voxlert", ["hook"], {
+    stdio: ["pipe", "ignore", "ignore"],
+    detached: true,
+  });
+
+  child.stdin.write(payload);
+  child.stdin.end();
+  child.unref(); // don't block pi on audio playback
+}
+
+/** Check if Voxlert CLI is installed and available. */
+function isVoxlertAvailable(): boolean {
+  return findVoxlert() !== null;
+}
+
+/**
+ * Extract the last assistant message text from pi's event messages array.
+ * Handles both direct message format and session entry format.
+ */
+function extractLastAssistantText(messages: unknown[]): string {
+  if (!Array.isArray(messages)) return "";
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i] as any;
+    // Handle session entry format: { type: "message", message: { role, content } }
+    const actualMsg = msg?.message || msg;
+
+    if (actualMsg?.role === "assistant") {
+      const content = actualMsg.content;
+      if (typeof content === "string") return content.slice(0, 500);
+      if (Array.isArray(content)) {
+        return content
+          .filter((c: any) => c.type === "text")
+          .map((c: any) => c.text)
+          .join("\n")
+          .slice(0, 500);
+      }
+    }
+  }
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+export default function (pi: ExtensionAPI) {
+  let available = isVoxlertAvailable();
+
+  // ------------------------------------------------------------------
+  // Session start: verify Voxlert is installed, fire SessionStart
+  // ------------------------------------------------------------------
+  pi.on("session_start", async (_event, ctx) => {
+    available = isVoxlertAvailable();
+    if (!available) {
+      ctx.ui.notify(
+        "Voxlert not found. Install with: npm install -g @settinghead/voxlert && voxlert setup",
+        "warning",
+      );
+    } else {
+      ctx.ui.setStatus("voxlert", "🔊 Voxlert");
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // Agent end → "Stop" hook (task finished, waiting for input)
+  // Passes last_assistant_message so the LLM can generate a
+  // contextual phrase about what just happened.
+  // ------------------------------------------------------------------
+  pi.on("agent_end", async (event, ctx) => {
+    if (!available) return;
+
+    const messages = (event as any).messages || [];
+    const lastAssistantMessage = extractLastAssistantText(messages);
+
+    fireVoxlert("Stop", ctx.cwd, {
+      last_assistant_message: lastAssistantMessage,
+    });
+  });
+
+  // ------------------------------------------------------------------
+  // Tool errors → "PostToolUseFailure" hook (contextual event)
+  // ------------------------------------------------------------------
+  pi.on("tool_result", async (event, ctx) => {
+    if (!available) return;
+    if (event.isError) {
+      const text =
+        event.content
+          ?.filter((c: any) => c.type === "text")
+          .map((c: any) => c.text)
+          .join("\n")
+          .slice(0, 500) || "";
+
+      fireVoxlert("PostToolUseFailure", ctx.cwd, {
+        error_message: `${event.toolName}: ${text}`,
+      });
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // Session shutdown → "SessionEnd" hook
+  // ------------------------------------------------------------------
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (!available) return;
+    fireVoxlert("SessionEnd", ctx.cwd);
+  });
+
+  // ------------------------------------------------------------------
+  // Context compaction → "PreCompact" hook
+  // ------------------------------------------------------------------
+  pi.on("session_before_compact", async (_event, ctx) => {
+    if (!available) return;
+    fireVoxlert("PreCompact", ctx.cwd);
+  });
+
+  // ------------------------------------------------------------------
+  // /voxlert command — quick controls
+  // ------------------------------------------------------------------
+  pi.registerCommand("voxlert", {
+    description: "Voxlert voice notifications: test, status, or configure",
+    handler: async (args, ctx) => {
+      const sub = (args || "").trim().split(/\s+/)[0];
+
+      if (sub === "test") {
+        if (!available) {
+          ctx.ui.notify("Voxlert CLI not installed.", "error");
+          return;
+        }
+        fireVoxlert("Stop", ctx.cwd);
+        ctx.ui.notify("Sent test notification.", "info");
+        return;
+      }
+
+      if (sub === "status") {
+        ctx.ui.notify(
+          available
+            ? "Voxlert is active. Voice notifications will play on agent_end, tool errors, compaction, and session end."
+            : "Voxlert CLI not found. Run: npm install -g @settinghead/voxlert && voxlert setup",
+          available ? "info" : "warning",
+        );
+        return;
+      }
+
+      // Default: show help
+      ctx.ui.notify(
+        "Usage: /voxlert [test|status]\n" +
+          "  test   — fire a test voice notification\n" +
+          "  status — check if Voxlert CLI is available\n" +
+          "\nConfigure voice packs, TTS backend, etc. via: voxlert config",
+        "info",
+      );
+    },
+  });
+
+  // ------------------------------------------------------------------
+  // voxlert_speak tool — let the LLM speak through Voxlert
+  // ------------------------------------------------------------------
+  pi.registerTool({
+    name: "voxlert_speak",
+    label: "Voxlert Speak",
+    description:
+      "Speak a phrase aloud through Voxlert using the user's configured voice pack and TTS backend. " +
+      "Use this when the user asks you to say something out loud, announce something, or test voice notifications.",
+    parameters: Type.Object({
+      phrase: Type.String({ description: "The phrase to speak aloud (2-12 words work best)" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (!available) {
+        throw new Error(
+          "Voxlert CLI not installed. Install with: npm install -g @settinghead/voxlert && voxlert setup",
+        );
+      }
+
+      fireVoxlert("Stop", ctx.cwd, {
+        phrase_override: params.phrase,
+      });
+
+      return {
+        content: [{ type: "text", text: `Speaking: "${params.phrase}"` }],
+        details: { phrase: params.phrase },
+      };
+    },
+  });
+}

package/src/cli.js

@@ -53,6 +53,14 @@ async function maybeRunSetup(command) {
 
 (async () => {
   const args = process.argv.slice(2);
+
+  // --onboard flag: run setup wizard directly (supports `npx voxlert --onboard`)
+  if (args.includes("--onboard")) {
+    const { runSetup } = await import("./setup.js");
+    await runSetup();
+    return;
+  }
+
   const requested = args[0] || "help";
   const command = resolveCommand(requested);
 

package/src/commands/help.js

@@ -4,7 +4,7 @@ export function formatHelp(commands, pkg) {
     .map((command) => command.help.join("\n"));
 
   return [
-    `voxlert v${pkg.version} — Game character voice notifications for Claude Code, Cursor, Codex, and OpenClaw`,
+    `voxlert v${pkg.version} — Game character voice notifications for Claude Code, Cursor, Codex, pi, and OpenClaw`,
     "",
     "Usage:",
     ...sections,

package/src/commands/uninstall.js

@@ -3,10 +3,11 @@ import confirm from "@inquirer/confirm";
 import { unregisterHooks, removeSkill } from "../hooks.js";
 import { unregisterCursorHooks } from "../cursor-hooks.js";
 import { unregisterCodexNotify } from "../codex-config.js";
+import { removePiExtension } from "../pi-hooks.js";
 import { STATE_DIR } from "../paths.js";
 
 async function runUninstall() {
-  console.log("Removing Voxlert hooks and skill...\n");
+  console.log("Removing Voxlert hooks, extensions, and skill...\n");
 
   const claudeRemoved = unregisterHooks();
   if (claudeRemoved > 0) {
@@ -23,13 +24,18 @@ async function runUninstall() {
     console.log("  Removed notify from ~/.codex/config.toml");
   }
 
+  const piRemoved = removePiExtension();
+  if (piRemoved) {
+    console.log("  Removed Voxlert extension from ~/.pi/agent/extensions/");
+  }
+
   const skillRemoved = removeSkill();
   if (skillRemoved) {
     console.log("  Removed voxlert-config skill");
   }
 
-  if (claudeRemoved === 0 && cursorRemoved === 0 && !codexRemoved && !skillRemoved) {
-    console.log("  No Voxlert hooks or skill were found.");
+  if (claudeRemoved === 0 && cursorRemoved === 0 && !codexRemoved && !piRemoved && !skillRemoved) {
+    console.log("  No Voxlert hooks, extensions, or skill were found.");
   }
 
   if (existsSync(STATE_DIR)) {
@@ -43,14 +49,14 @@ async function runUninstall() {
     }
   }
 
-  console.log("\nUninstall complete. You can still run 'voxlert' if installed via npm; run 'npm uninstall -g @settinghead/voxlert' to remove the CLI.");
+  console.log("\nUninstall complete. You can still run 'voxlert' if installed via npm; run 'npm uninstall -g @settinghead/voxlert' to remove the CLI.\nFor pi, you can also run: pi remove npm:@settinghead/pi-voxlert");
 }
 
 export const uninstallCommand = {
   name: "uninstall",
   aliases: [],
   help: [
-    "  voxlert uninstall           Remove hooks from Claude Code, Cursor, and Codex, optionally config/cache",
+    "  voxlert uninstall           Remove hooks from Claude Code, Cursor, Codex, and pi, optionally config/cache",
   ],
   skipSetupWizard: true,
   skipUpgradeCheck: false,

package/src/pi-hooks.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const PI_EXTENSIONS_DIR = join(homedir(), ".pi", "agent", "extensions");
+const PI_EXTENSION_FILE = join(PI_EXTENSIONS_DIR, "voxlert.ts");
+
+/**
+ * The extension source is bundled at ../pi-package/extensions/voxlert.ts
+ * relative to this file (cli/src/).
+ */
+const EXTENSION_SRC = join(__dirname, "..", "pi-package", "extensions", "voxlert.ts");
+
+/**
+ * Check if the Voxlert extension is installed in pi's extensions directory.
+ */
+export function hasPiExtension() {
+  return existsSync(PI_EXTENSION_FILE);
+}
+
+/**
+ * Install the Voxlert extension to ~/.pi/agent/extensions/voxlert.ts.
+ * Copies the bundled extension source file.
+ * @returns {boolean} true if installed successfully
+ */
+export function installPiExtension() {
+  if (!existsSync(EXTENSION_SRC)) return false;
+  mkdirSync(PI_EXTENSIONS_DIR, { recursive: true });
+  const content = readFileSync(EXTENSION_SRC, "utf-8");
+  writeFileSync(PI_EXTENSION_FILE, content);
+  return true;
+}
+
+/**
+ * Remove the Voxlert extension from ~/.pi/agent/extensions/.
+ * @returns {boolean} true if a file was removed
+ */
+export function removePiExtension() {
+  if (!existsSync(PI_EXTENSION_FILE)) return false;
+  rmSync(PI_EXTENSION_FILE);
+  return true;
+}

package/src/setup.js

@@ -21,6 +21,7 @@ import { LLM_PROVIDERS, getProvider } from "./providers.js";
 import { registerHooks, installSkill, unregisterHooks, hasVoxlertHooks, hasInstalledSkill, removeSkill } from "./hooks.js";
 import { registerCursorHooks, unregisterCursorHooks, hasCursorHooks } from "./cursor-hooks.js";
 import { registerCodexNotify, getCodexConfigPath, unregisterCodexNotify, hasCodexNotify } from "./codex-config.js";
+import { installPiExtension, removePiExtension, hasPiExtension } from "./pi-hooks.js";
 import { printSetupHeader, printStep, printStatus, printSuccess, printWarning, highlight } from "./setup-ui.js";
 import {
   probeTtsBackend,
@@ -238,6 +239,7 @@ export async function runSetup({ nonInteractive = false } = {}) {
   if (hasVoxlertHooks() || hasInstalledSkill()) installedPlatforms.push("Claude");
   if (hasCursorHooks()) installedPlatforms.push("Cursor");
   if (hasCodexNotify()) installedPlatforms.push("Codex");
+  if (hasPiExtension()) installedPlatforms.push("pi");
   await printSetupHeader(config, installedPlatforms);
 
   // --- Step 1: LLM Provider ---
@@ -502,6 +504,12 @@ export async function runSetup({ nonInteractive = false } = {}) {
       description: "Install/update notify in ~/.codex/config.toml",
       checked: hasCodexNotify(),
     },
+    {
+      name: "pi",
+      value: "pi",
+      description: "Install extension to ~/.pi/agent/extensions/",
+      checked: hasPiExtension(),
+    },
   ];
 
   const selectedPlatforms = await checkbox({
@@ -554,6 +562,20 @@ export async function runSetup({ nonInteractive = false } = {}) {
     }
   }
 
+  if (selectedPlatforms.includes("pi")) {
+    if (installPiExtension()) {
+      printSuccess("Installed Voxlert extension to ~/.pi/agent/extensions/voxlert.ts");
+      printStatus("Next", "Run /reload in pi or start a new session to activate.");
+    } else {
+      printWarning("Could not install pi extension (source file not found).");
+    }
+  } else {
+    const piRemoved = removePiExtension();
+    if (piRemoved) {
+      printWarning("Removed Voxlert extension from ~/.pi/agent/extensions/");
+    }
+  }
+
   if (selectedPlatforms.length === 0) {
     printWarning("No platforms selected. Run 'voxlert setup' again to install hooks later.");
   }
@@ -681,6 +703,9 @@ function printSetupSummary(config, chosenProvider, selectedPlatforms) {
   if (selectedPlatforms.includes("codex")) {
     printStatus("Codex", "Start a new Codex session to pick up the notify config.");
   }
+  if (selectedPlatforms.includes("pi")) {
+    printStatus("pi", "Run /reload in pi or start a new session.");
+  }
   printStatus("Reconfigure", "voxlert setup");
   console.log("");
 }

package/src/voxlert.js

@@ -93,6 +93,57 @@ export async function processHookEvent(eventData) {
   const pack = loadPack(config);
   const projectName = cwd ? basename(cwd) : "";
 
+  // Allow callers to bypass LLM generation entirely with a pre-built phrase
+  if (eventData.phrase_override && typeof eventData.phrase_override === "string") {
+    const overridePhrase = eventData.phrase_override.trim();
+    if (overridePhrase) {
+      debugLog("processHookEvent using phrase_override", { source, phrase: overridePhrase.slice(0, 120) });
+
+      // Prepend prefix
+      const prefixTemplate = config.prefix !== undefined ? config.prefix : "${dirname}";
+      let resolvedPrefix = "";
+      if (prefixTemplate !== "") {
+        resolvedPrefix = prefixTemplate.replace(/\$\{dirname\}/g, projectName);
+        if (resolvedPrefix) {
+          const finalPhrase = `${resolvedPrefix}; ${overridePhrase}`;
+          const packId = config.active_pack || "sc1-kerrigan-infested";
+          appendLog(
+            `[${new Date().toISOString()}] source=${source} event=${eventName} category=${category} phrase=${finalPhrase.replace(/\s+/g, " ").slice(0, 120)}`,
+            config,
+          );
+          showOverlay(finalPhrase, {
+            category,
+            packName: pack.name,
+            packId: pack.id || packId,
+            prefix: resolvedPrefix,
+            config,
+            overlayColors: pack.overlay_colors,
+          });
+          await speakPhrase(finalPhrase, config, pack);
+          debugLog("processHookEvent done (phrase_override)", { source });
+          return;
+        }
+      }
+
+      const packId = config.active_pack || "sc1-kerrigan-infested";
+      appendLog(
+        `[${new Date().toISOString()}] source=${source} event=${eventName} category=${category} phrase=${overridePhrase.replace(/\s+/g, " ").slice(0, 120)}`,
+        config,
+      );
+      showOverlay(overridePhrase, {
+        category,
+        packName: pack.name,
+        packId: pack.id || packId,
+        prefix: "",
+        config,
+        overlayColors: pack.overlay_colors,
+      });
+      await speakPhrase(overridePhrase, config, pack);
+      debugLog("processHookEvent done (phrase_override)", { source });
+      return;
+    }
+  }
+
   // For contextual events, try LLM phrase generation
   let phrase = null;
   let fallbackReason = null;