---
title: "Local-Files Mode and Desktop Sync"
description: "Keep Agent-Native Plan content out of the hosted database with local-files privacy mode and visualize-repo, or mirror a hosted plan's source to a folder with Agent-Native Desktop."
---

# Local-Files Mode and Desktop Sync

Some plans should never touch a shared database — a security review, an
unreleased feature, or a repo you want the plan checked into directly. This
page covers the two ways Plan content can live in files on disk instead of
(or alongside) the hosted database, and how the two differ.

<Diagram id="doc-block-plan4" title="Three lanes for plan content" summary="Local-files mode and desktop sync both keep source in a folder, but only one of them skips the hosted database entirely.">

```html
<div class="diagram-lanes">
  <div class="diagram-box">
    Local-files mode<br /><small class="diagram-muted"
      >MDX folder only — never in the Plan DB</small
    >
  </div>
  <div class="diagram-box">
    Desktop local sync<br /><small class="diagram-muted"
      >Plan DB is the source of truth — folder is a mirror</small
    >
  </div>
  <div class="diagram-panel center">
    Hosted (default)<br /><small class="diagram-muted"
      >SQL-backed — sharing, comments, history, live review</small
    >
  </div>
</div>
```

```css
.diagram-lanes {
  display: flex;
  align-items: stretch;
  gap: 12px;
  flex-wrap: wrap;
}
.diagram-lanes .diagram-box {
  flex: 1;
  min-width: 180px;
}
.diagram-lanes .center {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 4px;
  text-align: center;
  flex: 1;
  min-width: 180px;
}
```

</Diagram>

## Local-files privacy mode {#local-files}

For privacy-focused work, ask for local-files mode:

```text
Use /visual-plan in local-files mode. Do not write this plan to the Plan DB.
```

or set the convention for your agent environment:

```bash
export AGENT_NATIVE_PLANS_MODE=local-files
```

In this mode the agent writes a local MDX folder and must not call the
hosted Plan MCP tools. Use a repo folder such as `plans/<slug>/` when you
want the plan checked in with the code. Use a temp or ignored folder, such
as `/tmp/agent-native-plans/<slug>/` or `.agent-native/plans/<slug>/`, when
the plan should stay out of git.

<FileTree
  id="doc-block-plan3"
  title="Local plan folder shape"
  entries={[
    { path: "plan.mdx", note: "frontmatter plus markdown/document blocks" },
    {
      path: "canvas.mdx",
      note: "optional — DesignBoard/Section/Artboard/Screen/Annotation/Connector markup",
    },
    {
      path: "prototype.mdx",
      note: "optional — Prototype/PrototypeScreen/PrototypeTransition markup",
    },
    {
      path: ".plan-state.json",
      note: "optional — source metadata for stable bare-Markdown block IDs",
    },
    {
      path: "assets/",
      note: "optional — local image assets referenced by the MDX",
    },
  ]}
/>

After writing the folder, the agent starts a tiny localhost bridge and opens
the hosted Plan UI against that local-only source:

```bash
npx @agent-native/core@latest plan local check --dir plans/<slug>
npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
```

The bridge URL looks like
`https://plan.agent-native.com/local-plans/local-<opaque-id>#bridge=http://127.0.0.1:...`.
The page is the normal Plan viewer, but the browser fetches `plan.mdx`,
`canvas.mdx`, `prototype.mdx`, `.plan-state.json`, and local image assets
from the localhost bridge instead of the hosted database. Plan content is
never written to the database and never sent through hosted Plan actions.
Keep the bridge process running while you review — the URL only works on
your machine and is not a shareable team link. The serve command writes the
open URL to `.plan-url` by default so coding agents can capture it without
scraping long-running stdout; treat that file as local-only, since the URL
contains the bridge token, and don't commit it.

<Callout tone="warning">

On macOS, `--open` prefers Chrome/Chromium because Safari can block the
hosted HTTPS Plan page from fetching an HTTP localhost bridge.

</Callout>

For headless troubleshooting, run:

```bash
npx @agent-native/core@latest plan local verify --dir plans/<slug> --kind plan
```

`verify` starts the bridge, checks the private-network preflight and JSON
payload, prints diagnostics, and exits.

If you run the Plan app locally with the same `PLAN_LOCAL_DIR`, you can also
open the editable app route:

```text
http://localhost:<port>/local-plans/<slug>
```

For repo-backed folders, the direct local route can carry the repo-relative
folder path so browser edits keep writing to that folder:

```text
http://localhost:<port>/local-plans/<slug>?path=plans%2F<slug>
```

The Plan app uses `apps.plan.roots[0].path` in `agent-native.json` as the
default repo location for promoted local plans, falling back to `plans/`:

```json
{
  "version": 1,
  "apps": {
    "plan": {
      "mode": "local-files",
      "roots": [{ "name": "Plans", "path": "plans", "kind": "plans" }]
    }
  }
}
```

Direct local Plan routes include a menu action to save a temporary local
folder into that repo location. After promotion, the page reopens with
`?path=...` and continues autosaving MDX edits to the repo folder.

Local-files mode prevents plan or recap content from reaching the
Agent-Native Plan database. It also disables hosted sharing, browser
comments, plan history, and publish/export receipts until you explicitly
opt into publishing. It does not automatically make your coding agent's LLM
local, though — choose a local or approved model too if that privacy
boundary matters.

## Promoting a local plan into the hosted database {#promote}

To move a local plan into the hosted database, call `publish-visual-plan`
with the local MDX folder path. This uploads the plan, assigns it a hosted
ID, enables sharing and commenting, and returns the hosted URL. From there
the plan follows the normal
[sharing and commenting rules](/docs/template-plan-review-workflow#sharing)
like any other hosted plan.

## Repo visual docs {#visualize-repo}

Use `/visualize-repo` when you want a durable visual documentation layer for
a codebase instead of a one-off plan or recap. It creates or opens a local
Plan MDX workspace, updates `agent-native.json` with an
`apps.visualize-repo` local-files section, and serves the docs through the
same localhost bridge:

```bash
npx @agent-native/core@latest visualize-repo --open
```

If no `agent-native.json` exists, the command bootstraps one and recommends
a small starter set from the repo structure, such as `actions/`,
`app/components/`, `app/pages/`, `server/db/schema.ts`, `src/`, `packages/`,
`templates/`, `docs/`, or `content/`. You can target specific source
anchors:

```bash
npx @agent-native/core@latest visualize-repo \
  --target actions/webhooks.ts \
  --target server/db/schema.ts \
  --target app/components/PromptComposer.tsx
```

The starter folder lives at `.agent-native/visual-docs/repo-overview` by
default. Comments stay local in `comments.json`, so reviewers can mark
sections for a coding agent, and the agent can update both code and MDX in
the same change. Run `visualize-repo check` for local lint, and
`visualize-repo verify` when you want the Plan renderer schema to validate
the MDX.

## Desktop local file sync {#desktop-local-sync}

Agent-Native Desktop also gives hosted Plans a native local-folder bridge.
This is different from local-files privacy mode: the hosted Plan database
stays the source of truth for sharing, comments, history, and live review,
while Desktop mirrors the current plan's source files to a folder you
choose.

Open a plan in Agent-Native Desktop, use the plan menu's **Local files**
actions, then:

- **Link local folder** — choose the folder for that plan's MDX source.
- **Sync to local folder** — write `plan.mdx`, optional `canvas.mdx`,
  optional `prototype.mdx`, optional `.plan-state.json`, and image assets.
- **Import local edits** — read the folder and apply it through
  `import-visual-plan-source` with the plan's current update timestamp.
- **Auto-sync changes** — keep exporting the hosted plan's latest source
  after edits made in the app.

This path doesn't require cloning the Plan app or running a CLI. It's for
file-first review and editing around a hosted plan, not for keeping plan
content out of the hosted database — use local-files privacy mode above for
that.

## What's next

- [**Visual Plans**](/docs/template-plan) — the two commands and the guest browser flow
- [**Reviewing and Commenting on Plans**](/docs/template-plan-review-workflow) — what publishing a local plan unlocks
- [**Extending Plan**](/docs/template-plan-developers) — MDX source sync actions and the fully offline local dev mode