Pi Agent Board

Pi Agent Board is a full-screen TUI dashboard for Pi. It lets you dispatch, monitor, peek/reply to, attach to, and clean up multiple background Pi sessions from one place.

Problems It Solves

• Run several Pi tasks at once without losing track of which are queued, running, waiting for input, in progress, done, failed, or stopped.
• Keep real Pi sessions durable and resumable after /reload, closing Pi, or restarting the terminal.
• Check the latest output and answer follow-up questions without interrupting a running session.
• Attach to the full interactive Pi session only when hands-on work is needed.
• Manage work across multiple projects in one global board.

Install

From npm:

pi install npm:pi-agent-board
pi /agent-board

You can also start Pi normally and run /agent-board.

Pi Agent Board requires Node 20+ and working Pi provider auth. If rows stay in Running, first confirm Pi can complete a one-shot model call:

pi --mode json -p --no-session "Reply with exactly: DONE"

That command should produce an assistant reply and finish with an agent_end event.

From a local checkout:

npm install
pi install "$(pwd)"
pi /agent-board

For auto-discovery while developing:

ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
pi

Remove that symlink when you no longer want Pi to auto-load the checkout. If you installed by path, remove it with pi remove "$(pwd)".

Use

Open the board with pi /agent-board or /agent-board inside Pi.

• Type a task in the bottom input, then press enter.
• Confirm Start session, or adjust cwd, model, and thinking level first.
• Watch rows move through Queued, Running, Needs input, In Progress, Done, Failed, and Stopped.
• Press space to peek at the selected row's summary, blocker, and latest output.
• Press r to reply inline without attaching.
• Press enter, right, or > to attach to the real Pi session.
• Press v for a read-only live transcript.
• Press / to filter by text or state, such as s:running.
• Press ctrl+r rename, ctrl+t pin, ctrl+s stop, d mark done, m multi-select, ctrl+x delete/archive, X delete inactive rows in the selected state, and ? for help.

Rows are stored under ~/.pi/agent/agent-board/ by default. Deleting a row archives it from the board; it does not remove the underlying Pi session file.

Configuration

Useful environment variables:

Variable	Use
AGENT_BOARD_ROOT	Store location. Defaults to ~/.pi/agent/agent-board/.
AGENT_BOARD_AUTO_STATE=off	Disable automatic terminal-state moves.
AGENT_BOARD_AUTO_STATE_MODEL=<model>	Model for classifying finished turns. Defaults to gpt-4o; use off for heuristic-only.
AGENT_BOARD_SUMMARY_MODEL=<model>	Model for short row summaries. Defaults to gpt-4o; use off to disable.
AGENT_BOARD_TITLE_MODEL=<model>	Model for generated session titles. Defaults to openai-codex/gpt-5.5; use off to disable.
AGENT_BOARD_TITLE_THINKING_LEVEL=<level>	Thinking level for title generation. Defaults to low; use off to omit it.
AGENT_BOARD_DISABLE_PTY=1	Disable PTY attach mode.
AGENT_BOARD_FORCE_PTY=1	Force PTY attach mode.
AGENT_BOARD_ATTACH_MOUSE=0	Disable attach-view mouse handling and use terminal-native selection.
AGENT_BOARD_WHEEL_LINES=<1-50>	Lines scrolled per mouse-wheel event in attach view. Defaults to 1.

Legacy AGENT_VIEW_* variables are still honored for migration.

If the board reports node-pty unavailable, press ! in the dashboard for diagnosis and fix steps.

Develop

npm install
npm run typecheck
npm test
npm run pack:dry

Run all checks with:

npm run verify

npm run verify runs typecheck, tests, and a dry npm pack.

Publish

Before publishing a new release, bump the package version, run verification, then publish:

npm run verify
npm version patch
npm publish

If the version is already bumped, skip npm version patch.

Use npm version minor or npm version major instead when the release warrants it. After publish, users install with:

pi install npm:pi-agent-board

The Pi package gallery uses the pi.video and pi.image URLs from package.json.