Why

Planning a feature with an AI agent means a stream of decisions: pick a language, choose an approach, confirm a scope.

In a terminal or chat those arrive as awkward numbered lists ("reply 1, 2, or 3…") or a wall of free text — easy to fat-finger the wrong option, easy to lose track of what you already answered.

How

browser-plan hands those questions to a real browser form — text boxes, radio buttons, checkboxes, sliders. Every choice laid out, no way to misfire, and you answer at the pace of a form rather than a chat prompt.

It's an MCP server, so the same planning surface works across every harness — Claude Code, Cursor, Claude Desktop, Codex, and more.

And it persists the whole planning arc — every question, every answer, every version of the plan — so you can replay how a decision was reached later.

⚠️ Non-sensitive input only. This UI is for preferences, creative answers, and choices. Never use it to collect passwords, API keys, tokens, or payment data.

Usage

npx browser-plan

Add it to your harness

One command:

claude mcp add browser-plan -- npx -y browser-plan

Or as JSON in .mcp.json (project, committed) or ~/.claude.json (user scope):

{
  "mcpServers": {
    "browser-plan": { "command": "npx", "args": ["-y", "browser-plan"] }
  }
}

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "browser-plan": { "command": "npx", "args": ["-y", "browser-plan"] }
  }
}

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "browser-plan": { "command": "npx", "args": ["-y", "browser-plan"] }
  }
}

.vscode/mcp.json — note the key is servers (not mcpServers) and the "type": "stdio":

{
  "servers": {
    "browser-plan": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "browser-plan"]
    }
  }
}

~/.codex/config.toml — TOML, with a [mcp_servers.<name>] section:

[mcp_servers.browser-plan]
command = "npx"
args = ["-y", "browser-plan"]

Replay a session: browser-plan retro

The same package ships a read-only viewer that browses everything browser-plan has saved — per session, the questions asked, the answers given, and every plan version:

npx browser-plan retro

It serves on http://127.0.0.1:4317 (override with the PORT env var) and only ever reads your data — it never opens the form or changes a session.

/browser-plan skill

The MCP server still has to be installed (see above) — the skill doesn't ship it. It just steers the harness to ask its questions through browser-plan instead of its default prompts.

Installation via skills.sh

npx skills add ramybenaroya/browser-plan

Usage

/browser-plan refactor codebase from zig to rust

Tools

Under the hood the server exposes three tools. A session id threads a questioning-and-planning arc together: mint it once, then pass it to every ask and save.

| Tool | What it does | |------|--------------| | init_browser_plan_session | Mints a session id and creates the session on disk. Call once at the start. No browser. | | ask_user | Opens the browser form, asks one or more questions, returns the answers. Persists them under the session. | | save_plan | Saves the plan (Markdown) as a new version under the session — history is kept. No browser. |

Flow: call init_browser_plan_session once → pass its sessionId to every ask_user round and every save_plan. Each save_plan writes a new version, so the plan's full evolution is preserved.

Full input schemas, the question kinds (text, longtext, single, multi, scale), Markdown/diagram support, storage layout, and architecture are in ARCHITECTURE.md.

Requirements & security

• Node.js 18+, and any MCP client.
• The callback server binds 127.0.0.1 only, on an ephemeral port; answers are POSTed only there, never through the agent.
• The UI sets no cookies and stores nothing sensitive — only a theme preference in localStorage.
• Don't collect secrets (see the warning above).

More detail in ARCHITECTURE.md.

License

Released under the MIT License — © 2026 Ramy Ben Aroya.