planpage

Why

AI coding agents propose multi-step plans, review-gates, and reports, then often dump them as walls of terminal text. The work may be careful, but the reading experience is not: dense scrollback makes risks, choices, and next steps hard to absorb.

planpage turns that plan into a self-contained HTML page you open in the browser. One command gives the developer a calm, structured page for reading the plan properly — and, when needed, edit or annotate what is wrong, stage feedback in a fixed sidebar, then Send to Agent so the batch returns to the terminal.

Quick start

npx planpage render plan-brief --sample --open

That's it. One command renders a sample plan page and opens it in your browser. No install needed — npx handles it. Requires Node.js 18+.

Want the interactive menu instead?

npx planpage

Features

• Self-contained HTML — one file, works offline, nothing written to your repo
• Post-back server — opt-in: edit/annotate the plan, stage feedback in a sidebar, Send to Agent returns one JSON batch to your terminal
• 9 agent integrations — one init command wires planpage into Claude Code, Cursor, Codex, Windsurf, Kiro, Cline, GitHub Copilot, Amazon Q, and Roo Code
• 8 templates — plan-brief (flagship) · before-after · code-style-plan · question-poll · quiz · flashcards · audit-report · library
• 25 components — reader-first UI pieces: Callout · RiskList · Steps · Timeline · CodeBlock · DiffBlock · AnnotatedCode · CodeExplorer (IDE-style file tree) · Flow · QuestionCard · QuizCard · Flashcard · Scorecard · Storyboard · Carousel · Terminal · and more
• Real VS Code syntax colour — Shiki highlights TS/JS (and more) at render time using VS Code's own themes; colour is baked into the HTML, so it works offline with no client JS
• Programmable — use the CLI, or import render() (or renderHighlighted()) and compose Preact components directly in TypeScript
• Never hangs — the post-back server gracefully falls back when there's no TTY

Usage

CLI

planpage render <template> --data plan.json --open       # render to HTML and open
planpage render <template> --serve --decision out.json   # render + collect a decision
planpage serve page.html out.json                        # serve existing HTML, collect a decision
planpage library --open                                  # browse all components live
planpage new my-template                                 # scaffold a new template
planpage init                                            # wire planpage into your agents

Templates: plan-brief · before-after · code-style-plan · question-poll · quiz · flashcards · audit-report · library

Data flows in as JSON via --data <file> or piped stdin. Use --sample for built-in sample data.

Live mode

planpage live serves a sketch plan while you and the agent work on it. Comments you pin on a part reach the agent, the agent's cursor shows the part it changes, and edited pages refresh in the open tab.

planpage live --data plan.json --decision decision.json --open            # serve and wait
planpage live cursor --port <port> --token <token> --comment 1 --say "fixing the login box"

planpage live prints one JSON line on stdout: {"pageUrl","agentSocketUrl","port","token"}. Nothing else goes to stdout. The agentSocketUrl and token are for the agent only, so keep them out of chat and logs. --port (default 0, a free port) and --timeout (idle seconds, default 3600) are optional.

Exit codes for planpage live: 0 decision written (Approve) · 3 idle timeout · 2 error, including a plan file that cannot be rendered at start · 1 stopped by SIGINT or SIGTERM.

planpage live cursor exits 0 when the server accepts the cursor, 1 with the server's message when it refuses or cannot be reached, and 2 on bad usage (it needs --comment or --page).

Library

import { renderHighlighted, BeforeAfter } from "planpage";

const html = await renderHighlighted(
  <BeforeAfter
    title="Deslop pass"
    diffs={[{ file: "src/x.ts", before: "let x = 1", after: "const x = 1" }]}
  />,
);
// html is a complete document string with VS Code colour baked in — write it, open it, or serve it.
// Prefer the sync `render()` if you don't need syntax colour (it leaves a readable monochrome fallback).

Agent integration

The full agent skill ships in-repo at skills/planpage/ (SKILL.md + component catalog). Copy that folder into your agent's skills dir, or use the thin on-ramps:

npx planpage init                  # all supported agents
npx planpage init --agent cursor   # just one
npx planpage init --global         # user-wide (Claude)

| Agent | What init writes | |---|---| | Claude Code | .claude/skills/render-plan/SKILL.md | | Cursor | .cursor/rules/planpage.mdc | | Codex | delimited block in AGENTS.md | | Windsurf | .windsurf/rules/planpage.md | | Kiro | .kiro/steering/planpage.md | | Cline | .clinerules/planpage.md | | GitHub Copilot | .github/copilot-instructions.md | | Amazon Q | .amazonq/rules/planpage.md | | Roo Code | .roo/rules/planpage.md |

Each on-ramp tells the agent: shape your plan as JSON → render it through npx planpage → read the decision back. Idempotent — existing files are never clobbered unless you pass --force. For the full skill (templates, Storyboard, quiz/flashcards, decision contract), install skills/planpage/ into Claude / Grok / Codex skill roots.

How it works

data → render() → marked HTML → highlight() → coloured HTML → write/open  OR  serve → one feedback batch back

Static render is the default. The post-back server is opt-in and blocks until the user sends a feedback batch — then exits cleanly.

Sketch plans

Plans can be drawn as hand-sketched pages: one picture per page, short notes tied to their part, and a last "Your call" page with options A, B and C. sketch-plan is the default template for plans.

planpage render sketch-plan --data plan.json --out plan.html   # write the page
planpage serve plan.html decision.json --timeout 3600           # open it and wait for your pick
planpage recipes                                                # list the 80 sketch recipes

The decision file has approved, choice (the letter you picked) and notes. The style guide, the scene format and the recipe list are in skills/planpage/SKETCH-STYLE.md.

Use as a library

preact is a peer dependency, so your JSX and planpage share one Preact copy (two copies render a blank page). Install both:

npm install planpage preact

The CLI needs nothing extra: npx planpage installs preact for you.

Build locally

planpage is a Node.js package published on npm. Local development uses pnpm:

pnpm install
pnpm run verify
pnpm run cli -- render plan-brief --sample --open

Use pnpm run cli -- library --open to inspect the captured component gallery.

Scope

• Static-beautiful first. Pages read well with zero JS; interactivity is added only when asked for.
• Local HTML, not a hosted app. planpage renders a file — it's not a server framework.
• Not mcp-ui / MCP Apps. Those own the protocol lane; planpage is for local terminal skills.
• Not itself a skill. It's the rendering engine. planpage init wires it into your agent.

Docs

• AGENTS.md — conventions and validation commands for agents working in this repo
• PROJECT.md · CONTEXT.md · LANGUAGE.md

License

MIT