Markdown plans don't scale.
html-planner does.

Ready for Claude Code, Cursor, Antigravity and any shell-capable agent

When your agent emits a thousand-line markdown plan, nobody reads it carefully — and that's exactly when careful review matters most. html-planner replaces the markdown wall with a live interactive page: approve steps, edit rules, comment inline, answer the agent's questions on the page itself.

npx html-planner@latest init .

See it live ↓

∅ external services
1 command to start
MIT open source

add-user-auth.md

◐ html-planner

What do you want to plan?

Shift+Enter for newline · Enter to submit

Try: Auth migration CSV export Rate limiting

🧠 Brainstorm ⟳ Ask questions ⎇ Diagrams ⌶ Code 🧪 Tests 💡 Tips

Depth:

Quick Standard Thorough

add-user-auth.md

Add user auth 6 steps

▾Architecture ✓

▾Backend 0/2

1 Create users table pending

2 Hash passwords with bcrypt pending

Rule Token strategy

algorithmHS256

expiry7d

▾Frontend 0/3

3 Build login form pending

4 Build signup form pending

💬 Add email verify step first

5 Wire auth API client pending

6 Guard private routes pending

? Where to store the JWT token?

The problem

Same plan. On the left you skim it. On the right you own it.

Approve each step individually. Reject with a reason. Leave an inline comment on any sentence. Edit a config value and save it. Answer a question your agent asked — all on the page, without switching context.

plain markdown plan

Loading…

html-planner page

Drag the divider to compare ↔

★ Live playground

Type markdown on the left. The interactive plan renders on the right — in real time.

Every interaction you make on the rendered side is real. Approve steps, edit rule cards, click around. This is the actual tool.

plan.md 0 lines

rendered plan 0 steps

What you get

Eight interactions that markdown can't do.

Approve / reject each step

Every ### Step N: … renders as a card with approve, reject, and effort sizing. The agent can't start until you've signed off.

Inline PR-style comments

Select any text in a step, click 💬 Comment, leave a note. Highlights persist; the agent reads them before continuing.

Editable rule cards

:::rule directives become form inputs — text, numbers, booleans. Tweak the values, click save, the agent reads your edits.

Live Mermaid diagrams

Drop a ```mermaid fence and get a rendered SVG — not ASCII art, not a screenshot. Architecture you can actually read.

Questions on the page

The agent never spams your chat. It writes questions.jsonl, the page renders interactive cards (radio / multi / text), the agent waits for your answer.

Single self-contained HTML

The output is one file. All CSS and JS inlined. Share it, archive it, send it to a non-technical stakeholder. Works offline.

Brainstorming sessions

Toggle 🧠 Brainstorm before planning. The agent asks clarifying questions, you answer on-page, and decisions accumulate in a sidebar — before the plan is even written.

Step alternatives

Don't just reject a step — propose a different approach. Click ⇄ Alternative, describe how you'd do it, and the agent rewrites that step while preserving the rest.

How it works

Three files. Two participants. One live page.

Agent and user pass messages through plain files in .html-planner/. No DB. No auth. Binds to 127.0.0.1 only.

1

Agent writes `plan.md`

Your AI agent emits a normal markdown plan to .html-planner/plan.md. The server watches the file and re-renders the page on every change.

2

You review in the browser

Approve, reject, comment, edit rules. Every action POSTs to edits.jsonl. Need clarification? Agent writes questions.jsonl, you answer on the page.

3

Agent executes

Click Start Creating. The agent reads edits.jsonl, respects your approvals, and streams progress back into the page's activity feed.

Works with any agent

If it can run a shell command, it can use html-planner.

Run html-planner init . in your project — it copies a SKILL.md into .claude/skills/ and merges the required permissions into .claude/settings.json. Then just type /html-planner in Claude Code.

npx html-planner@latest init .
claude   # then type /html-planner

Run html-planner init . — it installs a skill into .cursor/skills/. Then invoke /html-planner in Cursor's agent chat.

npx html-planner@latest init .
# Open Cursor → type /html-planner in the agent chat

Run html-planner init . — it installs a skill into .agents/skills/. Antigravity auto-discovers skills from that directory. Then invoke /html-planner in the chat.

npx html-planner@latest init .
# Open Antigravity IDE → type /html-planner

Windsurf supports custom workflows. Run init, then start the server via the embedded terminal. Add the same system-prompt block to your Windsurf rules.

npx html-planner@latest init .
nohup npx html-planner serve . --open &

For any chat-based AI agent (ChatGPT, Gemini, etc.) that can execute shell commands — run these two commands, then paste the system prompt into your chat session:

# 1. Set up the project
npx html-planner@latest init .

# 2. Start the server
npx html-planner@latest serve . --open

Then tell your agent:

When asked to plan a multi-step change, write the plan to
.html-planner/plan.md using markdown sections and steps.
To ask a question, append a JSON line to
.html-planner/questions.jsonl, then poll
.html-planner/answers.jsonl for a matching id.
Honor approve/reject decisions in .html-planner/edits.jsonl.

The server watches your files and live-reloads the browser. Your agent writes markdown, you review interactively — no agent-specific integration needed.

Watch the loop

Plan → review → build, in 45 seconds.

① Prompt ② Brainstorm ③ Review ④ Build

◐ html-planner

What do you want to plan?

🧠 Brainstorm ⟳ Ask me questions ⎇ Diagrams ⌶ Code Examples 🧪 Test plan 💡 Suggestions

Depth:

Quick Standard Thorough

🧠 Brainstorming

QUESTION

Should real-time notifications show a toast, or just update a bell counter?

Just a bell counter badge Both toast and bell counter Toast, bell counter, and email fallback

QUESTION

Should we persist these notifications in the database?

Persistent

Store in Postgres for history

Ephemeral

Keep in Redis memory only

Add real-time notifications 4 steps

▼ Architecture

Data Flow

▼ Implementation

1

WebSocket gateway

pending

2

Event publisher service

pending

3

React notification panel

pending

💬 "Add sound toggle setting"

4

E2E test suite

pending

▼ Suggestions

OPTIONAL Rate Limiting

Add basic rate limiting to WS connections to prevent abuse.

◐

Agent is building…

✓ Created WebSocket gateway

✓ Added event publisher

● Building notification panel…

Install

One command. No clone. No setup.

Zero install. Runs from the npm registry on demand.

npx html-planner@latest init .
npx html-planner@latest serve . --open

First run downloads the package (~200 KB). Subsequent runs are cached.

Requires Node ≥ 18. Works on macOS, Linux, and Windows (WSL).