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, Approve or Adjust sends a decision straight back to the agent.
npx planpage render plan-brief --sample --openThat'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- Self-contained HTML — one file, works offline, nothing written to your repo
- Post-back server — opt-in: the page collects an Approve/Adjust decision and returns it as JSON to your agent
- 9 agent integrations — one
initcommand wires planpage into Claude Code, Cursor, Codex, Windsurf, Kiro, Cline, GitHub Copilot, Amazon Q, and Roo Code - 5 templates — plan-brief (flagship) · before-after diffs · code-style-plan · question-poll (interactive quiz with Mermaid diagrams) · library
- 17 components — reader-first UI pieces: Callout · RiskList · Steps · Timeline · CodeBlock · DiffBlock · AnnotatedCode · CodeExplorer (IDE-style file tree) · Flow · QuestionCard · 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()(orrenderHighlighted()) and compose Preact components directly in TypeScript - Never hangs — the post-back server gracefully falls back when there's no TTY
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 agentsTemplates: plan-brief · before-after · code-style-plan · question-poll · library
Data flows in as JSON via --data <file> or piped stdin. Use --sample for built-in sample data.
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).planpage is a package — not itself a skill. One command wires it into whatever agent you use:
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.
data → render() → marked HTML → highlight() → coloured HTML → write/open OR serve → one decision back
Static render is the default. The post-back server is opt-in and blocks until one decision arrives — then exits cleanly.
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 --openUse pnpm run cli -- library --open to inspect the captured component gallery. For code conventions and extension points, read CODE-STYLE.md before adding templates, components, or CLI commands.
- 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 initwires it into your agent.
- AGENTS.md — conventions and validation commands for agents working in this repo
- PROJECT.md · CONTEXT.md · LANGUAGE.md · CODE-STYLE.md
- docs/adr/ — architecture decisions
MIT