Build custom room orchestrators for Commands Desktop. No source access required.
External room orchestrator plugins for Commands Desktop. Works with packaged installs — no source repo needed.
Room Start ──> Orchestrator Plugin ──> Fan-out / Workers ──> Results
commands-room-compressed.mp4
| Zero dependencies | Reference plugin uses only Node.js built-ins |
| Cross-platform | Bash installer for macOS/Linux, Node.js installer for Windows |
| Full lifecycle | Hooks for init, start, turn results, fan-out, events, resume, shutdown |
| Dashboard panels | Counter groups, progress bars, charts, agent status, tables, conversation feeds |
| SHA-256 integrity | Allowlist with optional hash pins, safe in-tree symlink hashing, dev-only bypass |
| Declarative rooms | Define phases, dispatch, and dashboard in room.yaml — family runtimes handle orchestration |
| Copy-and-go | Clone template-room, edit manifest and handler, reinstall |
| Additive | External room types extend built-ins — never override |
- Node.js 18+
- Commands Desktop (DMG, installer, or dev build)
git clone https://github.com/Commands-com/room-plugins.git
cd room-pluginsmacOS / Linux:
./scripts/install-room-plugins.shWindows (or any platform with Node.js):
node scripts/install-room-plugins.mjsBoth scripts copy plugins, install npm dependencies, and generate the SHA-256 allowlist.
Use --plugin <name> to sync a single plugin without pruning other managed plugin folders already present in the destination. Installer-generated allowlists now only include installer-managed plugin directories in the destination.
./scripts/install-room-plugins.sh --plugin fft-autotune
node scripts/install-room-plugins.mjs --plugin fft-autotune| Platform | Default install locations |
|---|---|
| macOS / Linux | ~/.commands-com/workspace/room-plugins |
| Windows | %LOCALAPPDATA%\commands-com\workspace\room-plugins |
Restart Commands Desktop.
cp -R ./room-plugins/template-room ./room-plugins/my-roomUpdate:
manifest.json— setorchestratorType, display name, participant rolesindex.js— implement lifecycle hooks (onRoomStart,onTurnResult,onFanOutComplete, etc.)
For rooms that follow an established pattern (e.g., empirical search/optimization):
cp -R ./room-plugins/redshift-query-optimizer ./room-plugins/my-optimizerUpdate:
room.yaml— phases, dispatch, dashboard, family configlib/engine.js— domain-specific logic (plan shape, prompt builders, winner rendering)lib/harness.js— environment interaction (connect, compatibility)
See Declarative Rooms Guide for full reference.
./scripts/install-room-plugins.sh # macOS/Linux
node scripts/install-room-plugins.mjs # Windows (or any platform)Restart Commands Desktop and create a room using your orchestratorType.
| Rule | Detail |
|---|---|
| Built-in room types | Always load |
| External room types | Additive — cannot override built-ins |
| Allowlist | Plugin directory names must be listed |
| Integrity | If allowlist entry includes sha256, enforced at load time |
| File checks | manifest.json and index.js must be regular files (no symlinks) |
Dev-only bypass:
COMMANDS_AGENT_DEV=1 COMMANDS_AGENT_TRUST_ALL_PLUGINS=1In Desktop: Settings > Developer > Dev Mode + Trust All Plugins.
room-plugins/template-room Classic reference implementation (copy to create new)
room-plugins/spec-room Classic multi-pass spec authoring room
room-plugins/fft-autotune Advanced empirical search room (classic)
room-plugins/postgres-query-optimizer Declarative room (Docker harness, index + rewrite strategies)
room-plugins/redshift-query-optimizer Declarative room (live cluster, rewrite + advisory strategies)
room-plugins/sql-optimizer-core Shared library for SQL optimizer plugins
scripts/dev-config-spec-room.json Example config for running Spec Room locally
scripts/dev-runner.js Dev harness — run plugins locally with Ollama or fixtures
scripts/install-room-plugins.sh Bash installer (macOS/Linux)
scripts/install-room-plugins.mjs Node.js installer (cross-platform)
scripts/generate-room-allowlist.mjs Generate allowlist with SHA-256 pins
scripts/compute-room-plugin-sha256.mjs Compute single plugin hash
docs/CONTRACT.md Full plugin manifest, hook, and runtime contract
docs/DECLARATIVE_ROOMS.md Declarative room definitions (room.yaml, engine, harness)
docs/DASHBOARD_GUIDE.md Dashboard panel types and metrics authoring
docs/proposals/host-structured-output-and-fanout-state.md Host API proposal motivated by spec-room
GETTING_STARTED.md End-to-end workflow from install to testing