Visual Plans

Most people install Plan as a skill, not a scaffolded app. One CLI command adds the /visual-plan, /visual-recap, and /visualize-repo skills plus the hosted Plan connector to your coding agent — see Plan plugin & marketplace for the plugin and marketplace routes. Forking the Plan template (covered under Extending Plan) is the secondary path, for self-hosting or building on Plan itself.

Agent-Native Plans is visual plan mode for coding agents. It turns an ordinary Codex, Claude Code, Markdown, or pasted implementation plan into a structured review surface with rich text, diagrams, wireframes, annotated code walkthroughs and file trees, annotations, comments, and shareable links.

It comes down to two commands. /visual-plan builds a plan before the agent writes code. /visual-recap turns a change that already happened — a PR, commit, branch, or git diff — into a high-altitude visual code review. Both open the same review surface, so you annotate, comment, and hand feedback back to the agent the same way.

Two commands, one review surface
/visual-planbefore code — architecture, UI, refactor
/visual-recapafter code — PR, commit, branch, diff
Plan MCP connector
plan.agent-native.com
Review surface
diagrams · wireframes · annotated code · comments
Coding agent
feedback handed back

Both commands publish through the hosted Plan MCP connector into the same annotate-and-comment surface.

Checkout redesign plan

Current wireframe
Proposed wireframe
Implementation plan
Decision: keep existing checkout shell
Annotated code walkthrough
Open questions

There are two ways into Plans:

  • From your coding agent (CLI) — one command installs the skill, registers the hosted Plans connector, and authenticates it.
  • In the browser — anyone you share with can open the editor and create or edit as a guest, with no sign-up. They sign in only when they want to save or share.

Install the skill

Use the Agent-Native CLI. This installs the Plans skill instructions, registers the hosted Plans MCP connector, and runs the client-specific auth flow in one step, so your first tool call does not hit an OAuth wall:

npx @agent-native/core@latest skills add visual-plan

The command installs three commands — /visual-plan, /visual-recap, and /visualize-repo — plus the plan MCP connector at https://plan.agent-native.com/mcp. Authentication is a one-time browser sign-in at setup; this is intended, and it is what lets the agent persist and share the plans it generates.

For the full flag reference (--client, --mode, --mcp-url, --no-connect, --with-github-action), the plugin/marketplace install routes for Claude Code and Codex, and the bare-instructions fallback, see Plan plugin & marketplace → Install routes. To auto-generate a recap on every pull request, that same page's --with-github-action flag writes the GitHub Action described in PR Visual Recap.

Prefer a one-install plugin? Claude Code and Codex can add BuilderIO/agent-native directly as a plugin marketplace, which bundles the Plan skills and the connector in one install and auto-updates as the skills improve — see Plan plugin & marketplace.

Open Plans inside VS Code

If you live in VS Code, install the Agent-Native Plans extension to open the same Plan review surface in a side panel instead of a separate browser tab. The extension handles the vscode://builder.agent-native/open handoff URL that Plan tools return alongside the normal web link, and it includes a command to run the Agent Native MCP connect flow for VS Code / GitHub Copilot.

Use it from your coding agent

After installation, ask your agent for the command that fits the work:

  • /visual-plan creates a structured plan before implementation — for architecture, backend, refactor, UI, or mixed product work — pulling in diagrams, wireframes, mockups, clickable prototypes, and annotated code walkthroughs and file trees as the work calls for them.
  • /visual-recap creates a high-altitude review of a change that already happened — a PR, commit, branch, or git diff — as schema, API, file, and before/after blocks instead of a wall of raw diff.

The agent should inspect the codebase first, then create the visual plan when a wrong direction would be costly. The returned Plans link opens the review UI in the browser or VS Code, so you can annotate, correct, choose options, and ask for updates before code changes begin.

When a Codex, Claude Code, Markdown, or pasted plan already exists, use /visual-plan; the agent preserves that source plan and builds the richer review surface from it instead of starting over.

If the first pass still has answerable decisions, the agent can place an Open Questions form at the bottom of the same plan. Answering it and sending it to the agent starts a revision turn against the existing plan.

Cost and model choice

Generating a plan or recap runs a full agentic session against your coding agent's LLM, not a lightweight template fill, so cost scales with the size of the diff or plan and the model you choose.

  • The app's default chat model is GPT-5.6 Luna. Direct Anthropic connections keep Claude Sonnet 5 as their default. Change models any time in Settings; Haiku is the cheaper Claude option.
  • Automated PR recaps from the GitHub Action run separately from the interactive app and have their own model and cost knobs — see PR Visual Recap for VISUAL_RECAP_MODEL, VISUAL_RECAP_AGENT, and VISUAL_RECAP_REASONING.

What you can do with it

  • Review before implementation. React to diagrams, wireframes, option tabs, Open Questions forms, risk notes, annotated code walkthroughs, and code previews before the agent edits files.
  • Comment directly on the plan. Pin feedback to text, images, wireframes, or canvas locations; choose whether the comment is for the agent or a human reviewer; @mention teammates with inline chips; and resolve comments as the plan evolves. See Reviewing and Commenting on Plans for the full comment and sharing model.
  • Hand feedback to the agent clearly. Text comments attach to the nearest prose block, visual comments include exact target metadata, and browser handoff includes focused screenshots for a small set of visual/canvas comment locations instead of one hard-to-read giant image.
  • Export the result. Keep an HTML, Markdown, or JSON receipt of the plan when you need a source-control-friendly handoff.
  • Keep plan content private. Use local-files mode to write plans to a local MDX folder instead of the hosted database — see Local-Files Mode and Desktop Sync.

Editing in the browser as a guest

People you share a plan with do not need to install anything. They open the Plans editor and create and edit with no sign-up — they work as a guest. Signing in is only required when someone wants to save or share their own work.

When a guest signs in, the plans they created as a guest are claimed into their account, so nothing they built is lost.

Plan prose edits inline: click into any text section, type, format with the rich editor toolbar or slash menu, and Plans autosaves the underlying markdown. Review annotation mode temporarily turns text sections read-only so clicks can pin feedback; leave review mode to keep editing prose.

Guest vs. signed-in, at a glance

  • As a guest you can open a shared link, create a new plan, edit prose, and use review annotation mode — no account needed.
  • Signing in additionally lets you save your own plans permanently, publish a plan to a shareable link, grant viewer/editor/admin access to others, post comments that notify people by email, and delete or restore plans you own.

Requesting access to a private plan

If someone opens a plan link they do not have permission to view, Plans does not just show a dead end. The page tells them the plan is private and offers a Request access action. Requesting access:

  • Requires being signed in (a guest is prompted to sign in first).
  • Records the request against the plan and, when the deployment has email configured, sends the plan owner a message with the requester's name and a link to open the plan and share it back if approved.
  • Is safe to click more than once — Plans checks whether you already have access first, and a second request from the same person does not spam the owner with duplicate emails.

If the plan's visibility is set to org rather than fully private, and your account already has a pending invitation to that organization or an email domain that matches it, Plans offers to join the organization directly instead of sending a request.

Recovering from auth errors

If a Plans tool ever returns needs auth, Unauthorized, or Session terminated, do not keep retrying it. Authenticate the connector with npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex for Codex, or re-run /mcp → Authenticate in an OAuth-capable host. Start a new Codex thread or restart/reload the relevant client before expecting the tool registry to update.

Useful prompts

  • "Use /visual-plan before changing the auth flow."
  • "Create a /visual-plan for the new onboarding screen with mobile and desktop states."
  • "Use /visual-plan on the Markdown plan below and make it easier to review."
  • "Run /visual-recap on this PR so I can review the shape of the change first."
  • "Use /visual-recap on the diff between main and this branch."
  • "Use /visual-recap in local-files mode so no recap content is written to the Plan DB."
  • "Run /visualize-repo and start with our public API actions and schema."

What's next

Edit this page on GitHub