@astrofoundry/pi-astro 0.8.0 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # @astrofoundry/pi-astro
 
-Personal customizations for the [pi coding agent](https://github.com/badlogic/pi-mono) — registers an `astro_agent` tool, a `grimoire` docs tool, a `claude-globals` rules-injection extension, 8 curated subagents, 3 skills, and an `astro` theme.
+Personal customizations for the [pi coding agent](https://github.com/badlogic/pi-mono) — registers an `astro_agent` tool, a `grimoire` docs tool, a `claude-globals` rules-injection extension, a `caveman` compressed-output toggle, 8 curated subagents, 4 skills, and an `astro` theme.
 
 ## Full setup
 
@@ -62,16 +62,17 @@ pi                # launch; confirm [Extensions] lists astro-agents, claude-glob
 - `multi-edit` — registers the enhanced `edit` tool
 - `gemini-image` — registers `gemini_image` tool (requires a Gemini API key; prompts and saves on first use)
 - `security-guard` — blocks/prompts destructive bash commands and sensitive file access; configure at `~/.pi/agent/security-guard.json` (example written on first run); `/security-guard status|reload|test`
-- `notify-on-stop` — runs a shell command when the agent finishes a turn (sound, voice, desktop notification). macOS default: plays the Glass system sound **and** speaks "Agent done" via `say` using the **`Samantha (Enhanced)`** voice. Linux default: `notify-send "pi" "Agent done"`. Override the voice with `PI_STOP_NOTIFY_VOICE=<voice-name>` (macOS only; e.g. `Alex`, `Karen`, `Daniel (Enhanced)`). Replace the full command with `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Disable everything with `PI_STOP_NOTIFY_OFF=1`. `/notify status|test|off`.
+- `notify-on-stop` — runs a shell command when the agent finishes a turn (sound, voice, desktop notification). **Default: off.** Enable with `/notify on` (state persists in `~/.pi/agent/notify-on-stop.json`); disable with `/notify off`. macOS default command: plays the Glass system sound **and** speaks "Agent done" via `say` using the **`Samantha (Enhanced)`** voice. Linux default: `notify-send "pi" "Agent done"`. Override the voice with `PI_STOP_NOTIFY_VOICE=<voice-name>` (macOS only; e.g. `Alex`, `Karen`, `Daniel (Enhanced)`). Replace the full command with `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Hard-kill (overrides `/notify on`) with `PI_STOP_NOTIFY_OFF=1`. Commands: `/notify [on|off|status|test]`. See [extensions/notify-on-stop/README.md](extensions/notify-on-stop/README.md) for full details.
   - **macOS voice install (required once for the default):** open **System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…**, expand **English**, check **Samantha (Enhanced)**, click **Done** to download (~500 MB – 1 GB). Verify with `say -v "Samantha (Enhanced)" hi`. If the voice is missing, `say` errors silently and you'll only hear the Glass sound.
 - `vscode-image` — only active inside VS Code's integrated terminal (`TERM_PROGRAM=vscode`). Switches pi-tui's image output to the **Kitty graphics protocol** so images returned by tools like `gemini_image` render as real pixels instead of the `[Image: …]` text fallback. **Requires enabling `Terminal › Integrated: Enable Images` in VS Code settings** (off by default); restart the integrated terminal after flipping it. Disable with `PI_VSCODE_IMAGE_OFF=1`. `/vscode-image` prints current status.
 - `claude-globals` — auto-injects `~/.claude/CLAUDE.md` into every pi session's system prompt
+- `caveman` — `/caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off|status]` toggles a persistent compressed-output mode. No argument toggles between off and the default level (`full`). Active level is shown as a footer badge and survives `/reload`. The skill body at `skills/caveman/SKILL.md` is also available as a one-shot via `/skill:caveman`.
 
 **Bundled subagents** (callable via `astro_agent`):
 - `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
 
 **Skills** (loadable via `/skill:<name>`):
-- `playwright-cli`, `postman-cli`, `raycast-script-creator`
+- `playwright-cli`, `postman-cli`, `raycast-script-creator`, `caveman`
 
 **Theme:**
 - `astro` — dark, gold accent, GitHub-dark-inspired

package/extensions/caveman/README.md

@@ -0,0 +1,80 @@
+# caveman
+
+Persistent compressed-output mode for the [pi coding agent](https://github.com/badlogic/pi-mono). Strips fillers, hedging, and connectives from assistant prose to cut output tokens by ~70-75% while preserving every technical fact. Code, error strings, command lines, paths, identifiers, and version numbers stay untouched.
+
+Ships as part of [`@astrofoundry/pi-astro`](../../README.md). No extra install.
+
+## Quick start
+
+In any pi session:
+
+```
+/caveman
+```
+
+Caveman is now on at level `full`. Type the same command again to switch it off. The active level is shown as a footer badge and survives `/reload`.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/caveman` | Toggle: off → `full`, on → off |
+| `/caveman lite` | Activate at level `lite` |
+| `/caveman full` | Activate at level `full` (default) |
+| `/caveman ultra` | Activate at level `ultra` |
+| `/caveman wenyan-lite` | Activate at level `wenyan-lite` |
+| `/caveman wenyan-full` | Activate at level `wenyan-full` |
+| `/caveman wenyan-ultra` | Activate at level `wenyan-ultra` |
+| `/caveman off` | Deactivate |
+| `/caveman status` | Print the current level |
+
+Argument autocomplete is wired — type `/caveman ` and tab-cycle the levels.
+
+You can also deactivate by saying "stop caveman" or "normal mode" in plain prose.
+
+## Levels
+
+Pick the trade-off between compression and readability:
+
+| Level | Behaviour | Example answer to "Why does this React component re-render?" |
+|---|---|---|
+| `lite` | Drop fillers and pleasantries only. Full sentences, articles kept. | "Your component re-renders because every render creates a new object reference for the prop. Wrap it in `useMemo`." |
+| `full` | Drop articles, fragments allowed. Default. | "New object ref each render. Inline obj prop = new ref = re-render. Wrap in `useMemo`." |
+| `ultra` | Aggressive abbreviation, arrows for causality. | "Inline obj prop → new ref → re-render. `useMemo`." |
+| `wenyan-lite` | Classical Chinese register, modern grammar. | "組件每次重繪皆生新對象參照。以 `useMemo` 包之。" |
+| `wenyan-full` | Full 文言文, classical particles. | "每繪生新參照，故重繪。以 `useMemo` 包之。" |
+| `wenyan-ultra` | Maximum classical compression. | "新參照→重繪。`useMemo` 包。" |
+
+## What stays normal
+
+Caveman never applies to:
+
+- **Source code, commit messages, PR descriptions, code review comments** — written in normal prose.
+- **Documentation files** (`.md`, `.mdx`, `.rst`) — caveman is for chat, not artifacts.
+- **Quoted log lines, stack traces, error messages** — reproduced exactly.
+
+Caveman also drops itself temporarily for safety:
+
+- Security warnings.
+- Confirmations for destructive or irreversible operations.
+- Multi-step procedures whose order matters.
+- When you ask a clarifying question or repeat yourself.
+
+The mode resumes immediately after the clarified step is complete.
+
+## One-shot vs persistent
+
+Two ways to use it:
+
+- **Persistent** — `/caveman` (or `/caveman <level>`). Stays on until you turn it off. Restored across `/reload` and session resume.
+- **One-shot** — `/skill:caveman`. Loads the skill content for a single response, then the next reply returns to normal. Useful when you want a single terse answer without committing to a mode.
+
+## State and persistence
+
+State lives in the pi session itself — no flag files in your home directory, no shell scripts, no symlink risk. Each session keeps its own toggle, so two pi sessions in different projects can run different modes.
+
+## Tips
+
+- If you find caveman too clipped while debugging tricky logic, switch to `lite` for the duration: `/caveman lite`.
+- Use `/caveman ultra` for short Q&A and debugging chains. Pair it with thinking levels and small models to keep latency low.
+- The wenyan levels are useful when you genuinely want the classical register — they are not a joke language and require both you and the model to be comfortable reading 文言文.

package/extensions/caveman/index.test.ts

@@ -0,0 +1,253 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type Handler = (event: unknown, ctx: unknown) => unknown | Promise<unknown>;
+
+interface CommandOptions {
+    description?: string;
+    handler: (args: string, ctx: unknown) => Promise<void> | void;
+    getArgumentCompletions?: (prefix: string) => unknown;
+}
+
+interface FakePi {
+    handlers: Record<string, Handler>;
+    commands: Map<string, CommandOptions>;
+    appendEntry: ReturnType<typeof vi.fn>;
+    on: (event: string, h: Handler) => void;
+    registerCommand: (name: string, opts: CommandOptions) => void;
+}
+
+function makePi(): FakePi {
+    const handlers: Record<string, Handler> = {};
+    const commands = new Map<string, CommandOptions>();
+    return {
+        handlers,
+        commands,
+        appendEntry: vi.fn(),
+        on(event, h) {
+            handlers[event] = h;
+        },
+        registerCommand(name, opts) {
+            commands.set(name, opts);
+        },
+    };
+}
+
+interface FakeCtx {
+    ui: {
+        notify: ReturnType<typeof vi.fn>;
+        setStatus: ReturnType<typeof vi.fn>;
+    };
+    sessionManager: { getEntries: () => unknown[] };
+}
+
+function makeCtx(entries: unknown[] = []): FakeCtx {
+    return {
+        ui: {
+            notify: vi.fn(),
+            setStatus: vi.fn(),
+        },
+        sessionManager: {
+            getEntries: () => entries,
+        },
+    };
+}
+
+describe("caveman extension", () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    async function load(): Promise<typeof import("./index.ts")> {
+        return await import("./index.ts");
+    }
+
+    async function install(): Promise<{ pi: FakePi; mod: Awaited<ReturnType<typeof load>> }> {
+        const mod = await load();
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        return { pi, mod };
+    }
+
+    it("registers /caveman command and the two lifecycle handlers", async () => {
+        const mod = await load();
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        expect(pi.commands.has("caveman")).toBe(true);
+        expect(pi.handlers.session_start).toBeDefined();
+        expect(pi.handlers.before_agent_start).toBeDefined();
+    });
+
+    it("/caveman with no args toggles on to default level (full)", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("", ctx);
+        expect(pi.appendEntry).toHaveBeenCalledWith("caveman-mode", { level: "full" });
+        expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", expect.stringContaining("full"));
+        expect(ctx.ui.notify).toHaveBeenCalledWith("caveman: full", "info");
+    });
+
+    it("/caveman called twice with no args toggles back off", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("", ctx);
+        await pi.commands.get("caveman")!.handler("", ctx);
+        expect(pi.appendEntry).toHaveBeenLastCalledWith("caveman-mode", { level: null });
+        expect(ctx.ui.setStatus).toHaveBeenLastCalledWith("caveman", undefined);
+        expect(ctx.ui.notify).toHaveBeenLastCalledWith("caveman: off", "info");
+    });
+
+    it.each(["lite", "full", "ultra", "wenyan-lite", "wenyan-full", "wenyan-ultra"])(
+        "/caveman %s activates that level",
+        async (level) => {
+            const { pi } = await install();
+            const ctx = makeCtx();
+            await pi.commands.get("caveman")!.handler(level, ctx);
+            expect(pi.appendEntry).toHaveBeenCalledWith("caveman-mode", { level });
+            expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", `🪨 caveman:${level}`);
+            expect(ctx.ui.notify).toHaveBeenCalledWith(`caveman: ${level}`, "info");
+        },
+    );
+
+    it("/caveman off clears status and persists null level", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("ultra", ctx);
+        await pi.commands.get("caveman")!.handler("off", ctx);
+        expect(pi.appendEntry).toHaveBeenLastCalledWith("caveman-mode", { level: null });
+        expect(ctx.ui.setStatus).toHaveBeenLastCalledWith("caveman", undefined);
+        expect(ctx.ui.notify).toHaveBeenLastCalledWith("caveman: off", "info");
+    });
+
+    it("/caveman status reports current level without changing state", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("ultra", ctx);
+        const persistedBefore = pi.appendEntry.mock.calls.length;
+        await pi.commands.get("caveman")!.handler("status", ctx);
+        expect(pi.appendEntry.mock.calls.length).toBe(persistedBefore);
+        expect(ctx.ui.notify).toHaveBeenLastCalledWith("caveman: ultra", "info");
+    });
+
+    it("/caveman status reports off when inactive", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("status", ctx);
+        expect(pi.appendEntry).not.toHaveBeenCalled();
+        expect(ctx.ui.notify).toHaveBeenCalledWith("caveman: off", "info");
+    });
+
+    it("/caveman with an unknown argument warns and does not change state", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("nonsense", ctx);
+        expect(pi.appendEntry).not.toHaveBeenCalled();
+        expect(ctx.ui.setStatus).not.toHaveBeenCalled();
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/unknown level/), "warning");
+    });
+
+    it("argument autocomplete returns wenyan completions for 'wen'", async () => {
+        const { pi } = await install();
+        const completions = pi.commands.get("caveman")!.getArgumentCompletions!("wen");
+        expect(completions).toEqual(
+            expect.arrayContaining([
+                { value: "wenyan-lite", label: "wenyan-lite" },
+                { value: "wenyan-full", label: "wenyan-full" },
+                { value: "wenyan-ultra", label: "wenyan-ultra" },
+            ]),
+        );
+    });
+
+    it("argument autocomplete returns null when no candidate matches", async () => {
+        const { pi } = await install();
+        const completions = pi.commands.get("caveman")!.getArgumentCompletions!("zzz");
+        expect(completions).toBeNull();
+    });
+
+    it("argument autocomplete includes off and status", async () => {
+        const { pi } = await install();
+        const completions = pi.commands.get("caveman")!.getArgumentCompletions!("");
+        expect(completions).toEqual(
+            expect.arrayContaining([
+                { value: "off", label: "off" },
+                { value: "status", label: "status" },
+            ]),
+        );
+    });
+
+    it("session_start restores activeLevel from the latest custom entry", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx([
+            { type: "custom", customType: "caveman-mode", data: { level: "full" } },
+            { type: "custom", customType: "caveman-mode", data: { level: "ultra" } },
+        ]);
+        await pi.handlers.session_start({}, ctx);
+        expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", "🪨 caveman:ultra");
+        const result = (await pi.handlers.before_agent_start(
+            { systemPrompt: "ORIG" },
+            makeCtx(),
+        )) as { systemPrompt: string };
+        expect(result.systemPrompt).toContain("CAVEMAN MODE ACTIVE — level: ultra");
+    });
+
+    it("session_start clears status when the latest entry persisted off", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx([
+            { type: "custom", customType: "caveman-mode", data: { level: "full" } },
+            { type: "custom", customType: "caveman-mode", data: { level: null } },
+        ]);
+        await pi.handlers.session_start({}, ctx);
+        expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", undefined);
+    });
+
+    it("session_start ignores unrelated custom entries and corrupt level data", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx([
+            { type: "custom", customType: "other-extension", data: { level: "full" } },
+            { type: "custom", customType: "caveman-mode", data: { level: "not-a-real-level" } },
+        ]);
+        await pi.handlers.session_start({}, ctx);
+        expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", undefined);
+    });
+
+    it("before_agent_start returns void when caveman is inactive", async () => {
+        const { pi } = await install();
+        const result = await pi.handlers.before_agent_start(
+            { systemPrompt: "ORIG" },
+            makeCtx(),
+        );
+        expect(result).toBeUndefined();
+    });
+
+    it("before_agent_start appends caveman ruleset filtered to the active level", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("ultra", ctx);
+        const result = (await pi.handlers.before_agent_start(
+            { systemPrompt: "ORIG" },
+            makeCtx(),
+        )) as { systemPrompt: string };
+        expect(result.systemPrompt.startsWith("ORIG\n\n")).toBe(true);
+        expect(result.systemPrompt).toContain("CAVEMAN MODE ACTIVE — level: ultra");
+        expect(result.systemPrompt).toContain("**ultra**");
+        expect(result.systemPrompt).not.toContain("**lite**");
+        expect(result.systemPrompt).not.toContain("**wenyan-lite**");
+        expect(result.systemPrompt).not.toContain("**wenyan-full**");
+    });
+
+    it("before_agent_start keeps only the active level's worked-example bullets", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("lite", ctx);
+        const result = (await pi.handlers.before_agent_start(
+            { systemPrompt: "ORIG" },
+            makeCtx(),
+        )) as { systemPrompt: string };
+        expect(result.systemPrompt).toMatch(/^- lite:/m);
+        expect(result.systemPrompt).not.toMatch(/^- ultra:/m);
+        expect(result.systemPrompt).not.toMatch(/^- wenyan-full:/m);
+    });
+});

package/extensions/caveman/index.ts

@@ -0,0 +1,169 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const LEVELS = [
+    "lite",
+    "full",
+    "ultra",
+    "wenyan-lite",
+    "wenyan-full",
+    "wenyan-ultra",
+] as const;
+
+type Level = (typeof LEVELS)[number];
+
+const DEFAULT_LEVEL: Level = "full";
+const ENTRY_TYPE = "caveman-mode";
+const STATUS_KEY = "caveman";
+
+const extensionDir = path.dirname(fileURLToPath(import.meta.url));
+const skillPath = path.resolve(
+    extensionDir,
+    "..",
+    "..",
+    "skills",
+    "caveman",
+    "SKILL.md",
+);
+
+interface PersistedState {
+    level: Level | null;
+}
+
+function isLevel(value: unknown): value is Level {
+    return typeof value === "string" && (LEVELS as readonly string[]).includes(value);
+}
+
+function parseLevel(arg: string): Level | null {
+    return isLevel(arg) ? arg : null;
+}
+
+function readSkillBody(): string {
+    const raw = fs.readFileSync(skillPath, "utf8");
+    return raw.replace(/^---[\s\S]*?---\s*/, "");
+}
+
+function filterForLevel(body: string, level: Level): string {
+    return body
+        .split("\n")
+        .reduce<string[]>((acc, line) => {
+            const tableRow = line.match(/^\|\s*\*\*([^*|]+?)\*\*\s*\|/);
+            if (tableRow) {
+                if (tableRow[1] === level) acc.push(line);
+                return acc;
+            }
+            const exampleBullet = line.match(/^- (\S+?):\s/);
+            if (exampleBullet) {
+                if (exampleBullet[1] === level) acc.push(line);
+                return acc;
+            }
+            acc.push(line);
+            return acc;
+        }, [])
+        .join("\n");
+}
+
+function buildInjection(level: Level, body: string): string {
+    return `CAVEMAN MODE ACTIVE — level: ${level}\n\n${filterForLevel(body, level)}`;
+}
+
+function statusText(level: Level): string {
+    return `🪨 caveman:${level}`;
+}
+
+const HELP =
+    "Usage: /caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off|status]. " +
+    "No argument toggles between off and the default level (full).";
+
+export default function cavemanExtension(pi: ExtensionAPI): void {
+    let activeLevel: Level | null = null;
+    let cachedBody: string | null = null;
+
+    function loadBody(): string {
+        if (cachedBody === null) {
+            cachedBody = readSkillBody();
+        }
+        return cachedBody;
+    }
+
+    function persist(): void {
+        pi.appendEntry<PersistedState>(ENTRY_TYPE, { level: activeLevel });
+    }
+
+    pi.on("session_start", async (_event, ctx) => {
+        let restored: Level | null = null;
+        for (const entry of ctx.sessionManager.getEntries()) {
+            if (entry.type === "custom" && entry.customType === ENTRY_TYPE) {
+                const data = entry.data as PersistedState | undefined;
+                restored = data && isLevel(data.level) ? data.level : null;
+            }
+        }
+        activeLevel = restored;
+        ctx.ui.setStatus(STATUS_KEY, activeLevel ? statusText(activeLevel) : undefined);
+    });
+
+    pi.on("before_agent_start", async (event) => {
+        if (!activeLevel) return;
+        const body = loadBody();
+        return {
+            systemPrompt: `${event.systemPrompt}\n\n${buildInjection(activeLevel, body)}`,
+        };
+    });
+
+    pi.registerCommand("caveman", {
+        description: `Toggle compressed-output mode. ${HELP}`,
+        getArgumentCompletions: (prefix) => {
+            const items = [...LEVELS, "off", "status"];
+            const lower = prefix.toLowerCase();
+            const matches = items
+                .filter((value) => value.startsWith(lower))
+                .map((value) => ({ value, label: value }));
+            return matches.length > 0 ? matches : null;
+        },
+        handler: async (args, ctx) => {
+            const arg = args.trim().toLowerCase();
+
+            if (arg === "status") {
+                ctx.ui.notify(
+                    activeLevel ? `caveman: ${activeLevel}` : "caveman: off",
+                    "info",
+                );
+                return;
+            }
+
+            if (arg === "off") {
+                activeLevel = null;
+                persist();
+                ctx.ui.setStatus(STATUS_KEY, undefined);
+                ctx.ui.notify("caveman: off", "info");
+                return;
+            }
+
+            if (arg === "") {
+                activeLevel = activeLevel ? null : DEFAULT_LEVEL;
+            } else {
+                const level = parseLevel(arg);
+                if (!level) {
+                    ctx.ui.notify(
+                        `caveman: unknown level "${arg}". ${HELP}`,
+                        "warning",
+                    );
+                    return;
+                }
+                activeLevel = level;
+            }
+
+            persist();
+            ctx.ui.setStatus(
+                STATUS_KEY,
+                activeLevel ? statusText(activeLevel) : undefined,
+            );
+            ctx.ui.notify(
+                activeLevel ? `caveman: ${activeLevel}` : "caveman: off",
+                "info",
+            );
+        },
+    });
+}

package/extensions/notify-on-stop/README.md

@@ -0,0 +1,114 @@
+# notify-on-stop
+
+Plays a sound, speaks a message, or fires a desktop notification every time the pi agent finishes a turn (`agent_end` event). Cuts the "is it done yet?" tab-switching tax.
+
+Ships as part of [`@astrofoundry/pi-astro`](../../README.md). No extra install.
+
+## Default: off
+
+The extension does **nothing** by default. Enable it once with:
+
+```
+/notify on
+```
+
+State is persisted to `~/.pi/agent/notify-on-stop.json` and survives session restarts and `chezmoi apply`. To turn it back off:
+
+```
+/notify off
+```
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/notify on` | Enable for this and future sessions. Persists. |
+| `/notify off` | Disable for this and future sessions. Persists. |
+| `/notify` or `/notify status` | Print current state and the resolved command |
+| `/notify test` | Run the resolved command immediately, regardless of on/off state |
+
+Argument autocomplete is wired — type `/notify ` and tab-cycle.
+
+## Defaults per platform
+
+When enabled, the extension runs:
+
+| Platform | Command |
+|---|---|
+| macOS | `afplay /System/Library/Sounds/Glass.aiff && say -v "Samantha (Enhanced)" "Agent done"` |
+| Linux | `notify-send "pi" "Agent done"` (only if `notify-send` exists on `PATH`) |
+| Windows / other | Nothing — wire your own command via `PI_STOP_NOTIFY` |
+
+Errors from the notify command are swallowed — a broken sound or missing voice will never surface in pi output.
+
+## macOS voice setup (one-time)
+
+The default speaks via the `Samantha (Enhanced)` voice. If it isn't installed, the `say` command silently fails and you only hear the Glass sound. Install it once:
+
+1. **System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…**
+2. Expand **English**, check **Samantha (Enhanced)**, click **Done** (downloads ~500 MB – 1 GB).
+3. Verify: `say -v "Samantha (Enhanced)" hi`.
+
+If you'd rather skip the install, override with `PI_STOP_NOTIFY_VOICE` or replace the whole command via `PI_STOP_NOTIFY` — see below.
+
+## Configuration (env vars)
+
+Env vars control **what** runs, not **whether**. The on/off toggle is `/notify on|off`.
+
+Set in your shell rc (`.zshrc`/`.bashrc`) so they apply to every pi session.
+
+### `PI_STOP_NOTIFY` — replace the full command
+
+Wins over the platform default. Wins over `PI_STOP_NOTIFY_VOICE`.
+
+```bash
+# Just play the sound, no speech
+export PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff'
+
+# Speak something custom
+export PI_STOP_NOTIFY='say "Pi just finished, get back here"'
+
+# Linux: dunst / libnotify
+export PI_STOP_NOTIFY='notify-send "pi" "Done" -u low'
+```
+
+### `PI_STOP_NOTIFY_VOICE` — change only the macOS voice
+
+Used when you keep the default Glass+say behaviour but prefer a different voice. Ignored on Linux/Windows. Ignored when `PI_STOP_NOTIFY` is set.
+
+```bash
+export PI_STOP_NOTIFY_VOICE="Alex"
+export PI_STOP_NOTIFY_VOICE="Daniel (Enhanced)"
+export PI_STOP_NOTIFY_VOICE="Karen"
+```
+
+List available voices: `say -v ?`.
+
+### `PI_STOP_NOTIFY_OFF=1` — hard kill
+
+Overrides the persisted on/off state. Useful for CI / headless runs where you want the extension globally muted regardless of the state file.
+
+```bash
+export PI_STOP_NOTIFY_OFF=1
+```
+
+## Quick recipes
+
+| Goal | What to do |
+|---|---|
+| Enable | `/notify on` |
+| Disable | `/notify off` |
+| Test the command without changing state | `/notify test` |
+| Sound only, no voice | `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff'` |
+| Voice only, no sound | `PI_STOP_NOTIFY='say "Done"'` |
+| Different macOS voice | `PI_STOP_NOTIFY_VOICE="Alex"` |
+| Custom desktop notification | `PI_STOP_NOTIFY='terminal-notifier -title pi -message Done -sound Glass'` |
+| Hard-mute everywhere | `export PI_STOP_NOTIFY_OFF=1` |
+
+## Troubleshooting
+
+- **`/notify on` says "no command resolves on this platform"** — Windows or unknown platform. Set `PI_STOP_NOTIFY` to your own command.
+- **Nothing happens on macOS even though `/notify status` shows `on`** — the Samantha (Enhanced) voice is probably missing. Either install it (above) or set `PI_STOP_NOTIFY_VOICE` to a voice you have. Run `/notify test` to see whether the command itself runs.
+- **Nothing happens on Linux** — install `libnotify` (`apt install libnotify-bin`) or override `PI_STOP_NOTIFY`.
+- **`/notify status` shows the right command but nothing happens** — the command is launched via `/bin/sh` with a 10-second timeout, and all errors are silenced. Run the command directly in a shell to see the real error.
+- **Env-var changes don't take effect** — env vars are read once when the extension loads. Restart pi after changing them. The on/off state, by contrast, applies immediately.

package/extensions/notify-on-stop/index.test.ts

@@ -5,7 +5,6 @@ const execMock = vi.fn();
 vi.mock("node:child_process", () => ({
     exec: (cmd: string, opts: unknown, cb?: unknown) => {
         execMock(cmd, opts, cb);
-        // Return a chainable fake child with on/stdout/stderr
         const fake = {
             on: vi.fn(),
             stdout: { on: vi.fn() },
@@ -15,15 +14,39 @@ vi.mock("node:child_process", () => ({
     },
 }));
 
+const fakeFiles = new Map<string, string>();
+
+vi.mock("node:fs", () => ({
+    existsSync: (p: string) => fakeFiles.has(p),
+    readFileSync: (p: string) => {
+        const value = fakeFiles.get(p);
+        if (value === undefined) throw new Error(`ENOENT: ${p}`);
+        return value;
+    },
+    writeFileSync: (p: string, data: string) => {
+        fakeFiles.set(p, data);
+    },
+    mkdirSync: vi.fn(),
+}));
+
 type Handler = (event: unknown, ctx: unknown) => void | Promise<void>;
 type CommandHandler = (args: string, ctx: unknown) => Promise<void> | void;
 
-function makePi(): {
+interface FakePi {
     handlers: Record<string, Handler>;
-    commands: Map<string, { handler: CommandHandler }>;
+    commands: Map<string, { handler: CommandHandler; getArgumentCompletions?: (p: string) => unknown }>;
     on: (event: string, h: Handler) => void;
-    registerCommand: (name: string, opts: { description?: string; handler: CommandHandler }) => void;
-} {
+    registerCommand: (
+        name: string,
+        opts: {
+            description?: string;
+            handler: CommandHandler;
+            getArgumentCompletions?: (p: string) => unknown;
+        },
+    ) => void;
+}
+
+function makePi(): FakePi {
     const handlers: Record<string, Handler> = {};
     const commands = new Map();
     return {
@@ -33,7 +56,10 @@ function makePi(): {
             handlers[event] = h;
         },
         registerCommand: (name, opts) => {
-            commands.set(name, { handler: opts.handler });
+            commands.set(name, {
+                handler: opts.handler,
+                getArgumentCompletions: opts.getArgumentCompletions,
+            });
         },
     };
 }
@@ -48,6 +74,11 @@ function setPlatform(p: NodeJS.Platform): void {
     Object.defineProperty(process, "platform", { value: p, configurable: true });
 }
 
+function seedEnabled(enabled: boolean): void {
+    const stateFile = `${process.env.HOME}/.pi/agent/notify-on-stop.json`;
+    fakeFiles.set(stateFile, JSON.stringify({ enabled }));
+}
+
 describe("notify-on-stop", () => {
     const origCmd = process.env.PI_STOP_NOTIFY;
     const origOff = process.env.PI_STOP_NOTIFY_OFF;
@@ -56,6 +87,7 @@ describe("notify-on-stop", () => {
     beforeEach(() => {
         vi.resetModules();
         execMock.mockReset();
+        fakeFiles.clear();
         delete process.env.PI_STOP_NOTIFY;
         delete process.env.PI_STOP_NOTIFY_OFF;
         delete process.env.PI_STOP_NOTIFY_VOICE;
@@ -71,174 +103,215 @@ describe("notify-on-stop", () => {
         else process.env.PI_STOP_NOTIFY_VOICE = origVoice;
     });
 
-    it("runs default command on agent_end (macOS): afplay + say with Samantha (Enhanced)", async () => {
+    it("defaults to off — agent_end runs nothing on a fresh install", async () => {
         setPlatform("darwin");
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        expect(execMock).toHaveBeenCalled();
-        const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toMatch(/^afplay \/System\/Library\/Sounds\/Glass\.aiff && say -v /);
-        expect(cmd).toContain("'Samantha (Enhanced)'");
-        expect(cmd).toContain("'Agent done'");
+        expect(execMock).not.toHaveBeenCalled();
     });
 
-    it("PI_STOP_NOTIFY_VOICE overrides the default voice (macOS)", async () => {
+    it("/notify on persists enabled=true and starts firing on agent_end (macOS default)", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("on", ctx);
+        expect(fakeFiles.get(`${process.env.HOME}/.pi/agent/notify-on-stop.json`)).toContain('"enabled": true');
         pi.handlers.agent_end({}, makeCtx());
         const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toContain("say -v 'Alex'");
-        expect(cmd).not.toContain("Samantha");
+        expect(cmd).toMatch(/^afplay \/System\/Library\/Sounds\/Glass\.aiff && say -v /);
+        expect(cmd).toContain("'Samantha (Enhanced)'");
     });
 
-    it("PI_STOP_NOTIFY_VOICE with apostrophes is POSIX-safely quoted", async () => {
+    it("/notify off persists enabled=false and stops firing on agent_end", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_VOICE = "O'Neill";
+        seedEnabled(true);
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("off", ctx);
+        expect(fakeFiles.get(`${process.env.HOME}/.pi/agent/notify-on-stop.json`)).toContain('"enabled": false');
         pi.handlers.agent_end({}, makeCtx());
-        const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toContain("say -v 'O'\\''Neill'");
+        expect(execMock).not.toHaveBeenCalled();
+        expect(ctx.ui.notify).toHaveBeenCalledWith("notify: off (persisted)", "info");
     });
 
-    it("PI_STOP_NOTIFY_VOICE with only whitespace falls back to default voice (macOS)", async () => {
+    it("state survives across extension reloads", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_VOICE = "   ";
+        seedEnabled(true);
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toContain("'Samantha (Enhanced)'");
+        expect(execMock).toHaveBeenCalled();
     });
 
-    it("PI_STOP_NOTIFY_VOICE is ignored when PI_STOP_NOTIFY overrides the full command", async () => {
+    it("PI_STOP_NOTIFY_OFF=1 hard-kills even when enabled is true", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY = "my custom --cmd";
-        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_OFF = "1";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
+        expect(execMock).not.toHaveBeenCalled();
     });
 
-    it("PI_STOP_NOTIFY_VOICE has no effect on Linux default", async () => {
-        setPlatform("linux");
-        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
+    it("/notify status reflects on/off", async () => {
+        setPlatform("darwin");
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        pi.handlers.agent_end({}, makeCtx());
-        const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toMatch(/notify-send/);
-        expect(cmd).not.toContain("say");
-        expect(cmd).not.toContain("Alex");
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("status", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/notify: off/), "info");
+        await pi.commands.get("notify")!.handler("on", ctx);
+        await pi.commands.get("notify")!.handler("status", ctx);
+        expect(ctx.ui.notify).toHaveBeenLastCalledWith(expect.stringMatching(/notify: on .* will run /), "info");
     });
 
-    it("runs custom PI_STOP_NOTIFY over default", async () => {
+    it("/notify status reports hard-kill via env var", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY = "my custom --cmd";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_OFF = "1";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        pi.handlers.agent_end({}, makeCtx());
-        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("status", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/PI_STOP_NOTIFY_OFF=1/), "info");
     });
 
-    it("does NOT run anything when PI_STOP_NOTIFY_OFF=1", async () => {
+    it("/notify test runs the command immediately even when disabled", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_OFF = "1";
+        process.env.PI_STOP_NOTIFY = "test-cmd";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        pi.handlers.agent_end({}, makeCtx());
-        expect(execMock).not.toHaveBeenCalled();
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("test", ctx);
+        expect(execMock.mock.calls[0][0]).toBe("test-cmd");
     });
 
-    it("does nothing on an unsupported platform with no env", async () => {
+    it("/notify test warns when nothing configured (unsupported platform)", async () => {
         setPlatform("win32");
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        pi.handlers.agent_end({}, makeCtx());
-        expect(execMock).not.toHaveBeenCalled();
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("test", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/nothing configured/), "warning");
     });
 
-    it("Linux default uses notify-send", async () => {
-        setPlatform("linux");
+    it("/notify on warns if no command resolves on this platform", async () => {
+        setPlatform("win32");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("on", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(
+            expect.stringMatching(/notify: on, but no command resolves/),
+            "warning",
+        );
+    });
+
+    it("PI_STOP_NOTIFY overrides the default command", async () => {
+        setPlatform("darwin");
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY = "my custom --cmd";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        expect(execMock.mock.calls[0][0]).toMatch(/notify-send/);
+        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
     });
 
-    it("trims whitespace on PI_STOP_NOTIFY and ignores empty strings", async () => {
+    it("PI_STOP_NOTIFY_VOICE overrides the macOS default voice", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY = "   ";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        expect(execMock.mock.calls[0][0]).toMatch(/afplay/);
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("say -v 'Alex'");
+        expect(cmd).not.toContain("Samantha");
     });
 
-    it("/notify status reports current command", async () => {
+    it("PI_STOP_NOTIFY_VOICE with apostrophes is POSIX-safely quoted", async () => {
         setPlatform("darwin");
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_VOICE = "O'Neill";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("status", ctx);
-        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/afplay/), "info");
+        pi.handlers.agent_end({}, makeCtx());
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("say -v 'O'\\''Neill'");
     });
 
-    it("/notify status reports disabled when PI_STOP_NOTIFY_OFF", async () => {
+    it("PI_STOP_NOTIFY_VOICE with only whitespace falls back to default voice", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_OFF = "1";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_VOICE = "   ";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("", ctx);
-        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/disabled/), "info");
+        pi.handlers.agent_end({}, makeCtx());
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("'Samantha (Enhanced)'");
     });
 
-    it("/notify test runs the command immediately", async () => {
+    it("PI_STOP_NOTIFY_VOICE is ignored when PI_STOP_NOTIFY overrides the full command", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY = "test-cmd";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY = "my custom --cmd";
+        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("test", ctx);
-        expect(execMock.mock.calls[0][0]).toBe("test-cmd");
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
     });
 
-    it("/notify test warns when nothing configured", async () => {
-        setPlatform("win32");
+    it("Linux default uses notify-send", async () => {
+        setPlatform("linux");
+        seedEnabled(true);
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("test", ctx);
-        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/nothing configured/), "warning");
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock.mock.calls[0][0]).toMatch(/notify-send/);
     });
 
-    it("/notify off gives persistence guidance", async () => {
+    it("argument autocomplete returns on/off/status/test", async () => {
         setPlatform("darwin");
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("off", ctx);
-        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/PI_STOP_NOTIFY_OFF/), "info");
+        const completions = pi.commands.get("notify")!.getArgumentCompletions!("");
+        expect(completions).toEqual(
+            expect.arrayContaining([
+                { value: "on", label: "on" },
+                { value: "off", label: "off" },
+                { value: "status", label: "status" },
+                { value: "test", label: "test" },
+            ]),
+        );
+    });
+
+    it("argument autocomplete returns null when no candidate matches", async () => {
+        setPlatform("darwin");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const completions = pi.commands.get("notify")!.getArgumentCompletions!("zzz");
+        expect(completions).toBeNull();
     });
 });

package/extensions/notify-on-stop/index.ts

@@ -1,4 +1,7 @@
 import { exec } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 const ENV_CMD = "PI_STOP_NOTIFY";
@@ -8,6 +11,25 @@ const TIMEOUT_MS = 10_000;
 const DEFAULT_VOICE = "Samantha (Enhanced)";
 const MACOS_SPOKEN_MESSAGE = "Agent done";
 
+const STATE_DIR = path.join(os.homedir(), ".pi", "agent");
+const STATE_FILE = path.join(STATE_DIR, "notify-on-stop.json");
+
+interface PersistedState {
+    enabled: boolean;
+}
+
+function readEnabled(): boolean {
+    if (!fs.existsSync(STATE_FILE)) return false;
+    const raw = fs.readFileSync(STATE_FILE, "utf8");
+    const parsed = JSON.parse(raw) as PersistedState;
+    return parsed.enabled === true;
+}
+
+function writeEnabled(enabled: boolean): void {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(STATE_FILE, `${JSON.stringify({ enabled }, null, 2)}\n`);
+}
+
 function shellQuote(value: string): string {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -34,14 +56,16 @@ function resolveCommand(): string | undefined {
 
 function runNotify(cmd: string): void {
     const child = exec(cmd, { shell: "/bin/sh", timeout: TIMEOUT_MS });
-    // Swallow errors so a broken notify command never surfaces into pi output.
     child.on("error", () => {});
     child.stderr?.on("data", () => {});
     child.stdout?.on("data", () => {});
 }
 
 export default function notifyOnStopExtension(pi: ExtensionAPI): void {
+    let enabled = readEnabled();
+
     pi.on("agent_end", () => {
+        if (!enabled) return;
         const cmd = resolveCommand();
         if (!cmd) return;
         runNotify(cmd);
@@ -49,31 +73,60 @@ export default function notifyOnStopExtension(pi: ExtensionAPI): void {
 
     pi.registerCommand("notify", {
         description:
-            "Stop-notify status/test. Usage: /notify [status|test|off]. Configure via env PI_STOP_NOTIFY (full override) or PI_STOP_NOTIFY_VOICE (macOS default voice); disable with PI_STOP_NOTIFY_OFF=1.",
+            "Stop-notify control. Usage: /notify [on|off|status|test]. State persists in ~/.pi/agent/notify-on-stop.json. Defaults to off; PI_STOP_NOTIFY_OFF=1 hard-kills regardless.",
+        getArgumentCompletions: (prefix) => {
+            const items = ["on", "off", "status", "test"];
+            const lower = prefix.toLowerCase();
+            const matches = items
+                .filter((value) => value.startsWith(lower))
+                .map((value) => ({ value, label: value }));
+            return matches.length > 0 ? matches : null;
+        },
         handler: async (args, ctx) => {
             const sub = args.trim().toLowerCase() || "status";
+
             if (sub === "test") {
                 const cmd = resolveCommand();
                 if (!cmd) {
-                    ctx.ui.notify("notify: nothing configured / disabled", "warning");
+                    ctx.ui.notify("notify: nothing configured (no platform default and no PI_STOP_NOTIFY)", "warning");
                     return;
                 }
                 runNotify(cmd);
                 ctx.ui.notify(`notify: ran "${cmd}"`, "info");
                 return;
             }
-            if (sub === "off") {
+
+            if (sub === "on") {
+                enabled = true;
+                writeEnabled(true);
+                const cmd = resolveCommand();
                 ctx.ui.notify(
-                    `notify: to disable persistently, set ${ENV_OFF}=1 in your shell rc; this session's behavior is driven by env at startup.`,
-                    "info",
+                    cmd
+                        ? `notify: on — will run "${cmd}" on agent_end`
+                        : `notify: on, but no command resolves on this platform (set PI_STOP_NOTIFY)`,
+                    cmd ? "info" : "warning",
                 );
                 return;
             }
+
+            if (sub === "off") {
+                enabled = false;
+                writeEnabled(false);
+                ctx.ui.notify("notify: off (persisted)", "info");
+                return;
+            }
+
             const cmd = resolveCommand();
+            const hardKilled = process.env[ENV_OFF] === "1";
+            const stateLabel = hardKilled
+                ? `off (PI_STOP_NOTIFY_OFF=1)`
+                : enabled
+                  ? "on"
+                  : "off";
             ctx.ui.notify(
-                cmd
-                    ? `notify: will run "${cmd}" on agent_end`
-                    : `notify: disabled (no default for this platform or ${ENV_OFF}=1)`,
+                cmd && enabled && !hardKilled
+                    ? `notify: ${stateLabel} — will run "${cmd}" on agent_end`
+                    : `notify: ${stateLabel}${cmd ? "" : " (no command resolves on this platform)"}`,
                 "info",
             );
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/caveman/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: caveman
+description: >
+  Persistent compressed-output mode. Strips fillers, hedging, and connectives
+  from assistant prose to cut output tokens by ~70-75% while preserving every
+  technical fact. Six intensity levels: lite, full (default), ultra, wenyan-lite,
+  wenyan-full, wenyan-ultra. Activate with /caveman or /skill:caveman; deactivate
+  with /caveman off, "stop caveman", or "normal mode".
+---
+
+# Caveman Mode
+
+Output compression via principled prose-stripping. Substance is preserved
+verbatim — only redundancy and social padding are removed. Code, error
+strings, command lines, paths, identifiers, and version numbers are reproduced
+unchanged.
+
+## Persistence
+
+While active, **every** assistant response uses caveman compression. Do not
+drift back to verbose prose mid-conversation, even after long context, after
+context compaction, or after style instructions injected by other extensions.
+Resume caveman immediately after any unavoidable break (security warning,
+destructive-action confirmation, multi-step procedure).
+
+The level set by `/caveman <level>` persists until changed or session end.
+Switch off only on explicit user request: "stop caveman", "normal mode", or
+`/caveman off`.
+
+## Compression rules
+
+Drop:
+
+- Articles when grammatically optional (a, an, the).
+- Filler adverbs and intensifiers (just, really, basically, actually, simply, very).
+- Pleasantries (sure, certainly, of course, happy to, let me, I'd be glad to).
+- Hedging phrases (it seems, perhaps, you might want to, I think).
+- Restating the question before answering it.
+
+Keep:
+
+- Every technical fact, parameter name, file path, command, and version number.
+- Code blocks verbatim. Error messages quoted exactly.
+- Cause-and-effect order — never reorder steps for terseness.
+- Punctuation needed for parsing (commas separating list items, periods between independent claims).
+
+Sentence pattern: `<subject> <action> <reason>. <next step>.`
+
+Anti-example: "Sure! I'd be happy to help you with that. The issue you're seeing is most likely caused by..."
+Example: "Bug in auth middleware. Token expiry uses `<` not `<=`. Fix:"
+
+## Intensity levels
+
+| Level | Behaviour |
+|---|---|
+| **lite** | Drop fillers and pleasantries only. Keep articles + full sentences. Professional but tight. |
+| **full** | Drop articles. Sentence fragments allowed. Short synonyms (fix not "implement a solution for"). Default. |
+| **ultra** | Abbreviate (DB, auth, cfg, req, res, fn, impl). Replace conjunctions with arrows for causality (X → Y). Single word when sufficient. |
+| **wenyan-lite** | Classical Chinese register, modern grammar. Drop fillers and hedging. |
+| **wenyan-full** | Full 文言文 — verb precedes object, omit subject when implied, classical particles (之 / 乃 / 為 / 其). 80–90% character reduction. |
+| **wenyan-ultra** | Maximum classical compression. One classical phrase per thought. |
+
+### Worked example — "Why does this React component re-render on every parent update?"
+
+- lite: "Your component re-renders because every render creates a new object reference for the prop. Wrap it in `useMemo`."
+- full: "New object ref each render. Inline obj prop = new ref = re-render. Wrap in `useMemo`."
+- ultra: "Inline obj prop → new ref → re-render. `useMemo`."
+- wenyan-lite: "組件每次重繪皆生新對象參照。以 `useMemo` 包之。"
+- wenyan-full: "每繪生新參照，故重繪。以 `useMemo` 包之。"
+- wenyan-ultra: "新參照→重繪。`useMemo` 包。"
+
+### Worked example — "Explain database connection pooling."
+
+- lite: "Connection pooling reuses already-open connections instead of opening a new one per request, avoiding handshake overhead."
+- full: "Pool reuse open connections. No new handshake per request."
+- ultra: "Pool = reuse conn. Skip handshake → fast under load."
+- wenyan-lite: "連接池重用已開連接，免逐請求重握之耗。"
+- wenyan-full: "池存連接而重用，無逐請求重握之耗。"
+- wenyan-ultra: "池連，免握。"
+
+## Auto-clarity (override caveman temporarily)
+
+Drop caveman compression when ambiguity would harm correctness:
+
+- Security warnings.
+- Confirmations for destructive or irreversible operations.
+- Multi-step procedures whose order matters and where fragments would invite misreading.
+- The user repeats a question or asks for clarification.
+
+Use full prose for the duration of the override. Resume caveman immediately
+after the clarified step is complete.
+
+Example — destructive operation:
+
+> **Warning:** the next command permanently deletes every row in `users` and
+> cannot be undone:
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Verify a current backup exists before running. Caveman resume.
+
+## Boundaries (caveman never applies)
+
+- Source code, commit messages, PR descriptions, code review comments — write in normal prose.
+- Documentation files (`.md`, `.mdx`, `.rst`) — caveman is for chat, not artifacts.
+- Quoted log lines, stack traces, error messages — reproduce exactly.
+
+## Deactivation
+
+- `/caveman off` — explicit slash command.
+- "stop caveman" / "normal mode" / "disable caveman" — natural-language requests.
+
+After deactivation, return to normal prose immediately on the next response.