@alexgorbatchev/pi-cmux-notify

pi package for cmux notifications.

Why

Pi already knows what happened during a run. @alexgorbatchev/pi-cmux-notify turns that into terminal-native cmux notify alerts so you can notice when Pi is waiting, completed work, or ended in error.

Usage

Install with Pi:

pi install npm:@alexgorbatchev/pi-cmux-notify

If Pi is already running, reload extensions:

/reload

Included extension

• cmux-notify — sends cmux notify alerts when Pi finishes a run

Notification behavior

All notifications use:

• title: Pi by default
• subtitle: current run state
• body: a short summary of what Pi just did

Current notification types:

• Waiting

  • sent when Pi finishes a short run and is waiting for input
  • typical bodies:
    • Finished and waiting for input
    • Reviewed README.md
    • Reviewed 3 files
    • Searched the codebase

• Task Complete

  • sent when the run changed files, or when the run took at least the configured threshold
  • typical bodies:
    • Updated package.json
    • Updated 2 files
    • Finished in 42s
    • Updated 3 files in 1m 12s

• Error

  • sent when the run itself ends in error or abort
  • typical bodies:
    • read failed for config.json
    • edit failed for README.md
    • bash command failed

Notification bodies are summarized from the run itself:

• changed files from edit and write
• reviewed files from read
• searches from grep and find
• shell activity from bash
• the final agent error, with the first tool failure used as a fallback summary when needed

Settings

Configure notifications in Pi settings instead of environment variables.

Global settings live in ~/.pi/agent/settings.json. Project settings live in .pi/settings.json and override global settings.

Use this package-scoped key:

{
  "@alexgorbatchev/pi-cmux-notify": {
    "level": "all",
    "thresholdMs": 15000,
    "debounceMs": 3000,
    "title": "Pi"
  }
}

Supported fields:

• level — all, medium, low, or disabled (default: all)
• thresholdMs — duration threshold before a run is labeled Task Complete instead of Waiting (default: 15000)
• debounceMs — minimum delay between duplicate notifications (default: 3000)
• title — notification title override (default: Pi)

cmux must be available in PATH for notifications to work. Pi uses the current CMUX_WORKSPACE_ID / CMUX_SURFACE_ID automatically when cmux is running.