pi-event-monitor

Event-driven monitors for pi sessions. pi-event-monitor lets pi watch shell output or file changes in the background and wake the same session that started the monitor only when something happens.

Inspired by Claude Code's Monitor mechanic: stdout lines become events; silence costs no model calls.

What it does

• Runs selective shell monitors in the background.
• Watches files or directories for changes.
• Injects matching events into the current pi session so the agent can react.
• Shows active monitors in the status line and a /monitors details panel.
• Stops monitors automatically when the session switches, forks, reloads, or exits.

Requirements

• pi coding agent installed.
• Node.js compatible with your pi installation.
• Optional shell utilities for your own monitor commands, e.g. grep, tail, fswatch, inotifywait, gh.

Installation

From npm, once published

pi install npm:pi-event-monitor

From git

pi install git:github.com/Helmi/pi-event-monitor

Pin a release tag for reproducible installs:

pi install git:github.com/Helmi/[email protected]

From a local checkout

git clone https://github.com/Helmi/pi-event-monitor.git
pi install ./pi-event-monitor

Try without installing

pi -e ./pi-event-monitor

After installing into an already-running pi session, run:

/reload

or start a new pi session.

Quick start

Ask pi naturally:

Start my dev server and monitor it for errors

Or use explicit commands:

/monitor app errors :: tail -f app.log | grep --line-buffered -E "ERROR|WARN|FATAL"
/monitor-watch src changes in src
/monitors

Commands

/monitor <description> :: <command>

Start a persistent shell monitor. The command runs in your project directory. Every stdout line becomes a monitor event.

/monitor-watch <path> [description]

Watch a file or directory using Node fs.watch.

/monitors
/monitor-panel

Open the monitor details panel.

/monitor-stop <id|all>

Stop one monitor or all active monitors.

Tools available to the agent

• monitor_start — run a shell command in the background; stdout lines wake the session.
• monitor_watch_path — watch a file or directory.
• monitor_list — list running/stopped monitors.
• monitor_stop — stop one monitor or all monitors.

Monitor panel

/monitors opens a bordered overlay styled with your current pi theme.

Keyboard controls:

| Key | Action | | --- | --- | | ↑ / ↓ | Select monitor | | a | Toggle active-only / all monitors | | s | Stop selected monitor | | q / Esc | Close panel |

The panel shows:

• active and total monitor counts
• monitor id, status, kind, age, wakeup count
• command or watched path
• rate-limit window
• stderr temp file path for shell monitors
• recent monitor events

Examples

Watch application logs

/monitor app errors :: tail -f app.log | grep --line-buffered -E "ERROR|WARN|FATAL"

Monitor a dev server

/monitor dev errors :: npm run dev 2>&1 | grep --line-buffered -i "error\|failed\|exception"

Watch test failures

/monitor test failures :: npm test 2>&1 | grep --line-buffered -E "FAIL|failed|Error:"

Watch a source directory

/monitor-watch src changes in src

Poll GitHub comments without waking on every poll

/monitor pr comments :: while true; do gh api repos/OWNER/REPO/issues/123/comments --jq '.[] | "\(.user.login): \(.body)"' || true; sleep 30; done

For real use, make poll loops stateful so they only print new items.

Writing good monitors

Monitors are event streams. Every stdout line can become model context, so keep output selective.

Good:

tail -f app.log | grep --line-buffered -E "ERROR|WARN|FATAL"

Bad:

tail -f app.log

Guidelines:

• Use grep --line-buffered in pipelines so events arrive immediately.
• Filter aggressively; do not stream raw high-volume logs.
• Add || true inside polling loops so one transient failure does not kill the monitor.
• Use 30s+ polling intervals for remote APIs.
• Avoid commands that print secrets.

Security model

Shell monitors run arbitrary commands with the same OS permissions as pi. Treat monitor_start like bash plus a background lifetime.

Safety defaults:

• Interactive monitor_start tool calls and /monitor commands ask for confirmation before spawning a shell monitor.
• Headless shell monitors are blocked by default.
• To allow shell monitors in trusted headless automation, set:

PI_MONITOR_ALLOW_HEADLESS_SHELL=1

Output handling:

• Monitor stdout is injected into the session and may be sent to the active model.
• Monitor output is quoted and labeled as untrusted external data to reduce prompt-injection risk.
• Individual stdout lines, batches, and unterminated lines are capped.
• Stderr is not injected into the session. It is written to a private temp file capped at 1 MB for debugging.

Lifecycle and limits

• Monitors are in-memory and session-owned.
• Switching, forking, reloading, or quitting the session stops monitors and suppresses pending wakeups.
• Events arriving within 200 ms are batched into one wakeup.
• Shell monitors default to 60 stdout lines/minute.
• Path watchers default to 120 events/minute.
• Exceeding the rate limit stops the monitor.
• Shell monitor stderr is capped at 1 MB.

Development

Run checks:

npm test
npm run pi:load-check
npm run pack:dry

Try the package locally:

pi -e .

The smoke test checks syntax, pi package metadata, package dry-run, and avoids optional runtime imports that can break across pi package namespaces.

Release process

This package uses SemVer. See RELEASE.md for the release checklist, version policy, and publishing steps.

Short version:

npm test
npm run pi:load-check
npm run pack:dry
npm version patch   # or minor / major
npm publish --access public

Package manifest

pi-event-monitor is a normal pi package. package.json declares:

{
  "keywords": ["pi-package"],
  "pi": { "extensions": ["./extensions"] }
}

License

MIT