Development workflow
Author path: init a template, declare integrations, implement Worker or App, wire the stdio entry, build / validate / test, bind a running Host, run dev, pack, submit to the marketplace.
Development, validation, linking, and diagnostics stay on the command line. Bind the Host with dimo plugin run server, then run dimo plugin run … from the plugin directory. Linking uses the local Host token from Desktop or npx dimo serve. Do not ask the operator for a token.
dimo plugin run server --http://127.0.0.1:17891 --token <token>
dimo-plugin init my-notes --publisher you --template full
dimo plugin run build
dimo-plugin validate
dimo plugin run test
dimo plugin add --dev .
dimo plugin run dev
dimo plugin run test --host
dimo plugin pack
npx dimo plugin publishdimo-plugin toolchain prints Host version, CLI, contract, JS / Python / Rust SDK paths, and template names.
Templates
dimo-plugin init my-notes --publisher you --template fullinit writes the manifest, README, config.json, content index, tests, and matching source, then builds immediately. Default template: full. For the chosen template, build / validate / test must pass, and the declared integrations must activate on a real Host.
| Template | Output |
|---|---|
skill |
Skill projection |
mcp |
Managed MCP descriptor and placeholder process |
hooks |
Hook resource |
file-tab |
Node Worker, read-only .txt preview (artifact.preview), and a detail panel (slot: plugin.detail.panel) |
editor-tab |
Editable UTF-8 file tab (file.opener.editorSurface + slot: artifact.editor) |
full |
Node Worker, App detail panel, Workflow |
ts-worker |
TypeScript Worker definition (runtime/main.ts) |
node-worker |
JavaScript Worker definition (runtime/main.mjs) |
python-worker |
CPython Worker (runtime/worker.py includes the stdio entry) |
rust-worker |
native Worker source (runtime/src/main.rs includes the stdio entry) |
host-service |
Periodic handler, default intervalSeconds 30 |
host-chrome |
One contribution per chrome slot |
provider-import |
One provider.model.importSource |
panel |
One app.panel with a Vite Module Federation remote |
kanban-view |
One app.kanban.view with a Vite Module Federation remote |
engines.dimo is >=0.1.3 <1.0.0. engines.pluginSdk is ^1.0.0. python-worker and rust-worker source already call run_stdio_plugin_worker / run_stdio_plugin_worker_blocking. dimo-plugin build does not compile Rust; the Rust template path points at the compiled binary, and the README states to run cargo build.
host-chrome writes app.command / app.toolbar / app.status / app.composer.slash / app.timeline.card / app.settings.section. panel and kanban-view write a Federation project; during run dev Host loadRemote points at Vite. Editable file-tab steps: Contribution model.
Node Worker entry
The Host starts a Node Worker with:
node --max-old-space-size=128 <entrypoints.worker.path>That process must run protocol 1.1 on stdin/stdout. Recommended split:
runtime/worker.mjs # definePluginWorker(...)
runtime/main.mjs # runStdioPluginWorker(definition)runtime/main.mjs:
import { runStdioPluginWorker } from '@dimo/plugin-sdk/stdio';
import definition from './worker.mjs';
await runStdioPluginWorker(definition);dimo-plugin build bundles runtime/main.mjs into dist/worker.mjs. Manifest:
"entrypoints": {
"worker": {
"path": "dist/worker.mjs",
"runtime": "node",
"protocol": "1.1"
}
}Official Office uses this split. init --template node-worker writes the handler definition in runtime/main.mjs; call runStdioPluginWorker at the top level, or split like Office. Tests import the definition module so they skip the stdio loop; comparison data is exported from a module.
Author CLI and product CLI
dimo-plugin writes packages: init, build, validate, test, pack, toolchain, doctor. Run it from the plugin root.
| Command | Role |
|---|---|
validate [--json] |
Validate manifest, index, references |
build |
Validate; compile runtime/main.mjs to dist/worker.mjs; compile App, Federation remote, and managed MCP source |
test |
build first, then run test/*.{test,spec}.{mjs,js,mts,ts} in a temp directory |
pack [--output file.vxp] |
Write package.lock.json, emit a deterministic .vxp, print sha256: |
doctor |
Install, activation, Runtime, surfaces, bindings, recent crashes |
toolchain |
Print local SDK and template paths |
run server |
Write Host URL and token to ~/.dimo/pluginrc |
run dev |
Build, link, watch; start Vite HMR when a Federation remote exists |
run test --host |
Against a running Host: install → enable → contributions appear → disable withdraws them → enable again → uninstall |
npx dimo plugin operates the same Host catalog and the official marketplace. When desktop or npx dimo serve is running, the command finds the local Host token. Default URL is http://127.0.0.1:17891; override with DIMO_URL / DIMO_TOKEN. If no Host is up, snapshots go to ~/.dimo/imports/ and linked directories to ~/.dimo/imports/links.jsonl; the next launch imports them.
npx dimo plugin add --dev .
npx dimo plugin add --dev . --detach
npx dimo plugin add --profile dist/notes.vxp
npx dimo plugin add --web https://github.com/<owner>/<repo>#v1.0.0
npx dimo plugin add --web https://dimo-ai.com/marketplace/<owner>/<name>
npx dimo plugin list
npx dimo plugin test --host
npx dimo plugin pack
npx dimo plugin publish
npx dimo plugin remove <plugin-id>add --dev only links the directory and returns. HMR is started by dimo plugin run dev. dimo-plugin dev is an alias of run dev. dimo-plugin install --link, when still present, is the same Host import.
run dev builds, links, then watches. A digest change reloads the Worker (activation generation). With a Federation remote, Host loadRemote points at Vite so panel code hot-reloads without reloading the Host. On failure the previous complete generation stays visible. Neither path deletes the development directory.
Snapshot install, origin lock, update, and Update available: Install a Plugin from the marketplace. Marketplace submit: below and plugin.
Accept against a Host
- Edit the README
summaryand body. - Declare only stable-surface integrations you actually implement.
- Handler ids match the declarations and the handler regex.
- For a Node package, confirm
dist/worker.mjscontains the stdio loop. build,validate,test. Runnpx dimo plugin test --hostwhen you need the real install path.- Open Dimo or
npx dimo serve, rundimo plugin run server, thennpx dimo plugin add --dev .anddimo plugin run dev. - Enable the package in Settings → Plugins. Exercise the declared integrations: Skill projection, MCP injection, read-only preview, editable-file revision conflict, detail panel, chrome slots, structure surfaces, provider import. UI contributions appear on enable; the Agent tool list follows a new session.
- Inspect the crash ring with
dimo-plugin doctor. - Distribute with
npx dimo plugin pack. Install locally withadd --profileor by dropping a.vxp. Pin Git with#tagon--web. Publish withnpx dimo plugin publish.
test --host against a chrome or structure package: install → enable → declared kinds appear in plugin_contribution_catalog → they vanish on disable → enable again → uninstall, source directory kept. A Skill-bearing package also reloads SKILL.md.
The harness covers in-process contracts. File tabs, preview processes, Runtimes, structure surfaces, and remote-workstation observation finish on a running Host. A passing validate proves the manifest is legal; whether App, Runtime, or MCP is available on the Host is decided by Host acceptance.
Submit to the marketplace
Register a marketplace account on the site. The CLI sends a packed result or a GitHub repository into the review queue:
npx dimo plugin publish . --owner <marketplace-user> --password <password> [--show-tree]
npx dimo plugin publish --web <github-owner/repo[#tag]> --owner <marketplace-user> --password <password>Credentials also come from DIMO_MARKET_OWNER / DIMO_MARKET_PASSWORD. Default submit URL is https://dimo-ai.com; override with DIMO_MARKETPLACE_URL. The GitHub owner must match the marketplace username. Uploaded packages hide the tree by default; --show-tree shows it. GitHub listings show the tree by default.
After review, the listing appears in the public catalog and the Host Marketplace tab. One owner/plugin-name card keeps history and defaults to latest. A published GitHub repository appends a version when a new tag is pushed. Pending packages stay out of the Catalog.
Developing inside the Dimo repository
From the Dimo repository root, list contract files for the current checkout:
python3 .agents/skills/dimo-plugin-development/scripts/locate_toolchain.py
node packages/plugin-cli/dist/cli.js toolchainrequired includes the SDK, CLI validator, docs/plugins/package-v4.md, and docs/plugins/sdk-and-cli.md. Fill any missing path first. Python SDK lives in sdk/python. Rust SDK lives in crates/plugin-sdk. The author Skill follows that checkout.