pi-monitor — live Pi agent monitor

A Pi package that tracks running Pi agents and provides a small CLI for seeing what each one is doing. If an agent was launched inside tmux, the watch UI can jump directly to its pane.

pi install npm:@lukemelnik/pi-monitor

Features

• Live agent registry — each running Pi instance writes a heartbeat with status, cwd, model, session, and active tool info.
• Interactive monitor — pi-monitor --watch shows live agents and updates once per second.
• Native Pi view — /pi-monitor opens the same live monitor inside Pi.
• Tmux pane jump — press Enter on an agent launched inside tmux to switch to that pane.
• Context usage — shows current context consumption as a compact bar when Pi exposes usage data.
• Optional recap integration — shows session recap markers when pi-session-recap is installed.
• Stale cleanup — dead processes and old heartbeat files are pruned automatically.

Install

Install from npm:

pi install npm:@lukemelnik/pi-monitor

For local development or testing:

pi install /absolute/path/to/pi-monitor

The package includes both the Pi extension and the pi-monitor CLI. A global Pi npm install links the CLI so it can be run directly from your shell.

Usage

Open the monitor inside Pi:

/pi-monitor

Print a one-shot table:

pi-monitor

Open the interactive watcher:

pi-monitor --watch

Keys in watch mode and the native Pi view:

| Key | Action | |-----|--------| | j / ↓ | Move down | | k / ↑ | Move up | | Enter | Jump to the selected tmux pane, if available | | q / Esc / Ctrl-C | Exit |

Other options:

pi-monitor --version
pi-monitor --help
pi-monitor --ttl-ms 60000
pi-monitor --no-color

How it works

The Pi extension runs inside each Pi process and writes one small heartbeat file per live instance:

~/.pi/agent/monitor/live/<pid>-<instanceId>.json

The file is overwritten in place every few seconds. Normal shutdown removes it. If Pi crashes, later monitor runs prune stale files and dead PIDs.

The CLI is separate from Pi at runtime. It reads the heartbeat directory, renders the table, and uses tmux only for the optional pane jump action.

Context usage

When available, context usage is shown in the table and inspector:

CTX  ████░░░░░ 44%

Right after startup, reload, or compaction, Pi may not know token usage yet. In that case the monitor shows — until usage data is available again.

Optional recap integration

If @lukemelnik/pi-session-recap is installed, pi-monitor reads its saved session recap entries and shows a • marker plus the recap in the inspector.

pi install npm:@lukemelnik/pi-session-recap

This is optional. Pi-monitor still works without the recap package.

Development

npm run check

Release commands:

npm run release:patch
npm run release:minor
npm run release:major
npm run publish:release

npm version updates package.json, updates package-lock.json when present, creates a release commit, and creates a vX.Y.Z git tag.

License

MIT