---
title: Plugin Developer Mode (load unpacked plugins)
---

# Plugin Developer Mode (load unpacked plugins)

## What it is

Developer Mode lets you build and run your own AMC plugins straight from a
source folder on disk — the same "Load unpacked" model as Chrome extensions. No
packaging, no checksums, no marketplace submission, no external CLI: pick the
folder, and the plugin loads.

## Where to find it

**Settings → Plugins → Developer Mode** — the **Developer Mode** section of that page, desktop only.
It is a section inside the Plugins page rather than a page of its own, and none of its operations
are reachable from a paired phone or from the CLI control server.

## How it behaves

### What you can do

- **Turn on Developer Mode** — a toggle with explicit trust wording: unpacked
  plugins skip the marketplace's distribution checks, and a plugin backend runs
  with full Node access, so only load folders whose code you trust. Turning the
  toggle OFF fully unloads every dev plugin (workers stopped) — it is the kill
  switch.
- **Load unpacked plugin** — a native folder picker. The folder must contain a
  valid `manifest.json`; if the manifest is invalid you see the exact validation
  error, verbatim. Loaded plugins appear with a **DEV** badge and outrank a
  marketplace or built-in copy of the same plugin id.
- **Hot reload** — AMC watches the folder. Saving a UI file reloads the
  plugin's webview instantly; changing `manifest.json` or the backend build
  output triggers a full disable→enable cycle automatically. `node_modules` and
  `.git` are ignored, and reload storms are debounced.
- **Dev diagnostics** — the plugin's Settings card shows its live backend
  status, the last error verbatim, and a recent log tail; the plugin's own
  panel gets a slim dev toolbar with **Reload** and **Open DevTools**.
- **Reset storage** — wipes the plugin's stored data (webview storage + its
  data folder) for a clean-slate test; your source folder is untouched.
- **Remove** — unregisters the folder. It NEVER deletes or modifies the folder
  on disk, and re-adding it later brings the plugin back.

### Rules and safety (why some folders are refused)

- Folders inside AMC's own data directory, inside `~/.claude`, your home folder
  itself, or a whole drive root cannot be registered; up to 20 folders.
- A registered folder that later breaks (deleted, or its manifest stops
  parsing) shows an error card with the verbatim reason instead of silently
  vanishing — Remove works on it by path.
- Developer Mode is desktop-only: none of its operations are reachable from a
  paired phone or the CLI control server (the existing
  `POST /plugins/:id/reload` route remains for the external `amc-plugin` CLI's
  own loop).
- The marketplace's distribution security (checksums, signatures, consent
  dialogs) is completely untouched — dev mode is a parallel path for your own
  code, not a relaxation of the store's checks.
- Uninstalling a marketplace plugin now also fully stops its background worker
  first, and if a shipped built-in baseline of the same plugin remains, the
  toast says so ("the built-in version remains").

## For agents

- Origin precedence: `dev` > `marketplace` > `builtin`; the loader's dev scan
  pass runs only while `pluginDevMode` is on. Retired plugin ids stay barred
  from every source, including dev.
- The two backing settings (`pluginDevMode`, `devPluginFolders`) are
  INTERNAL_ONLY — writable only via the `plugin:dev-*` IPC handlers, never a
  generic settings PATCH.
- Channels: `plugin:dev-set-mode` / `dev-add` / `dev-remove` / `dev-reload` /
  `dev-reset-storage` / `dev-get-logs` (all WS-blocked), push
  `plugin:dev-ui-reload`.
- Contract: [.claude/memory/contracts/plugin-dev-mode-contract.md](../../.claude/memory/contracts/plugin-dev-mode-contract.md)
  (11 test-locked invariants — read it before changing any of this).

## Related

Developer Mode is the parallel path to the Plugin Marketplace, which is where plugins are normally
browsed, installed and removed — that is [plugin-marketplace.md](plugin-marketplace.md). Once a
plugin of your own is loaded, the screen a user configures it on is
[plugin-settings-panel.md](plugin-settings-panel.md), and the wider set of capabilities a plugin's
own screen may call is [plugin-bridge-capabilities.md](plugin-bridge-capabilities.md).