Getting Started

Build and install your first Omniscio plugin in under five minutes.

Prerequisites

• Node.js v18 or later
• Omniscio installed and running
• A terminal (PowerShell, bash, zsh)

Install the CLI

Install the Omniscio Plugin CLI globally:

npm install -g @agent-mc/plugin-cli

Verify the installation:

amc-plugin --version
# 1.0.0

Scaffold a New Plugin

Run amc-plugin create with a kebab-case name:

amc-plugin create my-plugin

The CLI walks you through an interactive prompt:

? Display name: My Plugin
? Description: An Omniscio plugin
? Author: Your Name
? Category: other
? Icon — a path to your logo in the package (assets/icon.svg), or a Lucide name for a generic glyph: assets/icon.svg

Scaffolding my-plugin with template: basic...

Installing dependencies...
added 2 packages in 3s

Plugin scaffolded at ./my-plugin/

Next steps:
  cd my-plugin
  npm run build
  npm run dev

Templates

Choose a template with the -t flag:

Template	What you get
basic (default)	UI only (src/ui/)
with-backend	UI + backend (src/backend/) with storage permission
full	UI + backend + cron job + CLI endpoint with storage, cron, and cli permissions

# Scaffold with a backend
amc-plugin create my-tool -t with-backend

# Scaffold with everything
amc-plugin create my-suite -t full

You can also skip the interactive prompts entirely:

amc-plugin create my-plugin \
  -t basic \
  --display-name "My Plugin" \
  --description "Does something useful" \
  --author "Your Name" \
  --category development \
  --icon wrench

Explore the Generated Files

After scaffolding, your plugin directory looks like this:

my-plugin/
  manifest.json       # Plugin metadata, settings, permissions
  package.json        # npm dependencies and scripts
  tsconfig.json       # TypeScript configuration
  .gitignore          # Ignores node_modules/, dist/, *.amcplugin
  src/
    ui/
      index.html      # Plugin UI entry point
      plugin.ts       # TypeScript for the UI

TIP

See Project Structure for a detailed breakdown of every file.

Build

Compile TypeScript and copy non-TS assets (HTML, CSS, images) into dist/:

cd my-plugin
npm run build

Expected output:

Manifest validated
Compiling TypeScript...
Build complete

The build command does three things:

1. Validates manifest.json against the SDK schema
2. Runs tsc to compile TypeScript into dist/
3. Copies non-TypeScript files from src/ui/ into dist/ui/ (HTML, CSS, images)

Validate

Run validation checks without producing build output. Useful for CI pipelines:

npx amc-plugin validate

Expected output:

PASS: Manifest schema
PASS: SDK version declared (2.0.0)
PASS: UI entry point exists
PASS: TypeScript compilation

All checks PASSED

WARNING

The validate command also scans compiled output for banned imports (electron, better-sqlite3, worker_threads, child_process — the last two in both their bare and node:-prefixed spellings) and fails on a hit. build runs the same scan but only warns, so you catch it earlier, and publish runs it again and refuses to upload — the same rule at all three points. Marketplace plugin backends run under Node's --permission and cannot access these modules directly.

child_process will not work, even though it compiles

child_process is the module authors most often reach for, usually to shell out to a CLI. A marketplace plugin backend runs under Node's --permission, which denies spawning a child process, so the import compiles, the plugin installs — and then every call fails at runtime.

Use HTTPS to talk to external services instead; the sandbox allows outbound network requests. If you genuinely need a host capability the plugin API does not expose, ask for it rather than shelling out.

Package

Bundle your plugin into a .amcplugin archive:

npx amc-plugin package

Expected output:

Packaged: my-plugin-1.0.0.amcplugin (0.01 MB)

If dist/ does not exist, the package command builds automatically before packaging.

The archive contains:

• manifest.json
• dist/ (compiled output)
• assets/ (if present)

WARNING

The marketplace enforces a 50 MB package size limit. The CLI warns you if your archive exceeds this.

Install in Omniscio

1. Open Omniscio
2. Go to Settings > Plugins
3. Click Install from file
4. Select your .amcplugin file
5. The plugin appears in the sidebar

Your plugin is now running inside Omniscio. Open it from the sidebar to see your UI.

Next Steps

• Project Structure -- understand every file in your plugin
• Manifest -- configure settings, permissions, storage, cron, and CLI endpoints
• Permissions -- learn what each permission grants
• Dev Shell -- develop with hot-reload outside Omniscio
• Publishing -- submit your plugin to the Omniscio Marketplace