@diegopetrucci/pi-extensions 0.1.63 → 0.1.64

package/README.md

@@ -2,7 +2,7 @@
 
 [![Total npm downloads](https://img.shields.io/npm/dt/%40diegopetrucci%2Fpi-extensions?label=total%20npm%20downloads)](https://www.npmjs.com/package/@diegopetrucci/pi-extensions)
 
-A collection of [pi](https://pi.dev) agent extensions I made. (btw, [I am also building my own harness on top of pi](https://github.com/diegopetrucci/the-last-harness). have a look!)
+A collection of [pi](https://pi.dev) agent extensions I made. (Btw, [I am also building my own harness on top of pi](https://github.com/diegopetrucci/the-last-harness). Have a look if that sounds interesting!)
 
 ### Subagents
 
@@ -13,9 +13,7 @@ A collection of [pi](https://pi.dev) agent extensions I made. (btw, [I am also b
 
 ### Providers
 
-- [`claude-fast`](./extensions/claude-fast): Standalone-only provider-specific alternative that adds `/claude-fast` for supported Anthropic Claude Opus models.
 - [`fast`](./extensions/fast): Adds one `/fast` toggle that enables the provider-specific Fast mode for the currently selected supported OpenAI Codex or Anthropic Claude model.
-- [`openai-fast`](./extensions/openai-fast): Standalone-only provider-specific alternative that adds `/fast` for ChatGPT-auth GPT-5.4, GPT-5.5, and GPT-5.6 Codex variants.
 
 ### UI
 
@@ -49,10 +47,13 @@ A collection of [pi](https://pi.dev) agent extensions I made. (btw, [I am also b
 - [`gnosis`](./extensions/gnosis): Exposes the `gn` repo-local knowledge base CLI as an agent tool for searching and recording durable project decisions, constraints, and intent.
 - [`illustrations-to-explain-things`](./extensions/illustrations-to-explain-things): Adds a skill for generating clean, absurd Xiaohei-style article illustrations, shot lists, image edits, and visual metaphors.
 - [`inline-bash`](./extensions/inline-bash): Expands `!{command}` snippets in user prompts by running them through bash before the prompt reaches the agent.
-- [`notify`](./extensions/notify): Sends configurable terminal, desktop, bell, and sound notifications when pi finishes and is ready for input.
+- [`notify`](./extensions/notify): Sends configurable terminal, desktop, bell, and sound notifications when pi finishes and is ready for input, including tmux-aware terminal notifications.
 - [`todo`](./extensions/todo): Adds a branch-aware `todo` tool for the agent and a `/todos` viewer for users..
 
-(For the full list of pi extensions I use, [check out my dotfiles](https://github.com/diegopetrucci/dot/blob/main/.pi/agent/settings.json).)
+### Deprecated
+
+- [`claude-fast`](./extensions/claude-fast): Standalone-only provider-specific alternative that adds `/claude-fast` for supported Anthropic Claude Opus models. [Deprecated, please use [`fast`](https://github.com/diegopetrucci/pi-extensions/blob/main/extensions/fast) instead.]
+- [`openai-fast`](./extensions/openai-fast): Standalone-only provider-specific alternative that adds `/fast` for ChatGPT-auth GPT-5.4, GPT-5.5, and GPT-5.6 Codex variants. [Deprecated, please use [`fast`](https://github.com/diegopetrucci/pi-extensions/blob/main/extensions/fast) instead.]
 
 ## Install
 

package/extensions/notify/README.md

@@ -11,6 +11,9 @@ This started from the original `notify.ts` example in [`earendil-works/pi`](http
 - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
 - OSC 99: Kitty
 
+Both are wrapped in tmux's DCS passthrough automatically when `$TMUX` is set;
+see [Running inside tmux](#running-inside-tmux).
+
 ### Desktop notifications
 
 - macOS Notification Center via `osascript`
@@ -86,7 +89,8 @@ Example:
     "sound": false
   },
   "terminal": {
-    "backend": "auto"
+    "backend": "auto",
+    "tmuxPassthrough": "auto"
   },
   "desktop": {
     "backend": "auto"
@@ -102,6 +106,39 @@ Example:
 }
 ```
 
+### Running inside tmux
+
+Under tmux, terminal notifications need one line in your `tmux.conf`:
+
+```tmux
+set -g allow-passthrough all
+```
+
+Without it, notifications never reach your terminal. tmux is the terminal
+emulator for the pane, so the escape sequence is delivered to tmux rather than
+to the terminal that can act on it. tmux has no OSC 777 or OSC 99 handler
+(checked in 3.7b, whose OSC dispatch covers 4/7/8/9;4/10/11/12/52/104/133) and
+does not forward OSC codes it does not recognise, so the notification is parsed
+and silently dropped. Desktop, bell, and sound channels are unaffected.
+
+This extension therefore wraps terminal notifications in tmux's DCS passthrough
+(`ESC P tmux ; … ESC \`), which asks tmux to forward the payload to the outer
+terminal verbatim — but tmux only honours that when `allow-passthrough` is on.
+
+Use `all` rather than `on`: under `on`, tmux only honours passthrough from panes
+that are currently *visible*, which discards exactly the notification you want —
+the one fired while you are looking at another window. The trade-off is that
+`all` lets a program in any pane write bytes straight to the attached terminal;
+notification sequences render nothing, but a malformed passthrough from a
+background pane can garble the display, since those bytes bypass tmux's screen
+model.
+
+Set `terminal.tmuxPassthrough` to `never` to opt out of wrapping (for example if
+your multiplexer forwards these codes itself), or `always` to force it when
+`$TMUX` is not visible in the environment. Wrapping is safe to leave on `auto`:
+with passthrough disabled in tmux, a wrapped sequence is dropped exactly like a
+bare one, so nothing regresses.
+
 ### Enable sound
 
 Minimal example:
@@ -127,6 +164,7 @@ You can also customize the sound backend and options if needed.
 - `channels.bell`: enable terminal bell
 - `channels.sound`: enable sound playback
 - `terminal.backend`: `auto`, `osc777`, `osc99`, `none`
+- `terminal.tmuxPassthrough`: `auto` (wrap when `$TMUX` is set), `always`, `never`
 - `desktop.backend`: `auto`, `macos`, `linux`, `windows-toast`, `none`
 - `sound.backend`: `auto`, `macos`, `linux`, `windows-beep`, `command`, `none`
 - `sound.name`: macOS system sound name, like `Glass` or `Hero`
@@ -138,6 +176,7 @@ You can also customize the sound backend and options if needed.
 ## Notes
 
 - Hooks the `agent_settled` event so automatic retries, compaction retries, and queued follow-ups do not trigger intermediate notifications.
+- Terminal notifications are wrapped for tmux when `$TMUX` is set, which also requires `set -g allow-passthrough all` in `tmux.conf`.
 - Default message is `Pi` / `Ready for input`.
 - Terminal, desktop, bell, and sound channels can be enabled independently.
 - To opt into sound playback, set `channels.sound` to `true`.

package/extensions/notify/index.ts

@@ -3,7 +3,7 @@
  *
  * Sends notifications when Pi agent is done and waiting for input.
  * Supports multiple channels:
- * - terminal notifications: OSC 777 and OSC 99
+ * - terminal notifications: OSC 777 and OSC 99, wrapped for tmux when needed
  * - desktop notifications: macOS Notification Center, Linux notify-send, Windows toast
  * - terminal bell
  * - sound playback
@@ -20,6 +20,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
 
 type TerminalBackend = "auto" | "osc777" | "osc99" | "none";
+type TmuxPassthrough = "auto" | "always" | "never";
 type DesktopBackend = "auto" | "macos" | "linux" | "windows-toast" | "none";
 type SoundBackend = "auto" | "macos" | "linux" | "windows-beep" | "command" | "none";
 
@@ -41,6 +42,7 @@ interface NotifyConfig {
 	};
 	terminal: {
 		backend: TerminalBackend;
+		tmuxPassthrough: TmuxPassthrough;
 	};
 	desktop: {
 		backend: DesktopBackend;
@@ -68,6 +70,7 @@ const DEFAULT_CONFIG: NotifyConfig = {
 	},
 	terminal: {
 		backend: "auto",
+		tmuxPassthrough: "auto",
 	},
 	desktop: {
 		backend: "auto",
@@ -145,13 +148,47 @@ function windowsToastScript(title: string, body: string): string {
 	].join("; ");
 }
 
-function notifyOSC777(title: string, body: string): void {
-	process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
+/**
+ * Inside tmux, terminal notifications are written to tmux, not to the terminal
+ * that can act on them: tmux is the pane's emulator and parses the sequence
+ * itself. tmux has no OSC 777 or OSC 99 handler (checked in 3.7b, whose OSC
+ * dispatch covers 4/7/8/9;4/10/11/12/52/104/133) and does not forward OSC codes
+ * it does not recognise, so both backends are silently dropped.
+ *
+ * tmux's DCS passthrough asks it to write a payload to the outer terminal
+ * verbatim. Every ESC inside the payload must be doubled.
+ *
+ * Users must also allow passthrough in tmux.conf:
+ *
+ *   set -g allow-passthrough all
+ *
+ * `all` rather than `on`, because `on` only honours passthrough from panes that
+ * are currently visible - which drops exactly the notification that matters,
+ * the one fired while the user is looking at a different window. When
+ * passthrough is disabled entirely, the wrapped sequence is dropped just like
+ * the bare one, so wrapping is never a regression.
+ */
+function wrapForTmux(sequence: string): string {
+	return `\x1bPtmux;${sequence.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+
+function shouldWrapForTmux(config: NotifyConfig): boolean {
+	if (config.terminal.tmuxPassthrough === "never") return false;
+	if (config.terminal.tmuxPassthrough === "always") return true;
+	return Boolean(process.env.TMUX);
+}
+
+function writeTerminalSequence(sequence: string, wrap: boolean): void {
+	process.stdout.write(wrap ? wrapForTmux(sequence) : sequence);
 }
 
-function notifyOSC99(title: string, body: string): void {
-	process.stdout.write(`\x1b]99;i=1:d=0;${title}\x1b\\`);
-	process.stdout.write(`\x1b]99;i=1:p=body;${body}\x1b\\`);
+function notifyOSC777(title: string, body: string, wrap: boolean): void {
+	writeTerminalSequence(`\x1b]777;notify;${title};${body}\x07`, wrap);
+}
+
+function notifyOSC99(title: string, body: string, wrap: boolean): void {
+	writeTerminalSequence(`\x1b]99;i=1:d=0;${title}\x1b\\`, wrap);
+	writeTerminalSequence(`\x1b]99;i=1:p=body;${body}\x1b\\`, wrap);
 }
 
 function ringBell(): void {
@@ -195,13 +232,18 @@ function detectSoundBackend(config: NotifyConfig): Exclude<SoundBackend, "auto">
 	return "none";
 }
 
-function sendTerminalNotification(title: string, body: string, backend: Exclude<TerminalBackend, "auto">): void {
+function sendTerminalNotification(
+	title: string,
+	body: string,
+	backend: Exclude<TerminalBackend, "auto">,
+	wrap: boolean,
+): void {
 	if (backend === "osc99") {
-		notifyOSC99(title, body);
+		notifyOSC99(title, body, wrap);
 		return;
 	}
 	if (backend === "osc777") {
-		notifyOSC777(title, body);
+		notifyOSC777(title, body, wrap);
 	}
 }
 
@@ -263,7 +305,12 @@ export default function notifyExtension(pi: ExtensionAPI) {
 		const tasks: Array<Promise<unknown>> = [];
 
 		if (config.channels.terminal) {
-			sendTerminalNotification(config.title, config.body, detectTerminalBackend(config));
+			sendTerminalNotification(
+				config.title,
+				config.body,
+				detectTerminalBackend(config),
+				shouldWrapForTmux(config),
+			);
 		}
 
 		if (config.channels.desktop) {

package/extensions/notify/notify.example.json

@@ -10,7 +10,8 @@
     "sound": false
   },
   "terminal": {
-    "backend": "auto"
+    "backend": "auto",
+    "tmuxPassthrough": "auto"
   },
   "desktop": {
     "backend": "auto"

package/extensions/notify/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-notify",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "A pi extension that sends a notification when the agent is ready for input.",
   "keywords": [
     "pi-package",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-extensions",
-  "version": "0.1.63",
+  "version": "0.1.64",
   "description": "A collection of pi extensions and skills for annotation UIs, context management, workflow audits, contrarian review, review-comment triage, notifications, brrr push alerts, safety guards, GitHub research, repo-local knowledge, todos, tool rendering, model/provider helpers, and Xiaohei-style article illustrations.",
   "keywords": [
     "pi-package",