docs بواسطة 0xSero/orchestra

Spawn, manage, and coordinate specialized AI workers in OpenCode

Overview

Open Orchestra is a monorepo that ships the orchestrator plugin, control panel, and desktop shell for OpenCode.

Repo in 10 minutes

Mental model:

Workers: orchestrator-managed runtimes that do the work.
Workflows: multi-step plans the orchestrator runs across workers.
Memory: persistent records written by workflows and tools.

The 3 commands:

bun run dev — developer loop (plugin watch + control panel)
bun run build — release build (plugin + app + desktop)
opencode + plugin install — user flow (add opencode-orchestrator to OpenCode config)

Open Orchestra is a multi-agent orchestration plugin for OpenCode that enables you to spawn, manage, and coordinate specialized AI workers. It implements a hub-and-spoke architecture where a central orchestrator coordinates multiple specialized workers, each optimized for specific tasks.

Why Multiple AI Workers?

Instead of asking one AI to do everything, Open Orchestra lets you use specialized workers:

Worker	Best For	Example
Vision	Analyzing screenshots, images, UI mockups	"What error is shown in this screenshot?"
Docs	Researching APIs, finding examples	"How do I use React's useEffect hook?"
Coder	Writing and modifying code	"Implement this feature"
Architect	System design, planning (read-only)	"Review this architecture"

This specialization means better results, clearer reasoning, and the ability to run tasks in parallel.

Prerequisites

Before installing Open Orchestra, verify you have:

Requirement	Check Command	Expected
Bun runtime	`bun --version`	1.0.0 or higher
OpenCode CLI	`opencode --version`	Any recent version
AI Provider	`orchestrator.models` (in OpenCode)	At least one model listed

Quick verification:

bun --version && opencode --version

Need to configure a provider? Add to ~/.config/opencode/opencode.json:

{
  "provider": {
    "anthropic": {
      "apiKey": "sk-ant-your-key-here"
    }
  }
}

See the Quickstart Guide for detailed setup instructions.

Key Features

6 Built-in Worker Profiles - Vision, Docs, Coder, Architect, Explorer, Memory
Hub-and-Spoke Architecture - Central orchestrator with specialized workers
5-tool Async Task API - Start/await/peek/list/cancel tasks (workers + workflows)
Profile-Based Spawning - Auto-model resolution from OpenCode config
Dynamic Port Allocation - Avoids conflicts with automatic port assignment
Session-Based Isolation - Each worker maintains its own conversation context
Optional Neo4j Memory - Persistent knowledge graph (advanced feature)

Architecture

Open Orchestra follows a hub-and-spoke pattern inspired by successful multi-agent systems like AutoGen and LangGraph, but optimized for OpenCode's plugin architecture.

graph TB
    subgraph Orchestrator["Open Orchestra Hub"]
        Registry["Worker Registry"]
        Config["Config Loader"]
        Tools["Tool APIs"]
    end
    
    subgraph Workers["Specialized Workers"]
        Vision["Vision Worker<br/><small>Image Analysis, OCR</small>"]
        Docs["Docs Worker<br/><small>Research, Citations</small>"]
        Coder["Coder Worker<br/><small>Implementation</small>"]
        Architect["Architect Worker<br/><small>System Design</small>"]
        Explorer["Explorer Worker<br/><small>Fast Search</small>"]
        Memory["Memory Worker<br/><small>Knowledge Graph</small>"]
    end
    
    subgraph Storage["Persistence"]
        Neo4j["Neo4j Graph DB"]
        ConfigFiles["orchestrator.json"]
    end
    
    Orchestrator --> Vision
    Orchestrator --> Docs
    Orchestrator --> Coder
    Orchestrator --> Architect
    Orchestrator --> Explorer
    Orchestrator --> Memory
    
    Memory --> Neo4j
    Config --> ConfigFiles
    
    style Orchestrator fill:#6495ED,stroke:#2F4F8F,color:#fff
    style Vision fill:#FFD700,stroke:#CC8400
    style Docs fill:#FFD700,stroke:#CC8400
    style Coder fill:#FFD700,stroke:#CC8400
    style Architect fill:#FFD700,stroke:#CC8400
    style Explorer fill:#FFD700,stroke:#CC8400
    style Memory fill:#FFD700,stroke:#CC8400

Quick Start

Installation

# Add to your project
bun add opencode-orchestrator

# Or install globally
bun add -g opencode-orchestrator

Configuration

1. Add the plugin to OpenCode:

// opencode.json or ~/.config/opencode/opencode.json
{
  "plugin": ["opencode-orchestrator"]
}

2. Create orchestrator config (optional - auto-setup available):

// .opencode/orchestrator.json or orchestrator.json
{
  "$schema": "./node_modules/opencode-orchestrator/schema/orchestrator.schema.json",
  "autoSpawn": true,
  "workers": ["vision", "docs", "coder"]
}

Basic Usage

sequenceDiagram
    participant User
    participant Orchestrator
    participant Vision as Vision Worker
    participant Coder as Coder Worker
    
    User->>Orchestrator: "Fix the bug shown in this screenshot"
    Orchestrator->>Vision: analyze_image(screenshot)
    Vision-->>Orchestrator: "Error on line 42: undefined is not a function"
    Orchestrator->>Coder: fix_bug(file, line 42)
    Coder-->>Orchestrator: "Fixed: added null check"
    Orchestrator-->>User: "Bug fixed - added null check on line 42"

Start tasks (async):

task_start({ kind: "worker", workerId: "vision", task: "What's in this image?", attachments: [...] })
task_await({ taskId: "<taskId>" })

Auto-route tasks:

task_start({ kind: "auto", task: "Find the official React hooks documentation" })
task_await({ taskId: "<taskId>" })

Workflows

Workflows run multi-step sequences with security limits:

task_list({ view: "workflows", format: "markdown" })
task_start({ kind: "workflow", workflowId: "roocode-boomerang", task: "Implement the new workflow tools" })
task_await({ taskId: "<taskId>" })

Resume a paused run:

task_start({ kind: "workflow", continueRunId: "<runId>", task: "continue workflow" })
task_await({ taskId: "<taskId>" })

Command shortcuts:

orchestrator.workflows
orchestrator.boomerang

Built-in Profiles

Profile	Model Tag	Vision	Web	Purpose
`vision`	`auto:vision`	Yes	No	Image analysis, OCR, UI review
`docs`	`auto:docs`	No	Yes	Documentation research, examples, citations
`coder`	`auto`	No	No	Code implementation, file operations
`architect`	`auto`	No	No	System design, planning (read-only)
`explorer`	`auto:fast`	No	No	Fast codebase searches
`memory`	`auto`	No	Yes	Neo4j memory graph, context pruning

Worker Lifecycle

stateDiagram-v2
    [*] --> Starting: task_start(kind="worker")
    Starting --> Ready: initialized
    Ready --> Busy: task assigned
    Busy --> Ready: task complete
    Ready --> Stopped: shutdown
    Busy --> Error: failure
    Error --> Ready: recovery
    Stopped --> [*]

Documentation

Getting Started

Quickstart - Your first worker in 5 minutes
Examples - Real-world use cases and workflows
Troubleshooting - Common issues and fixes

Reference

Configuration - Complete configuration reference
Guide - Profiles, workflows, and advanced features
Tool Reference - All tools with examples

Deep Dive

Architecture - System design and patterns
CHANGELOG - Version history and changes

Tools

Tool	Description
`task_start`	Start a worker/workflow task (async; returns `taskId`)
`task_await`	Wait for a task to finish (returns final job record)
`task_peek`	Inspect task status without waiting
`task_list`	List recent tasks (plus other views)
`task_cancel`	Cancel a running task (best-effort)

Commands

Command	Description
`orchestrator.status`	Show workers, profiles, and config
`orchestrator.models`	List available models
`orchestrator.profiles`	List worker profiles
`orchestrator.workers`	List running workers
`orchestrator.output`	Show recent tasks + logs
`orchestrator.workflows`	List workflows
`orchestrator.boomerang`	Run the RooCode boomerang workflow

Advanced: Memory System (Optional)

Open Orchestra includes an optional Neo4j-backed memory system for persistent knowledge storage. See the memory section in Guide for setup instructions.

Development

See docs/standards.md for engineering standards and docs/testing.md for test tiers and CI behavior.

# Install dependencies
bun install
cd app && bun install
cd desktop && bun install

# Run the full quality gate
bun run check

Project Structure

opencode-orchestrator/
├── bin/
│   └── worker-bridge-plugin.mjs
├── src/
│   ├── index.ts              # Plugin entry point
│   ├── command/
│   │   ├── index.ts          # Tool registry
│   │   └── tasks.ts          # Task API tools (5-tool surface)
│   ├── config/
│   │   ├── orchestrator.ts   # Config loading/merging
│   │   └── profiles.ts       # Built-in worker profiles
│   ├── core/
│   │   ├── runtime.ts        # Runtime lifecycle
│   │   └── worker-pool.ts    # Worker registry + pooling
│   ├── memory/
│   │   ├── graph.ts          # Memory graph operations
│   │   └── neo4j.ts          # Neo4j connection
│   ├── models/
│   │   ├── catalog.ts        # Model catalog utilities
│   │   └── hydrate.ts        # Model resolution
│   ├── types/
│   │   └── index.ts          # TypeScript definitions
│   ├── ux/
│   │   ├── idle-notification.ts
│   │   └── pruning.ts        # Context pruning
│   └── workers/
│       ├── prompt.ts         # Prompt building
│       └── spawner.ts        # Worker lifecycle
├── schema/
│   └── orchestrator.schema.json
├── docs/
│   ├── architecture.md
│   ├── guide.md
│   └── reference.md
└── test/
    ├── e2e.test.ts
    └── orchestrator.test.ts

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and submit PRs to the main branch.

License

MIT - see LICENSE for details.

Built for OpenCode with orchestration patterns inspired by multi-agent systems research.

docs