Planboard

Review an agent's plan before you build it.

Planboard turns an existing Markdown plan into a local browser workspace with readable sections, interactive diagrams, anchored feedback, and revision history. Keep your planning method and your coding agent; use Planboard to understand the proposal, ask questions, and agree on the exact version to implement.

Quick start · Install for your agent · Review workflow · Architecture · Contributing

What you can do

Planboard opens only when explicitly requested. It does not run a planning hook on every prompt, impose a planning template, or replace your agent's existing workflow.

Related MCP server: Terrarium

Quick start

Use Node.js 24+. For Pi, install the package directly:

pi install npm:@koboimomo/planboard

Run /reload, then /planboard in your project. The package includes the extension and skill.

For Claude Code or Codex:

npm install -g @koboimomo/planboard

# Claude Code
planboard install-skill --agent claude
claude mcp add --scope user --transport stdio planboard -- planboard mcp

# Or Codex
planboard install-skill --agent codex
codex mcp add planboard -- planboard mcp

Restart the agent, then invoke /planboard in Claude Code or $planboard in Codex. Install only the integration you use. Installation, updates, and source setup.

Try the fictional demo

git clone https://github.com/lucapohl-angel/planboard.git
cd planboard
npm ci
npm run demo

Open the printed URL. The demo runs without an agent in a temporary project; Ctrl+C stops it. Feedback stays queued until an agent is attached.

Choose your agent

The browser, files, and review contract are shared. MCP hosts must keep a wait loop active to receive feedback; use a background agent when your host supports it. An idle MCP host cannot be assumed to wake automatically. Pi can deliver follow-ups to its owning session. See connection behavior and recovery.

The standard MCP workflow uses your chosen host agent. The optional fast Codex subprocess adapter is opt-in and has additional model requirements; it is not needed to use Planboard.

Draft → review → revise → approve

flowchart LR
  A[Your Markdown plan] --> B[Agent-authored review]
  B --> C[Browser questions and annotations]
  C --> D[Revised plan]
  D --> C
  D --> E[Approved Markdown and receipt]

1. Draft a plan using your preferred method. If it exists only in the conversation, the agent saves that public draft as Markdown first.

2. Invoke Planboard. The agent preserves the source and opens a readable review.

3. Explore the diagrams, ask questions, compare alternatives, or request changes. Notes retain their target and original revision.

4. Review the update. The viewer preserves active drafts and shows committed changes; failed requests remain retryable.

5. Approve the displayed revision when ready. The agent receives the approved file and asks separately whether to implement it.

Files stay with the project

Review records live under <project>/.pi/plans/ for compatibility, even when you use Claude Code or Codex. That directory contains revisions, feedback, the immutable original source, and the reviewed Markdown. Approval writes a versioned Markdown artifact and SHA-256 receipt. The legacy plan.md review export includes history; use the approved artifact for implementation.

The local server binds to loopback. Browser feedback sent to an agent follows that agent's provider policy. Do not expose the server as a public service. Security and data boundaries

Use it with Formative

Formative helps discover what an app needs through persistent interviewing and prototype checkpoints. Planboard helps review the resulting plan. You can use either on its own or bring Formative's written plan into Planboard; neither package imports or requires the other.

Development and limits

From a source checkout:

npm run test:unit
npx playwright install chromium
npm run test:browser
npm run check:release

Tests cover persistence, stale revisions, source preservation, MCP feedback/reconnection, browser interaction, and accessibility checks. Optional native Pi integration tests need an installed Pi runtime. CI is configured for Linux; macOS and Windows installation commands are provided but are not yet end-to-end tested. Protocol tests do not guarantee an agent's reasoning quality.

This is an early public release of a local single-user tool. Structural validation cannot prove that a plan is feasible, secure, or complete. Direct editing covers text fields, not arbitrary structural changes. Undo can be blocked by conflicting later edits. See usage and limits.

License: MIT. Third-party dependencies retain their own licenses. Public examples and screenshots are fictional.