@xzzpig/pi-terminal-notifications

@xzzpig/pi-terminal-notifications sends a desktop notification when Pi settles or needs input, and mirrors pending input to Herdr through herdr:blocked.

It observes three public cross-extension APIs:

• @eko24ive/pi-ask lifecycle events.
• @xzzpig/pi-permission-system UI prompt, direct decision, and forwarded decision events. Forwarded requests are correlated with the parent response by requestId.

The extension is observational. A notification or event listener failure never blocks Pi, a permission decision, or an agent loop.

Install

Install the published package:

pi install npm:@xzzpig/pi-terminal-notifications

From a checkout of this monorepo:

pi install ./packages/pi-terminal-notifications

From the Git monorepo, load only this extension:

{
  "packages": [
    {
      "source": "git:github.com/xzzpig/pi-extensions@main",
      "extensions": ["packages/pi-terminal-notifications/extensions/index.ts"]
    }
  ]
}

Notification Protocols

The extension emits exactly one notification sequence per event. It resolves TERM_PROGRAM against built-in mappings, then falls back to osc99 when the variable is unset or no mapping matches.

TERM_PROGRAM	Default protocol
ghostty	osc9
iTerm.app	osc9
WezTerm	osc9
kitty	osc99
vscode	osc99
WarpTerminal	osc777
missing or unknown	osc99

The defaults follow the documented notification protocols of iTerm2, WezTerm, Ghostty, and kitty. The VS Code and Warp mappings match the Herdr terminal notification profiles maintained in the accompanying NixOS configuration.

All payload text is stripped of terminal control characters, OSC separators, and excessive whitespace before it is written. This prevents application text from escaping the selected notification protocol.

Configuration

The optional global configuration file is:

~/.pi/agent/extensions/pi-terminal-notifications/config.json

Start from config/config.example.json. Its termPrograms object extends or overrides the built-in mappings; fallback changes the protocol used for an unknown terminal.

{
  "fallback": "osc99",
  "termPrograms": {
    "WezTerm": "osc777",
    "MyTerminal": "osc9"
  }
}

Valid protocol names are osc9, osc99, and osc777. Invalid, unreadable, or missing configuration safely uses the built-in defaults. The JSON schema is available at config/config.schema.json.

Permission And Herdr Lifecycle

A pi-ask or visible permission prompt marks Herdr as blocked. The state is cleared only after all active asks and prompts finish. For a direct permission ask, the local permissions:decision event resolves the prompt.

For a permission ask forwarded from a child session, the parent UI emits permissions:ui_prompt with a non-null forwarding context. After the parent successfully persists its response, pi-permission-system emits exactly one permissions:forwarded_decision with the same requestId; this extension uses that event to resolve the parent-side blocked state. The child later emits its own permissions:decision when its original gate consumes the response. The extension does not read private forwarding files, and session shutdown clears any remaining state.

Terminal control sequences are written only in Pi TUI mode. Herdr lifecycle state is still maintained in other modes.

Development

From the repository root:

pnpm --filter @xzzpig/pi-terminal-notifications run typecheck
pnpm --filter @xzzpig/pi-terminal-notifications test