@arvoretech/pi-monitor

Watch a long-running background process and push each matching output line to the agent as a notification — no polling. Inspired by Claude Code's Monitor tool, with stderr + exit-code capture and flood protection on top.

How it works

monitor_start → spawn(command, shell) → readline(stdout/stderr)
                        │
              line matches include/exclude filter
                        │
        pi.sendUserMessage(line, { deliverAs: "steer" })  → agent reacts mid-conversation

The agent keeps working and is interrupted only when a matching line arrives. Monitors are session-scoped and are killed on session_shutdown.

Tools

• monitor_start — start a background monitor. Params: id, command, cwd?, include? (regex), exclude? (regex), captureStderr? (default true), reportExit? (default true), deliverAs? (steer | followUp, default steer), maxEventsPerWindow? (default 40 / 60s).
• monitor_stop — stop by id, or all: true.
• monitor_list — list running monitors with uptime and event counts.

Command

• /monitors — abre o painel de logs (monitores ativos + eventos recentes). Esc fecha.

Footer

Enquanto houver monitores rodando, um item aparece no rodapé (1 monitor ativo · /monitors p/ logs). Ele some sozinho quando o último monitor termina, e pode ser escondido pela extensão widget-wrangler (/wrangle).

Notes vs Claude Code Monitor

• Captures stderr and exit code (Claude's forwards stdout only, so silent failures look healthy).
• Filter is applied in-process via include/exclude regex to avoid flooding context.
• Flood guard: a monitor emitting more than maxEventsPerWindow matching lines per 60s window auto-stops and tells the agent to restart with a tighter filter.
• Pipe-buffering caveat still applies to your command: use grep --line-buffered when filtering upstream.

Usage

Add to .pi/settings.json:

{ "packages": ["npm:@arvoretech/pi-monitor"] }

Then ask in natural language:

Run docker compose up --build in the background and tell me the moment any line contains "error" or when a service reports "healthy".