---
title: "Visual Plans"
description: "Agent-Native Plans turns your coding agent's plan into a structured, reviewable document — diagrams, wireframes, annotated code, comments, and share links. Install once from the CLI; reviewers you share with edit as a guest and sign in only to save or share."
---

# Visual Plans

<Callout tone="info">

**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](/docs/plan-plugin) for the plugin and marketplace
routes. Customizing the Plan template (covered under [Extending Plan](/docs/template-plan-developers))
is the secondary path, for self-hosting or building on Plan itself.

</Callout>

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.

<Diagram id="doc-block-eoqv08" title="Two commands, one review surface" summary="Both commands publish through the hosted Plan MCP connector into the same annotate-and-comment surface.">

```html
<div class="diagram-plan">
  <div class="diagram-col">
    <div class="diagram-node">
      <span class="diagram-pill accent">/visual-plan</span
      ><small class="diagram-muted"
        >before code — architecture, UI, refactor</small
      >
    </div>
    <div class="diagram-node">
      <span class="diagram-pill">/visual-recap</span
      ><small class="diagram-muted"
        >after code — PR, commit, branch, diff</small
      >
    </div>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-panel center">
    Plan MCP connector<br /><small class="diagram-muted"
      >plan.agent-native.com</small
    >
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-box">
    Review surface<br /><small class="diagram-muted"
      >diagrams · wireframes · annotated code · comments</small
    >
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
  <div class="diagram-node">
    Coding agent<br /><small class="diagram-muted">feedback handed back</small>
  </div>
</div>
```

```css
.diagram-plan {
  display: flex;
  align-items: center;
  gap: 12px;
  flex-wrap: wrap;
}
.diagram-plan .diagram-col {
  display: flex;
  flex-direction: column;
  gap: 10px;
}
.diagram-plan .diagram-arrow {
  font-size: 22px;
  line-height: 1;
}
.diagram-plan .center {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 4px;
  text-align: center;
}
```

</Diagram>

<WireframeBlock id="doc-block-h7x805">
  <Screen
    surface="desktop"
    html={
      "<div style='display:grid;grid-template-columns:1fr 250px;gap:14px;padding:16px;min-height:520px;box-sizing:border-box'><main style='display:flex;flex-direction:column;gap:12px;min-width:0'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Checkout redesign plan</h1><div style='flex:1'></div><button>Share</button><button class='primary'>Approve</button></div><div class='wf-card' style='display:grid;grid-template-columns:1fr 1fr;gap:10px;min-height:150px'><div class='wf-box' style='display:flex;flex-direction:column;gap:6px;padding:10px'><span class='wf-muted' style='font-size:11px'>Current wireframe</span><div class='wf-box' style='height:14px'></div><div class='wf-box' style='height:28px'></div><div class='wf-box' style='height:28px'></div><div class='wf-box' style='height:18px;width:65%'></div></div><div class='wf-box' style='display:flex;flex-direction:column;gap:6px;padding:10px'><span class='wf-muted' style='font-size:11px'>Proposed wireframe</span><div style='display:flex;gap:6px'><div class='wf-box' style='flex:2;height:54px'></div><div class='wf-box' style='flex:1;height:54px'></div></div><div class='wf-box' style='height:18px;width:40%'></div></div></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:10px'><strong>Implementation plan</strong><div class='wf-box'>Decision: keep existing checkout shell</div><div class='wf-box'>Annotated code walkthrough</div><div class='wf-box'>Open questions</div></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Comments</strong><div class='wf-box'>Pin on primary CTA</div><div class='wf-box'>Question for agent</div><div class='wf-box'>Resolved copy note</div><button class='primary'>Hand back feedback</button></aside></div>"
    }
  />
</WireframeBlock>

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 {#install}

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:

```bash
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](/docs/plan-plugin#install). 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](/docs/pr-visual-recap).

<Callout tone="info">

**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](/docs/plan-plugin).

</Callout>

### Open Plans inside VS Code {#vscode-extension}

If you live in VS Code, install the
[Agent-Native Plans extension](https://marketplace.visualstudio.com/items?itemName=Builder.agent-native)
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](/docs/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](/docs/template-plan-review-workflow)
  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](/docs/template-plan-local-and-desktop).

## Editing in the browser as a guest {#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.

<Callout tone="info">

**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.

</Callout>

## Requesting access to a private plan {#request-access}

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 {#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

- [**Reviewing and Commenting on Plans**](/docs/template-plan-review-workflow) — comment types, resolving feedback, sharing, and deleting plans
- [**Local-Files Mode and Desktop Sync**](/docs/template-plan-local-and-desktop) — keep plan content off the hosted database, or mirror it to a folder
- [**Events and Automations**](/docs/template-plan-automations) — the plan event bus and automation recipes
- [**Extending Plan**](/docs/template-plan-developers) — data model, actions, and custom MDX blocks for customizing or self-hosting Plan
- [**PR Visual Recap**](/docs/pr-visual-recap) — run `/visual-recap` automatically on every pull request
- [**Plan plugin & marketplace**](/docs/plan-plugin) — install the Plan skills as a Claude Code or Codex plugin
- [**Skills**](/docs/skills-guide) — how Agent-Native installs skills
- [**MCP Clients**](/docs/mcp-clients) — configuring hosted MCP connectors
- [**Templates**](/docs/cloneable-saas) — the Cloneable SaaS model