@settinghead/voxlert 0.3.9 → 0.3.11

package/README.md

@@ -8,11 +8,14 @@
   <a href="https://github.com/settinghead/voxlert/actions/workflows/cli-integration.yml">
     <img src="https://github.com/settinghead/voxlert/actions/workflows/cli-integration.yml/badge.svg" alt="CLI Integration" />
   </a>
+  <a href="https://fazier.com/launches/voxlert">
+    <img src="https://fazier.com/api/v1//public/badges/launch_badges.svg?badge_type=launched&theme=light" alt="Launched on Fazier" />
+  </a>
 </p>
 
 # 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 +27,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)
@@ -71,7 +74,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).
 
@@ -113,12 +116,6 @@ Run tests locally with:
 npm test
 ```
 
-For release-impacting changes, add a changeset before opening a PR:
-
-```bash
-npm run changeset
-```
-
 ## Supported Voices
 
 The `sc1-adjutant` preview below uses the animated in-game portrait GIF from `assets/sc1-adjutant.gif`.
@@ -188,6 +185,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.
@@ -218,6 +236,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>]
@@ -233,7 +252,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.
@@ -278,7 +297,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 |
 |---|---|---|---|
@@ -321,9 +340,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`.
 
@@ -353,7 +372,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
 ```
@@ -371,7 +390,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.9",
-  "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.11",
+  "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",
@@ -27,14 +28,10 @@
   "scripts": {
     "start": "node src/voxlert.js",
     "postinstall": "node src/postinstall.js",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "release": "changeset publish",
     "test": "node --test ./test/*.test.js"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "license": "MIT",
   "dependencies": {
@@ -43,9 +40,5 @@
     "@inquirer/input": "^4.1.0",
     "@inquirer/select": "^5.1.0",
     "node-notifier": "^10.0.1"
-  },
-  "devDependencies": {
-    "@changesets/changelog-github": "^0.6.0",
-    "@changesets/cli": "^2.30.0"
   }
 }

package/pi-package/extensions/voxlert.ts

@@ -0,0 +1,309 @@
+/**
+ * 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();
+
+  // ------------------------------------------------------------------
+  // Guided setup: install CLI + run setup --yes
+  // ------------------------------------------------------------------
+  async function runGuidedSetup(ctx: any): Promise<boolean> {
+    // Step 1: Install the CLI
+    ctx.ui.notify("Installing @settinghead/voxlert...", "info");
+    const install = await pi.exec("npm", ["install", "-g", "@settinghead/voxlert"], {
+      timeout: 120_000,
+    });
+    if (install.code !== 0) {
+      ctx.ui.notify(
+        `Install failed (exit ${install.code}):\n${install.stderr.slice(0, 300)}`,
+        "error",
+      );
+      return false;
+    }
+
+    // Step 2: Run non-interactive setup (downloads voice packs, detects TTS)
+    ctx.ui.notify("Running voxlert setup (downloading voice packs, detecting TTS)...", "info");
+    const setup = await pi.exec("voxlert", ["setup", "--yes"], { timeout: 120_000 });
+    if (setup.code !== 0) {
+      ctx.ui.notify(
+        `Setup failed (exit ${setup.code}):\n${setup.stderr.slice(0, 300)}`,
+        "error",
+      );
+      return false;
+    }
+
+    // Verify it worked
+    available = isVoxlertAvailable();
+    if (available) {
+      ctx.ui.notify(
+        "Voxlert installed and configured!\n\n" +
+          "Voice notifications will now play when the agent finishes a task.\n" +
+          "Run /voxlert test to hear it, or 'voxlert setup' in a terminal for full interactive config.",
+        "info",
+      );
+      ctx.ui.setStatus("voxlert", "🔊 Voxlert");
+      return true;
+    } else {
+      ctx.ui.notify("Install succeeded but voxlert binary not found in PATH.", "error");
+      return false;
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Session start: verify Voxlert is installed, offer setup if not
+  // ------------------------------------------------------------------
+  pi.on("session_start", async (_event, ctx) => {
+    available = isVoxlertAvailable();
+    if (!available) {
+      if (!ctx.hasUI) {
+        // Non-interactive mode (print mode, JSON mode) — just warn
+        return;
+      }
+
+      const install = await ctx.ui.confirm(
+        "Voxlert Setup",
+        "Voxlert CLI not found. Install it now?\n\n" +
+          "This will:\n" +
+          "  • npm install -g @settinghead/voxlert\n" +
+          "  • Download default voice packs (SHODAN, Adjutant, etc.)\n" +
+          "  • Auto-detect your TTS backend\n\n" +
+          "You can run full interactive setup later with: voxlert setup",
+      );
+
+      if (install) {
+        await runGuidedSetup(ctx);
+      } else {
+        ctx.ui.notify(
+          "Skipped. Run /voxlert setup anytime, or manually:\n" +
+            "  npm install -g @settinghead/voxlert && voxlert setup",
+          "info",
+        );
+      }
+    } 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 === "setup") {
+        if (available) {
+          const redo = await ctx.ui.confirm(
+            "Voxlert Setup",
+            "Voxlert is already installed. Re-run setup with defaults?",
+          );
+          if (!redo) return;
+        }
+        await runGuidedSetup(ctx);
+        return;
+      }
+
+      if (sub === "test") {
+        if (!available) {
+          ctx.ui.notify("Voxlert CLI not installed. Run /voxlert setup first.", "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 /voxlert setup to install.",
+          available ? "info" : "warning",
+        );
+        return;
+      }
+
+      // Default: show help
+      ctx.ui.notify(
+        "Usage: /voxlert [setup|test|status]\n" +
+          "  setup  — install Voxlert CLI and configure with defaults\n" +
+          "  test   — fire a test voice notification\n" +
+          "  status — check if Voxlert CLI is available\n" +
+          "\nFor full interactive config, run in terminal: voxlert setup",
+        "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/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/pack-helpers.js

@@ -5,6 +5,7 @@ import { showOverlay } from "../overlay.js";
 import { listPacks, loadPack } from "../packs.js";
 import { generatePhrase } from "../llm.js";
 import { speakPhrase } from "../audio.js";
+import { resolvePrefix, DEFAULT_PREFIX } from "../prefix.js";
 
 export async function testPipeline(text, pack) {
   if (!text) {
@@ -33,12 +34,19 @@ export async function testPipeline(text, pack) {
     phrase = text;
   }
 
+  // Resolve prefix from config, same as the hook path
+  const prefixTemplate = config.prefix !== undefined ? config.prefix : DEFAULT_PREFIX;
+  const resolvedPrefix = resolvePrefix(prefixTemplate, process.cwd());
+  if (resolvedPrefix) {
+    phrase = `${resolvedPrefix}; ${phrase}`;
+  }
+
   console.log("Sending to TTS...");
   showOverlay(phrase, {
     category: "notification",
     packName: activePack.name,
     packId: activePack.id || (config.active_pack || "sc1-kerrigan-infested"),
-    prefix: "Test",
+    prefix: resolvedPrefix,
     config,
     overlayColors: activePack.overlay_colors,
   });

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/prefix.js

@@ -0,0 +1,266 @@
+/**
+ * Prefix resolver — composable template variables for announcement prefixes.
+ *
+ * Template syntax:
+ *   ${dirname}          — basename of cwd
+ *   ${project}          — project name from manifest files (package.json, pyproject.toml, etc.)
+ *   ${project|dirname}  — pipe means "try left, fall back to right"
+ *
+ * Literal text is preserved as-is: "Project ${project|dirname}" → "Project my-app"
+ * Unknown variables and all-null chains resolve to empty string.
+ */
+
+import { basename, join } from "path";
+import { existsSync, readFileSync, readdirSync } from "fs";
+
+/** Default prefix template — project name with dirname fallback. */
+export const DEFAULT_PREFIX = "${project|dirname}";
+
+// ---------------------------------------------------------------------------
+// Resolvers — each is (cwd: string) => string | null
+// ---------------------------------------------------------------------------
+
+const RESOLVERS = {
+  dirname: (cwd) => (cwd ? basename(cwd) : null),
+  project: readProjectName,
+};
+
+// ---------------------------------------------------------------------------
+// Project manifest readers, tried in priority order.
+// Each entry: [filename, extractorFn(contents) => string|null]
+// ---------------------------------------------------------------------------
+
+/** @type {Array<[string, (content: string) => string|null]>} */
+const MANIFEST_READERS = [
+  ["package.json", extractPackageName],
+  ["pyproject.toml", extractPyprojectName],
+  ["Cargo.toml", extractTomlSectionField("package", "name")],
+  ["setup.cfg", extractIniSectionField("metadata", "name")],
+  ["go.mod", extractGoModule],
+  ["composer.json", extractComposerName],
+  ["pubspec.yaml", extractYamlScalar("name")],
+  // gemspec handled separately — requires glob
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a prefix template string against the given working directory.
+ *
+ * @param {string} template - e.g. "${project|dirname}" or "my-app"
+ * @param {string} cwd - Absolute path to the project directory
+ * @returns {string} Resolved prefix (may be empty)
+ */
+export function resolvePrefix(template, cwd) {
+  if (!template) return "";
+  return template.replace(/\$\{([^}]+)\}/g, (_match, expr) => {
+    const candidates = expr.split("|");
+    for (const name of candidates) {
+      const resolver = RESOLVERS[name.trim()];
+      if (!resolver) continue;
+      const value = resolver(cwd);
+      if (value) return value;
+    }
+    return "";
+  });
+}
+
+// ---------------------------------------------------------------------------
+// readProjectName — walks manifests in priority order
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the project name from the first recognized manifest file in cwd.
+ * Returns null if no manifest is found or none yields a name.
+ *
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function readProjectName(cwd) {
+  if (!cwd) return null;
+
+  // Fixed-name manifests
+  for (const [filename, extractor] of MANIFEST_READERS) {
+    const filepath = join(cwd, filename);
+    const content = readFileSafe(filepath);
+    if (content === null) continue;
+    const name = extractor(content);
+    if (name) return name;
+  }
+
+  // *.gemspec — need a directory listing
+  try {
+    const entries = readdirSync(cwd);
+    const gemspec = entries.find((e) => e.endsWith(".gemspec"));
+    if (gemspec) {
+      const content = readFileSafe(join(cwd, gemspec));
+      if (content) {
+        const name = extractGemspecName(content);
+        if (name) return name;
+      }
+    }
+  } catch {
+    // directory unreadable — skip
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Extractors
+// ---------------------------------------------------------------------------
+
+/** JSON field extractor factory. */
+function extractJsonField(field) {
+  return (content) => {
+    try {
+      const obj = JSON.parse(content);
+      const val = obj?.[field];
+      return typeof val === "string" && val.trim() ? val.trim() : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/** package.json: strip npm scope (@scope/name → name). */
+function extractPackageName(content) {
+  const name = extractJsonField("name")(content);
+  if (!name) return null;
+  // Strip @scope/ prefix for TTS-friendly output
+  const slashIdx = name.indexOf("/");
+  return slashIdx >= 0 && name.startsWith("@") ? name.slice(slashIdx + 1) : name;
+}
+
+/** composer.json: name is "vendor/package" — return the package segment. */
+function extractComposerName(content) {
+  try {
+    const obj = JSON.parse(content);
+    const val = obj?.name;
+    if (typeof val !== "string" || !val.trim()) return null;
+    const parts = val.split("/");
+    return parts[parts.length - 1].trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * pyproject.toml: check [project].name then [tool.poetry].name.
+ * Lightweight line-based extraction — no full TOML parser.
+ */
+function extractPyprojectName(content) {
+  return (
+    extractTomlSectionField("project", "name")(content) ||
+    extractTomlNestedField("tool.poetry", "name")(content)
+  );
+}
+
+/**
+ * Factory: extract `key = "value"` under a [section] header in TOML.
+ * Handles both `key = "value"` and `key = 'value'`.
+ */
+function extractTomlSectionField(section, key) {
+  // Match [section] exactly (no dots, no sub-tables)
+  const headerRe = new RegExp(`^\\[${escapeRegex(section)}\\]\\s*$`);
+  const fieldRe = new RegExp(`^${escapeRegex(key)}\\s*=\\s*["'](.+?)["']`);
+  return (content) => extractFromSections(content, headerRe, fieldRe);
+}
+
+/**
+ * Factory: extract `key = "value"` under a [dotted.section] header in TOML.
+ * e.g. [tool.poetry] → key = "value"
+ */
+function extractTomlNestedField(dottedSection, key) {
+  const headerRe = new RegExp(`^\\[${escapeRegex(dottedSection)}\\]\\s*$`);
+  const fieldRe = new RegExp(`^${escapeRegex(key)}\\s*=\\s*["'](.+?)["']`);
+  return (content) => extractFromSections(content, headerRe, fieldRe);
+}
+
+/** Shared: scan lines for a section header, then find a field before the next header. */
+function extractFromSections(content, headerRe, fieldRe) {
+  const lines = content.split("\n");
+  let inSection = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("[")) {
+      inSection = headerRe.test(trimmed);
+      continue;
+    }
+    if (inSection) {
+      const m = fieldRe.exec(trimmed);
+      if (m) return m[1].trim() || null;
+    }
+  }
+  return null;
+}
+
+/** setup.cfg: INI-style [metadata] section, name = value (no quotes). */
+function extractIniSectionField(section, key) {
+  const headerRe = new RegExp(`^\\[${escapeRegex(section)}\\]\\s*$`, "i");
+  const fieldRe = new RegExp(`^${escapeRegex(key)}\\s*=\\s*(.+)`, "i");
+  return (content) => {
+    const lines = content.split("\n");
+    let inSection = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("[")) {
+        inSection = headerRe.test(trimmed);
+        continue;
+      }
+      if (inSection) {
+        const m = fieldRe.exec(trimmed);
+        if (m) return m[1].trim() || null;
+      }
+    }
+    return null;
+  };
+}
+
+/** go.mod: `module github.com/user/repo` → "repo" */
+function extractGoModule(content) {
+  const m = /^module\s+(\S+)/m.exec(content);
+  if (!m) return null;
+  const parts = m[1].split("/");
+  return parts[parts.length - 1].trim() || null;
+}
+
+/** *.gemspec: first `spec.name = "value"` or `.name = "value"` */
+function extractGemspecName(content) {
+  const m = /\.name\s*=\s*["'](.+?)["']/.exec(content);
+  return m ? m[1].trim() || null : null;
+}
+
+/** YAML top-level scalar: `name: value` */
+function extractYamlScalar(key) {
+  const re = new RegExp(`^${escapeRegex(key)}:\\s*(.+)`, "m");
+  return (content) => {
+    const m = re.exec(content);
+    if (!m) return null;
+    // Strip surrounding quotes if present
+    let val = m[1].trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    return val || null;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readFileSafe(filepath) {
+  try {
+    if (!existsSync(filepath)) return null;
+    return readFileSync(filepath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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/upgrade-check.js

@@ -91,13 +91,9 @@ const ansi = {
   grey: "\x1b[90m",
 };
 
-function stripAnsi(str) {
-  return str.replace(/\x1b\[[0-9;]*m/g, "");
-}
-
 /**
- * Print upgrade notification to stdout, styled like a terminal box:
- * dark background hint, cyan "Update available!", version range, command, release notes link.
+ * Print upgrade notification to stdout, styled with horizontal separator lines:
+ * yellow lines above and below, bold header, version info, install command, changelog link.
  * Only uses colors when stdout is TTY.
  */
 export function printUpgradeNotification(info, options = {}) {
@@ -110,28 +106,16 @@ export function printUpgradeNotification(info, options = {}) {
     releaseNotesUrl ||
     `https://github.com/settinghead/voxlert/releases/latest`;
 
-  const line1 = `${c.yellow}✨${c.reset} ${c.cyan}Update available!${c.reset} ${info.current} -> ${info.latest}`;
-  const line2 = `Run ${installCmd} to update.`;
-  const line3 = "See full release notes:";
-  const line4 = `${c.cyan}${url}${c.reset}`;
-
-  const padding = 2;
-  const maxLen = Math.max(
-    stripAnsi(line1).length,
-    line2.length,
-    line3.length,
-    url.length
-  );
-  const width = maxLen + padding * 2;
-  const border = "─".repeat(width);
-  const pad = (s) => " ".repeat(Math.max(0, width - 2 - stripAnsi(s).length));
+  const rule = `${c.yellow}${"─".repeat(60)}${c.reset}`;
 
   console.log("");
-  console.log(`${c.grey}┌${border}┐${c.reset}`);
-  console.log(`${c.grey}│${c.reset}${" ".repeat(padding)}${line1}${pad(line1)}${c.grey}│${c.reset}`);
-  console.log(`${c.grey}│${c.reset}${" ".repeat(padding)}${line2}${pad(line2)}${c.grey}│${c.reset}`);
-  console.log(`${c.grey}│${c.reset}${" ".repeat(padding)}${line3}${pad(line3)}${c.grey}│${c.reset}`);
-  console.log(`${c.grey}│${c.reset}${" ".repeat(padding)}${line4}${pad(line4)}${c.grey}│${c.reset}`);
-  console.log(`${c.grey}└${border}┘${c.reset}`);
+  console.log(rule);
+  console.log("");
+  console.log(`  ${c.bold}${c.yellow}Update Available${c.reset}`);
+  console.log(`  New version ${c.bold}${info.latest}${c.reset} is available. Run: ${c.cyan}${installCmd}${c.reset}`);
+  console.log(`  Changelog:`);
+  console.log(`  ${c.cyan}${url}${c.reset}`);
+  console.log("");
+  console.log(rule);
   console.log("");
 }

package/src/voxlert.js

@@ -6,7 +6,7 @@
  * speaks them through a local Chatterbox TTS server.
  */
 
-import { basename } from "path";
+import { resolvePrefix, DEFAULT_PREFIX } from "./prefix.js";
 import { appendFileSync, mkdirSync } from "fs";
 import { loadConfig, EVENT_MAP, CONTEXTUAL_EVENTS, FALLBACK_PHRASES } from "./config.js";
 import { extractContext, generatePhrase } from "./llm.js";
@@ -58,7 +58,7 @@ export async function processHookEvent(eventData) {
     llm_backend: config.llm_backend || "",
     tts_backend: config.tts_backend || "",
     overlay: config.overlay === true,
-    prefix: config.prefix !== undefined ? config.prefix : "${dirname}",
+    prefix: config.prefix !== undefined ? config.prefix : DEFAULT_PREFIX,
     task_complete_enabled: config.categories?.["task.complete"] !== false,
     task_error_enabled: config.categories?.["task.error"] !== false,
   });
@@ -91,7 +91,53 @@ export async function processHookEvent(eventData) {
   debugLog("processHookEvent processing", { source, eventName, category });
   // Load active voice pack
   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) });
+
+      // Resolve prefix
+      const prefixTemplate = config.prefix !== undefined ? config.prefix : DEFAULT_PREFIX;
+      const resolvedPrefix = resolvePrefix(prefixTemplate, cwd);
+      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;
@@ -145,14 +191,11 @@ export async function processHookEvent(eventData) {
     phrase = phrases[Math.floor(Math.random() * phrases.length)];
   }
 
-  // Prepend prefix (supports ${dirname} template variable)
-  const prefixTemplate = config.prefix !== undefined ? config.prefix : "${dirname}";
-  let resolvedPrefix = "";
-  if (prefixTemplate !== "") {
-    resolvedPrefix = prefixTemplate.replace(/\$\{dirname\}/g, projectName);
-    if (resolvedPrefix) {
-      phrase = `${resolvedPrefix}; ${phrase}`;
-    }
+  // Resolve prefix (supports ${project|dirname} template variables)
+  const prefixTemplate = config.prefix !== undefined ? config.prefix : DEFAULT_PREFIX;
+  const resolvedPrefix = resolvePrefix(prefixTemplate, cwd);
+  if (resolvedPrefix) {
+    phrase = `${resolvedPrefix}; ${phrase}`;
   }
 
   const packId = config.active_pack || "sc1-kerrigan-infested";