Omniscio

Plugin Developer Mode (load unpacked plugins)

Developer Mode is the Plugins setting that loads your own unpacked plugin straight from a source folder on disk — the Chrome-style "Load unpacked" model, with hot reload, dev diagnostics, storage reset and a kill switch, and no packaging or marketplace submission.

On this page

What it is

Developer Mode lets you build and run your own Omniscio 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 — Omniscio 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, and once it succeeds the open panel reloads too, so a panel built into the same output folder shows the new code without closing and reopening it. Reload storms are debounced. A reload never touches the plugin's sidebar entry, its AI sessions or its schedules. Omniscio watches your plugin's FOLDERS, not its individual files, so a big plugin costs a handful of watches rather than thousands — node_modules and hidden folders (.git, .worktrees, local data dirs) are skipped entirely, except your own backend build folder if you happen to hide it. A folder tree past 200 sub-folders stops being watched beyond that point and says so in the plugin card's log tail, rather than quietly eating your CPU.
  • 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 Omniscio'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").

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. To make the plugin you load, see plugin-authoring.md. Once a plugin of your own is loaded, the screen a user configures it on is plugin-settings-panel.md, and the wider set of capabilities a plugin's own screen may call is plugin-bridge-capabilities.md.

Last verified 2026-09-23