pi-monitor

A local, live CLI and TUI monitor for the Pi coding agent. It listens to the global Pi activity-reporter extension and renders what Pi is doing without replacing Pi's normal interactive interface.

The interactive dashboard monitors multiple Pi sessions, shows running tools, keeps a per-session timeline, tracks cumulative input/output tokens and the active model's context-window size, and aggregates tool activity:

 pi-monitor  ● 2 connected  3 sessions  2 working
──────────────────────────────────────────────────────────────────────────────
 SESSIONS                    RECENT EVENTS · FOLLOW        CURRENT ACTIVITY
 > ● pi-monitor  12.4s       03:50:09 ↳ EDIT  Editing…     Tokens: ↑123.5k ↓8.2k · ctx 200k
   ○ Bagsy  IDLE             03:50:08 ✓ READ  Completed…   WORKING · 12.4s
   ● website  4.1s           03:50:04 ↳ READ  Reading…     Tools: 8/9
──────────────────────────────────────────────────────────────────────────────
 ↑↓/jk move  tab panel  space pause  f follow  ? help  q quit

The line-oriented watcher remains available for scripts and log-oriented use:

03:49:48  ○ SESSION  [my-project] Pi session started
03:50:02  ? PROMPT   [my-project] Asked Pi: Refactor the authentication service
03:50:02  ● WORK     [my-project] Pi started working
03:50:04  ↳ READ     [my-project] Reading src/AuthService.ts
03:50:05  ✓ READ     [my-project] Completed read · 84ms
03:50:08  ↳ EDIT     [my-project] Editing src/AuthService.ts
03:50:09  ✓ EDIT     [my-project] Completed edit · 112ms
03:50:12  ✓ DONE     [my-project] Pi finished working · 10.2s

Requirements

• Node.js 22.19 or newer
• The global Pi activity-reporter extension at ~/.pi/agent/extensions/activity-reporter/

The extension sends versioned JSONL activity over a user-specific local socket. It reports cumulative input, output, cache-read, and cache-write token counts along with the active model's configured context-window size, without sending message contents. Exact tool inputs and results are hidden by default; set PI_ACTIVITY_INCLUDE_TOOL_IO=1 in Pi's environment to publish them. This can expose file contents, commands, credentials, and other sensitive data. Shell-command previews are hidden unless explicitly enabled in the extension environment.

Install from this checkout

npm install
npm run build
npm link

This installs the pi-monitor command using a symlink to the checkout.

Usage

Open the interactive dashboard before or after Pi:

pi-monitor tui

pi-monitor dashboard is an alias. The extension reconnects automatically, so already-running Pi sessions will begin reporting once the monitor is available. The dashboard uses these keys:

↑/↓ or j/k   Select a session or scroll its timeline
Tab          Switch between sessions and timeline
d            Remove the selected stopped session from the dashboard
Space        Pause/resume visual updates (events continue buffering)
f            Follow the newest event
?            Show help
q            Quit

Removing a stopped session only dismisses it from the current dashboard; it does not delete Pi's session file.

For the existing line-oriented stream, run:

pi-monitor
# or: pi-monitor watch

Filter to one project

The selected directory and nested working directories are included:

pi-monitor --project .

Machine-readable JSONL

pi-monitor --json

JSON mode validates each event against activity protocol version 1 before writing it to stdout. Monitor diagnostics remain on stderr. When exact tool I/O is enabled in the reporter, tool.started.data.input contains the call arguments and tool.completed.data contains both input and output. JSON mode preserves them exactly. The human-readable watch view shows compact representations fitted to the terminal width; the TUI shows only the tool event summary and never renders exact call arguments or results.

Options

Commands:
  watch             Stream line-oriented activity (default)
  tui               Open the interactive activity dashboard

Options:
  --socket <path>   Override the activity socket
  --project <path>  Show only activity under this project directory
  --json            Emit validated JSONL (watch only)
  --no-color        Disable ANSI colors
  -h, --help        Show help
  -v, --version     Show version

The default socket is /tmp/pi-activity-<uid>.sock. Both the monitor and Pi extension honor PI_ACTIVITY_SOCKET.

To monitor exact tool calls and their output, start Pi with:

PI_ACTIVITY_INCLUDE_TOOL_IO=1 pi

Use pi-monitor --json when the complete, untruncated values are required.

Safety and lifecycle

• The socket is created with mode 0600.
• A second monitor refuses to replace an active monitor's socket.
• A stale socket is detected and removed.
• A non-socket filesystem path is never removed.
• SIGINT and SIGTERM close clients and remove the owned socket.
• Malformed, oversized, and unsupported-version events are ignored with a warning.

Development

npm run check
npm test
npm run build

The dashboard uses @earendil-works/pi-tui for differential terminal rendering. Tests use Node's test runner via tsx.