--- title: "Plan plugin & marketplace" description: "Install the Agent-Native Plan skills (/visual-plan, /visual-recap, /visualize-repo) plus the hosted Plan MCP connector as a Claude Code or Codex plugin, or with the universal CLI. How updates work and whether you need to submit anything." --- # Plan plugin & marketplace The Agent-Native **Plan** app ships as one installable bundle. A single install adds the Plan slash-command skills **and** wires up the hosted Plan MCP connector, so the agent can generate plans and the skills can publish them straight into the Plan app. ## What you get {#what-you-get} One install gives you: - **Three skills** — `/visual-plan` (the canonical entry point), `/visual-recap`, and `/visualize-repo`. - **The Plan MCP connector** — registered against the hosted app at `https://plan.agent-native.com` (MCP endpoint `https://plan.agent-native.com/mcp`, server name `plan`). ```html
Universal CLI
skills add visual-plan
Claude Code plugin
/plugin install
Codex plugin
codex plugin add
/visual-plan/visual-recap/visualize-repothree skills
Plan MCP connector
plan.agent-native.com/mcp
``` ```css .diagram-routes { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; } .diagram-routes .diagram-col { display: flex; flex-direction: column; gap: 10px; } .diagram-routes .diagram-arrow { font-size: 22px; line-height: 1; } .diagram-routes .center { display: flex; flex-direction: column; align-items: center; gap: 4px; text-align: center; } .diagram-routes .center .diagram-pill { margin: 2px; } ``` By default, `/visual-plan` and `/visual-recap` publish to the hosted Plan app — they create a plan via the MCP connector and hand you a link or inline plan to review. They never dump an inline Markdown/ASCII plan into chat as the deliverable. If a Plan tool returns `needs auth`, `Unauthorized`, or `Session terminated`, re-authenticate the connector instead of falling back to inline output. Access tokens are long-lived (30-day default, sliding 365-day refresh), so this should be rare; when it happens, the lightweight fix is: ```bash npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex ``` `reconnect` finds and refreshes the connector by URL for the selected local client — no reinstall needed. Start a new Codex thread after reconnecting so the tool registry reloads. In Claude Code, the equivalent is `/mcp` → **Authenticate / Reconnect**, or the same command with `--client claude-code`. The exception is explicit **local-files privacy mode**. When you ask for no DB writes or set `AGENT_NATIVE_PLANS_MODE=local-files`, the skills must not call the Plan MCP connector. They write `plans//plan.mdx` plus optional `canvas.mdx`, `prototype.mdx`, and `.plan-state.json`, then preview locally with: ```bash npx @agent-native/core@latest plan local serve --dir plans/ --kind plan --open ``` This starts a tiny localhost bridge and opens the Plan UI against the local folder. (`plan local preview` runs a local Plan dev-server route instead, and `plan local preview --out preview.html` is a legacy escape hatch that writes a standalone static HTML file. `plan serve` is accepted as a short alias for `plan local serve`.) A few local-files-mode gotchas worth knowing: - **Use a Chromium browser.** Safari blocks the hosted HTTPS Plan page from reading the `http://127.0.0.1` localhost bridge (mixed-content / private network), so the page hangs on "Loading plan." On macOS `--open` already prefers Chrome/Chromium/Edge/Brave; if Safari opens anyway, reopen the printed URL in a Chromium browser. - **The served URL is written to `plans//.plan-url`** (override with `--url-file`). A backgrounded or headless agent can read that file instead of scraping the long-running `serve` stdout. Treat it as a local token file and do not commit it. - **Verify headlessly** when no browser is available: `npx @agent-native/core@latest plan local verify --dir plans/` starts the bridge, checks the private-network preflight and JSON payload, prints diagnostics, and exits non-zero on failure — no human eyes required. - **Run `plan local check` first.** It validates the MDX against the Plan renderer's block schema (including required fields like `checklist` item `id`/`label` and `question-form` question `id`/`title`/`mode`), so authoring mistakes surface before the browser handoff instead of as a stuck loader. For folders in the current repo, the direct local route includes `?path=...` so the local Plan app can keep browser edits saving to the repo folder. The Plan app uses `apps.plan.roots[0].path` in `agent-native.json` as the default place to save promoted local plans, falling back to `plans/`. This keeps plan content out of the Agent-Native Plan database. Hosted sharing, comments, screenshots, and plan history are unavailable until you explicitly publish later. ```html
Default · hostedPublish to the Plan appMCP connector → hosted DB → share links, comments, history, screenshots
Local-files privacyWrite MDX to diskplan.mdx + canvas.mdx + prototype.mdx → localhost bridge → hosted Plan UI reads local source. No DB writes until publish-visual-plan.
``` ```css .diagram-modes { display: flex; gap: 14px; flex-wrap: wrap; } .diagram-modes .diagram-card { flex: 1 1 260px; display: flex; flex-direction: column; gap: 6px; padding: 16px 18px; } ``` Agent Native Desktop has a separate local-file sync path for hosted plans: the Desktop app can mirror a hosted plan to local MDX files and import edits back without cloning the Plan app or running a CLI. That workflow keeps the hosted Plan database as the source of truth; use local-files privacy mode when the goal is no Plan DB writes. > The plugin (`agent-native-visual-plans`) carries app id `visual-plans`, which is why the Claude Code plugin name and Codex plugin name are both `agent-native-visual-plans`. The Plan app's display name is "Agent-Native Plan". ## Install routes {#install} There are three ways in. The **universal CLI route** is the one we recommend by default, because it installs the skills **and** lets you choose hosted, local-files, or self-hosted mode in one flow. The plugin routes are for hosts with a first-class plugin/marketplace system and use hosted Plans by default. ### Universal skill route (any MCP host) {#universal} Works for any host — Claude Code, Codex, Cursor, Cline, Goose, ChatGPT custom MCP apps, Claude Cowork, and anything else MCP-compatible. The Agent-Native CLI installs the Plan skills, registers the hosted Plan MCP connector, **and runs auth for the selected local client(s) in the same step**, so your first tool call does not hit an OAuth wall: ```bash npx @agent-native/core@latest skills add visual-plan ``` This installs `visual-plan` plus the companion `visual-recap` and `visualize-repo` skills, then registers the `plan` connector, then runs auth (OAuth prompt for hosted/account-backed sharing). Useful flags: - `--client codex|claude-code|claude-code-cli|cowork|all` — which local agents to write the MCP config for (default `all`). - `--no-connect` — register the connector without authenticating; run `npx @agent-native/core@latest connect https://plan.agent-native.com --client all` later, or choose a narrower `--client`. - `--mode hosted|local-files|self-hosted` — choose hosted sharing, all-local MDX files, or your own Plan app. - `--mcp-url ` — point the connector at a custom origin (an ngrok tunnel, a local dev server, or a self-hosted deployment) instead of the hosted default. - `--with-github-action` — also write the PR Visual Recap GitHub Action (see [PR Visual Recap](/docs/pr-visual-recap)). Interactive installs also offer the PR Visual Recap Action when no workflow is present. Say yes to add it during skill setup, or run the command above later with `--with-github-action`. After the workflow is written, run: ```bash npx @agent-native/core@latest recap setup npx @agent-native/core@latest recap doctor ``` `recap setup` configures the GitHub Action secrets and variables where possible, and `recap doctor` verifies the workflow, local publish token, GitHub repo access, and required Actions configuration. After install finishes, restart or reload the agent client so the new skills and tools load, then run `/visual-plan`. > Note: the bare `npx skills@latest add BuilderIO/agent-native --skill visual-plan` (Vercel/open Skills CLI) installs **instructions only** — it does not register the MCP connector. Use the Agent-Native CLI above when you want the connector wired up too. ### Claude Code (plugin) {#claude-code} The public `BuilderIO/agent-native` repo is itself a Claude Code plugin marketplace, so you add it directly — no build step. Inside Claude Code: ```text /plugin marketplace add BuilderIO/agent-native /plugin install agent-native-visual-plans@agent-native-apps /reload-plugins /mcp # authenticate the Plan connector (one OAuth approval) ``` `/plugin install` adds the Plan skills and a **URL-only** MCP config (no secrets in the package); `/mcp` → **Authenticate** completes the OAuth handshake. Use the universal CLI route instead when you want local-files or self-hosted mode. > The marketplace catalog is named `agent-native-apps` and the Plan plugin is `agent-native-visual-plans`, so the install target is always `agent-native-visual-plans@agent-native-apps`. ### Codex (plugin) {#codex} The same repo is a Codex plugin marketplace. Add it, install the plugin, then authenticate the connector: ```bash codex plugin marketplace add BuilderIO/agent-native codex plugin add agent-native-visual-plans@agent-native-apps codex mcp login plan # OAuth in the browser ``` After install, **start a new Codex thread** so the skills and MCP tools load into the session. The plugin ships a URL-only connector (`[mcp_servers.plan]` → `https://plan.agent-native.com/mcp`); `codex mcp login plan` runs the OAuth flow. The universal CLI route above also works for Codex (`npx @agent-native/core@latest skills add visual-plan --client codex`) if you prefer one command that installs and authenticates together, or when you want local-files or self-hosted mode. **Older installs:** if your config still has an `agent-native-plans` entry pointing at the same URL, running `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex` for Codex, or the same command with your target `--client`, consolidates it to the canonical `plan` name. ## Updates {#updates} The plugin routes auto-update — you do not re-pack or re-add the marketplace for routine skill changes: - **Claude Code** — the marketplace entry sets `autoUpdate: true` and the plugin uses commit-SHA versioning, so Claude Code pulls new versions from the repo at startup; run `/reload-plugins` to activate. Every push to the repo's default branch reaches installed users automatically. - **Codex** — the plugin `version` embeds a content hash of the bundled skills and MCP endpoint (e.g. `1.0.0+codex.`), so any skill or endpoint change yields a new version. Codex's startup auto-upgrade re-installs configured git marketplaces on its own; just **start a new thread** to pick up the change. No manual `codex plugin marketplace upgrade` is needed for routine updates. - **Universal CLI route** — run `npx @agent-native/core@latest skills status visual-plan` to check copied skill folders, or `npx @agent-native/core@latest skills update visual-plan` to refresh them in place. Re-running `skills add visual-plan` still works when you also want to re-register/authenticate the connector. `@latest` always pulls the current skills from the published `@agent-native/core` package. The connector points at a **hosted** app, so the Plan app's actions and live tool surface always reflect the deployed version regardless of when you installed; only the bundled skill instructions follow the update mechanisms above. **Maintainers:** the marketplace bundle (`.claude-plugin/`, `.agents/plugins/`) is generated from the canonical plan skills by `pnpm sync:plan-marketplace` and verified in CI by `pnpm guard:plan-marketplace`, so the published marketplace always matches the canonical skills. Edit the skill, run `pnpm sync:plan-marketplace`, and commit. ## Do you need to submit anything? {#submission} **No submission or review is required to distribute or install this.** `BuilderIO/agent-native` is a self-hosted, public git marketplace, so users add it directly with the commands above on **both Claude Code and Codex** — no application or approval. The universal CLI route needs no marketplace at all. Optional discoverability, if you want a public listing: - **Claude Code** has a community marketplace you can _optionally_ submit to for listing (submission plus an automated review). The official, Anthropic-curated marketplace is listed at Anthropic's discretion — there is no open self-serve application. Neither is required to use the install commands above. - **Codex** has an OpenAI-curated plugin catalog (a closed allow-list, sourced as a partnership rather than a self-serve submission). Self-hosted git marketplaces and the CLI route need no submission to work. In short: ship it as a self-hosted/public git marketplace and users install directly; submit to a curated catalog only if you want it listed for discovery. ## Plugin vs. skill {#plugin-vs-skill} A **skill** is a single `SKILL.md` instruction file the agent reads when a task matches. A **plugin** (Claude Code marketplace plugin or Codex plugin) is a package that bundles one or more skills **plus** an MCP connector and metadata, so a host can install everything in one step. Under the hood, all three routes are produced from the same source by the `npx @agent-native/core@latest app-skill` CLI: `app-skill pack` builds the marketplace/plugin adapters, and `skills add` is the friendly one-step installer that also registers and authenticates the MCP connector. See [Skills Guide](/docs/skills-guide) for the app-skill manifest format, and [External Agents](/docs/external-agents) for connecting any MCP host and the `npx @agent-native/core@latest connect` flow. ## What's next {#whats-next} - [**Visual Plans**](/docs/template-plan) — what the skills do and how to use them - [**PR Visual Recap**](/docs/pr-visual-recap) — run `/visual-recap` automatically on every pull request - [**Skills Guide**](/docs/skills-guide) — app-backed skills and the manifest format - [**External Agents**](/docs/external-agents) — connect any MCP host and round-trip artifacts