User guide

This guide covers the board as a whole. For installation, see Getting started. Each feature has its own page:

• Terminal and sessions: run pi in the board, start, resume, find, and group sessions.
• Show and ask: cards from the agent, and questions it waits on.
• Review: comment on a doc and send the comments to pi.
• Panes and docs: files and pages as tabs next to the board.
• Dispatch: hand a task to a new pi session.
• Navigation and zen: the keyboard, and zen mode for one session or one group.
• Companions: pi-cost, pi-inspect, and the other pi packages the board reads.

Start the board

Install the board command once with npm install -g pi-kanban, then run the server in a shell:

pi-kanban

It prints pi-kanban running at http://localhost:3460 and the board URL with its access token.

Flag	Env var	What it does
--port <n>	PORT	Port. Default 3460. When the port is taken, the server picks a free one.
--open		Open the board in the browser
--dir <path>	PI_CODING_AGENT_DIR	pi agent dir. Default ~/.pi/agent.
--session-dir <dir>	PI_CODING_AGENT_SESSION_DIR	pi session dir. When neither is set, the board reads sessionDir from pi’s settings.json and from each project’s .pi/settings.json.
--no-terminal		Turn off the board terminal
--new-token		Replace the saved terminal token. Open board tabs need the new URL.
--terminal-shell <shell>	PK_TERMINAL_SHELL	gitbash, a program on PATH, or a path
--host <addr>	HOST	Listen address. Default 127.0.0.1.
--allowed-hosts <list>	ALLOWED_HOSTS	Extra Host header values, comma-separated

A flag wins over its env var. The pi-kanban command also talks to a running board: see the CLI reference.

The /kanban command

Run these inside pi. The session commands use the current session when you leave out <id>. /kanban open is for pi started in another terminal: a pi in the board terminal is already on the board.

Command	What it does
/kanban or /kanban open	Open the board in the browser, with the access token
/kanban session open [<id>]	Open a session on the board
/kanban session pin [<id>]	Pin a session
/kanban session sticky-pin [<id>]	Sticky-pin a session
/kanban session unpin [<id>]	Remove a pin
/kanban session view-doc <file> [<id>]	Open a file in the board preview
/kanban session link-doc <file> [<id>]	Link a file to a session
/kanban cost [<id>]	Open pi-cost for a session as a pane. In the board terminal, the board shows it at once.
/kanban inspect [<id>]	Open pi-inspect for a session as a pane, the same way

Layout

• Sidebar. Sessions in groups and projects. Each card shows progress, context use, age, pins, linked docs, and icons for a terminal, a dispatched session, or a question that waits for you. The pills at the top count the sessions that wait, the active sessions, and the open terminals.
• Board. Pending, In Progress, and Completed columns for the selected session, from @juicesharp/rpiv-todo. Tabs next to Board hold panes and show cards.
• Agents log. The subagents of the session, with model, status, and run time.
• Session log. Every prompt, reply, and tool call. Ctrl+Shift+L opens it, and Ctrl+Shift+M opens the last message.

Subagents

When pi-subagents starts a child session, the board lists it in the agents log of its parent. Open one to read its prompt and its response, rendered as markdown.

Tool stats

Session info has a button that counts the tool calls of the session, with the failures of each tool and its share of the context.

Notes and storage

N opens notes for the session. The board keeps them in your browser, with pins, groups, and linked docs. Shift+S opens the storage manager, which shows what the board keeps for each session and clears it.

Board messages to pi

When you send review comments from the board, answer a card, or move a task, the board delivers it to pi as a user message. When pi is busy, the message waits until the current turn ends.

Install as an app

The board is a progressive web app. Install it from the browser menu to give it its own window.

Close