@clanker-code/pi-monitor

| | | |---|---| | npm | @clanker-code/pi-monitor — scope @clanker-code | | GitHub | clankercode/pi-monitor — org clankercode (no hyphen) |

Naming is intentional and easy to mix up: npm uses the hyphen (@clanker-code/…); this repo lives under GitHub clankercode (no hyphen).

A pi extension that watches background processes and delivers regex-matching stdout windows (with before/after context) into the agent session, plus background shell jobs that notify only on exit.

This is a partial pseudo-fork of pi-monitor-plugin by Walisson Casonatto (Shodocan). Upstream planned a broader jobs surface (background / monitor / loop / schedule). We ported the monitor tool and its core infrastructure, then rebuilt delivery, TUI, and agent integration for our direction. Upstream changes are reviewed when useful; we do not merge blindly.

Status: Working monitor + background extension. Not a drop-in replacement for the full planned upstream jobs suite (loop/schedule omitted).

Do not poll. Matching output and process exits are delivered automatically as steer messages. Exit notifications include exit code, last lines of output, and a path to the full process log.

Features

• Regex matching — only forward lines that match a pattern (default: match everything)
• Before/after context — deliver surrounding lines with each match
• Debouncing — batch nearby matches into a single delivery
• Background jobs — fire-and-forget shell commands (bg_*); no intermediate deliveries; notify on exit
• Exit notifications — every job end steers the agent with exit code, last lines, and full log path
• Full output logs — stdout/stderr tee'd to {tmpdir}/pi-monitor/{pid}/{jobID}.log
• No-poll contract — tool descriptions and start/exit messages tell agents not to poll
• triggerTurn (default on) — wake/steer the assistant when matching output arrives; set false for display-only logging (exits always wake)
• ReDoS protection — vet regex patterns before execution
• Nonce-fencing — untrusted output is fenced with cryptographic nonces
• XML envelope — delivered windows wrapped for LLM context (id + at; exits add event="exit")
• Secret redaction — best-effort scrubbing of tokens, keys, passwords
• ANSI stripping — remove terminal escape sequences from output
• Idle/busy routing — deliver immediately if idle; queue/invalidate safely across session lifecycle
• Same-turn batching — group monitor deliveries that fire together
• Interactive /monitor-list TUI — live tail, stop with confirm, keyboard nav
• AI-callable tools — Monitor, Background, MonitorStop, MonitorList

Fork divergences

This package intentionally diverges from upstream. Keep this table honest on every release.

| Feature | Status | Notes | |---------|--------|-------| | Package identity | ✅ shipped | npm: @clanker-code/pi-monitor (hyphenated scope). GitHub: clankercode/pi-monitor (no hyphen). | | Monitor + Background | ✅ shipped | Ported ProcessRunner, MonitorEngine, ReDoS, nonce-fencing, redaction, ANSI strip. Dropped loop/schedule. Reintroduced reduced Background tool (bg_*, exit-only). | | Working implementation | ✅ shipped | Upstream README describes a planning/scaffold jobs package; this repo is a usable extension. | | Exit notifications | ✅ shipped | Process exit always steers the agent with exit code, last ~8 lines, and full log path. Fixes silent disappear from list. | | Full output log path | ✅ shipped | Every job tees stream-tagged lines to a durable log file; path returned on start and exit. | | AI tools: stop + list | ✅ shipped | MonitorStop and MonitorList cover mon_* and bg_* (not only slash commands). | | triggerTurn + steer delivery | ✅ shipped | Default true for matches; exit always uses deliverAs: "steer" + triggerTurn: true. | | Same-turn delivery batching | ✅ shipped | Nearby/same-turn matches coalesce via MonitorDeliveryBatcher; invalidated on session shutdown. | | XML envelope for LLM context | ✅ shipped | Matches: <pi-monitor id at>; exits: event="exit" + body with path/lastLines. TUI strips envelope. | | Compact custom tool renderers | ✅ shipped | Tools use custom TUI renderers (renderShell: 'self'); statusline /m shows active job count. | | Interactive /monitor-list menu | ✅ shipped | Vertical frame, live tail (last 10 lines), details mode, confirm-or-force stop, left/right nav. | | Sensible agent-oriented defaults | ✅ shipped | Default regex matches all lines; before/after/debounceSeconds default to 0. | | Project/global settings | ✅ shipped | confirmStop in .pi/pi-monitor.json or ~/.pi/agent/pi-monitor.json (project overrides global). | | License | ✅ shipped | Unlicense / public domain; not MIT like upstream’s published LICENSE. | | No GitHub PR-watch skill | intentionally omitted | Upstream plans a gh-based PR watcher skill; out of scope here. | | Fork maintenance docs | ✅ shipped | AGENTS.md, CHANGELOG.md, RELEASE.md, tag-driven CI publish. |

Install

pi install npm:@clanker-code/pi-monitor

Local development:

pi install /path/to/pi-monitor
# or ad-hoc for one run:
pi -e ./extensions/pi-monitor.ts

Requires Node ≥ 22.19 and a recent pi coding agent.

Tools

Monitor

Run a shell command in the background and watch stdout for regex matches. Matching windows and process exit are delivered automatically — do not poll.

Monitor command="tail -f /var/log/app.log" regex="error|warn" before=5 after=3

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | command | yes | — | Shell command to run | | regex | no | match all | Regex pattern against each stdout line | | regexFlags | no | '' | RegExp flags | | before | no | 0 | Context lines before match (0–200) | | after | no | 0 | Context lines after match (0–200) | | debounceSeconds | no | 0 | Debounce window in seconds (0–60) | | label | no | — | Human-readable label | | triggerTurn | no | true | Wake/steer on match; false = display-only (exits always wake) |

Background

Run a shell command in the background with no intermediate deliveries (exit-only). Ids are bg_N. Full output is still written to a log file. Do not poll.

Background command="pnpm build" label="build"

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | command | yes | — | Shell command to run | | label | no | — | Human-readable label |

Exit notification

When any job ends (natural exit, crash, or stop), the agent receives a steer message with:

• exit code (and signal if the process was killed)
• last ~8 lines of process output
• path to the full output log ({tmpdir}/pi-monitor/{pid}/{jobID}.log)

MonitorStop

Stop a running job by id (mon_1 or bg_1). You will still receive the exit notification when the process actually terminates.

MonitorList

List all running monitors and background jobs (for inspection only — do not poll to wait for completion).

Commands

| Command | Description | |---------|-------------| | /monitor-stop <jobID> | Stop a running monitor or background job | | /monitor-list | Interactive menu: list jobs, view tail, stop |

There is no /monitor slash command — start jobs via the Monitor / Background tools.

/monitor-list menu

• Lists active jobs, newest first
• Detail pane shows the last 10 stdout lines (refreshes every 1s)
• Up/Down: navigate · Enter / s: stop (confirm if confirmStop) · x: stop without confirm · Left / Esc / q: back/close · Right: Enter-equivalent on list

Settings

Read from <cwd>/.pi/pi-monitor.json (project) or ~/.pi/agent/pi-monitor.json (global); project overrides global.

| Key | Type | Default | Description | |-----|------|---------|-------------| | confirmStop | boolean | true | Whether Enter/s asks for confirmation before stopping |

{ "confirmStop": false }

Security model

• Pi packages run with full system access — review the source before installing.
• Commands run in their own process group; stop is SIGTERM → grace → SIGKILL.
• Delivered process output is nonce-fenced, ANSI/control-stripped, and best-effort secret-redacted.
• Regex patterns are length-capped and ReDoS-vetted before a monitor starts.
• Full process logs on disk may contain secrets; treat log paths as sensitive.

Development

pnpm install
pnpm test
pnpm check

Changelog: CHANGELOG.md. Release process: RELEASE.md.

Upstream

• Original design and research: Shodocan/pi-monitor-plugin (successor ideas also relate to opencode-monitor-plugin).
• We credit Walisson Casonatto for the monitor architecture (ProcessRunner, MonitorEngine, ReDoS worker, delivery hygiene). Divergences above are ours.

License

Unlicense (public domain).