/visual-edit

name: visual-edit
description: >-
  Open and collaboratively edit a running local app in Design, with shared
  fallback previews and source handoff. Use when the user asks to inspect,
  share, or edit a real local app in Design.
metadata:
  visibility: exported

Visual Edit

Use `/visual-edit` when the user wants to inspect or edit a real local app visually instead of generating standalone Alpine HTML. The source of truth is the running localhost app plus its route URLs. Design shows those routes as iframe-backed screens on the infinite canvas.

The editor is hosted at `https://design.agent-native.com`. Never start local Design; only the target app and bridge run locally.

See the [Visual Edit guide](https://github.com/BuilderIO/agent-native/blob/main/skills/visual-edit/README.md) for a worked onboarding-flow example.

Fast local startup

• Do not install this skill into the target app or start a local Design server.

The skill belongs to the coding host; Design is always the hosted app above.

• If you need to start an Agent-Native framework app yourself, use

`AUTH_DISABLED=1` with its normal dev command. This is local-only and gives the visual editor the framework's dev identity without a user login.

• If an agent-owned local server redirects a requested screen to `/sign-in`,

restart that server with `AUTH_DISABLED=1` and probe the route again before opening Design. Never present a sign-in page as the requested screen.

• Before calling `open-visual-edit`, verify the target URL responds. Start an

agent-owned dev server with its normal command when it is down, and wait for the requested routes to respond before opening Design. Never leave a dead localhost URL in the canvas.

• Preserve a server you did not start; use its existing authenticated browser

session or explain that the target app, rather than Design, requires login.

• When the user gives explicit paths, skip route inventory and place those

paths directly. Discover routes only when paths were not supplied.

Installation

`npx @agent-native/core@latest skills add visual-edit` installs the skill and hosted Design MCP connector. `npx skills@latest add BuilderIO/agent-native --skill visual-edit` installs instructions only; page-capable WebMCP hosts need no connector installation.

Put Design Beside The Chat

Prefer the MCP App from `open-visual-edit`: it keeps Design beside chat. Use **Copy prompt** to hand the visual edits to the coding agent; the host may request conversation confirmation. Otherwise, `openUrl` is a credential-free, read-only fallback; never claim it is editable.

• Inline-browser hosts should open `https://design.agent-native.com/visual-edit`

and call its `open-visual-edit` WebMCP tool. It works signed in or out; the one-time capability is not a Design account session. A page-capable browser controller is enough, so Claude-in-Chrome, Claude Code browser tools, the ChatGPT Chrome/browser extension, Puppeteer or Playwright MCP, CDP, and similar JavaScript-capable controllers do not need the hosted MCP connector.

• VS Code uses its Design webview/deep link. Without page WebMCP, use the hosted

Design MCP connector and its normal OAuth/device authorization. Never replace either path with a local Design server.

Inside Design, use **Show/Hide UI** from the `Cmd K` menu or press Figma's `Shift \` shortcut to toggle all editing chrome so only the canvas remains.

Browser WebMCP (Default Without Connector)

Without a connected Design MCP, use a visible browser tab with a main-world JavaScript evaluator. Prefer the host's inline browser; use external Chrome only when requested or unavailable. Open `https://design.agent-native.com/visual-edit`, keep it visible while tools register, and read the title before work. Never enter, copy, or request passwords, cookies, tokens, or codes. Signed-out loopback visual-edit works; other pages that block tools behind sign-in still require a signed-in tab. If the browser exposes CDP permissions, grant `local-network-access` to `https://design.agent-native.com` before calling page tools; otherwise use the page's Connect button and let the browser's permission prompt complete.

Use a native browser-session WebMCP bridge when the host provides one: list once with `list-browser-session-webmcp-tools` and run with `run-browser-session-webmcp-tool`, or use the `list-host-webmcp-tools` and `run-host-webmcp-tool` pair. Preserve the exact discovered name, origin, and args. Otherwise use the page-world API. Agent-Native pages expose this helper:

Example assumes signed-in or existing bridge; fresh signed-out loopback must add the locally held `bridgeToken` described below.

const an = window.__agentNativeWebMcp;
const status = await an.ready({ waitMs: 20_000 });
if (status.state !== "ready") throw new Error(status.error ?? status.state);
const tools = await an.tools("visual-edit");
if (!tools.some((tool) => tool.name === "open-visual-edit")) {
  throw new Error("open-visual-edit is not registered yet");
}
const result = await an.call("open-visual-edit", {
  devServerUrl: "http://localhost:5173",
  paths: ["/"],
  navigate: true,
}, { waitMs: 2_000 });
if (result.state === "pending") {
  // On the next evaluation, read the still-running call without replaying it.
  an.result(result.id);
}

If the helper is absent, use standard WebMCP directly. `document.modelContext` is canonical; `navigator.modelContext` is deprecated:

const ctx = document.modelContext;
const tool = (await ctx.getTools()).find((candidate) => candidate.name === NAME);
if (!tool) throw new Error(`WebMCP tool not found: ${NAME}`);
const codex = typeof ctx.codexExecuteTool === "function" ||
  typeof ctx.codexGetTools === "function";
const result = await ctx.executeTool(tool, codex ? ARGS : JSON.stringify(ARGS));

The helper handles live discovery, partial registries, and pending calls. If a call returns `state: "pending"`, read `an.result(id)` on the next evaluatio