---
slug: "orchestra"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/0xSero/orchestra@main/README.md"
repo: "https://github.com/0xSero/orchestra"
source_file: "README.md"
branch: "main"
---
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](https://opencode.ai) 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:**
```bash
bun --version && opencode --version
```
**Need to configure a provider?** Add to `~/.config/opencode/opencode.json`:
```json
{
"provider": {
"anthropic": {
"apiKey": "sk-ant-your-key-here"
}
}
}
```
See the [Quickstart Guide](https://github.com/0xSero/orchestra/blob/HEAD/docs/quickstart.md) 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.
```mermaid
graph TB
subgraph Orchestrator["Open Orchestra Hub"]
Registry["Worker Registry"]
Config["Config Loader"]
Tools["Tool APIs"]
end
subgraph Workers["Specialized Workers"]
Vision["Vision Worker
Image Analysis, OCR"]
Docs["Docs Worker
Research, Citations"]
Coder["Coder Worker
Implementation"]
Architect["Architect Worker
System Design"]
Explorer["Explorer Worker
Fast Search"]
Memory["Memory Worker
Knowledge Graph"]
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
```bash
# Add to your project
bun add opencode-orchestrator
# Or install globally
bun add -g opencode-orchestrator
```
### Configuration
**1. Add the plugin to OpenCode:**
```json
// opencode.json or ~/.config/opencode/opencode.json
{
"plugin": ["opencode-orchestrator"]
}
```
**2. Create orchestrator config (optional - auto-setup available):**
```json
// .opencode/orchestrator.json or orchestrator.json
{
"$schema": "./node_modules/opencode-orchestrator/schema/orchestrator.schema.json",
"autoSpawn": true,
"workers": ["vision", "docs", "coder"]
}
```
### Basic Usage
```mermaid
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):**
```bash
task_start({ kind: "worker", workerId: "vision", task: "What's in this image?", attachments: [...] })
task_await({ taskId: "" })
```
**Auto-route tasks:**
```bash
task_start({ kind: "auto", task: "Find the official React hooks documentation" })
task_await({ taskId: "" })
```
## Workflows
Workflows run multi-step sequences with security limits:
```bash
task_list({ view: "workflows", format: "markdown" })
task_start({ kind: "workflow", workflowId: "roocode-boomerang", task: "Implement the new workflow tools" })
task_await({ taskId: "" })
```
Resume a paused run:
```bash
task_start({ kind: "workflow", continueRunId: "", task: "continue workflow" })
task_await({ 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
```mermaid
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](https://github.com/0xSero/orchestra/blob/HEAD/docs/quickstart.md) - Your first worker in 5 minutes
- [Examples](https://github.com/0xSero/orchestra/blob/HEAD/docs/examples.md) - Real-world use cases and workflows
- [Troubleshooting](https://github.com/0xSero/orchestra/blob/HEAD/docs/troubleshooting.md) - Common issues and fixes
### Reference
- [Configuration](https://github.com/0xSero/orchestra/blob/HEAD/docs/configuration.md) - Complete configuration reference
- [Guide](https://github.com/0xSero/orchestra/blob/HEAD/docs/guide.md) - Profiles, workflows, and advanced features
- [Tool Reference](https://github.com/0xSero/orchestra/blob/HEAD/docs/reference.md) - All tools with examples
### Deep Dive
- [Architecture](https://github.com/0xSero/orchestra/blob/HEAD/docs/architecture.md) - System design and patterns
- [CHANGELOG](https://github.com/0xSero/orchestra/blob/HEAD/CHANGELOG.md) - 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](https://github.com/0xSero/orchestra/blob/HEAD/docs/guide.md) for setup instructions.
## Development
See [docs/standards.md](https://github.com/0xSero/orchestra/blob/HEAD/docs/standards.md) for engineering standards and [docs/testing.md](https://github.com/0xSero/orchestra/blob/HEAD/docs/testing.md) for test tiers and CI behavior.
```bash
# 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](https://github.com/0xSero/orchestra/blob/HEAD/CONTRIBUTING.md) and submit PRs to the `main` branch.
## License
MIT - see [LICENSE](https://github.com/0xSero/orchestra/tree/HEAD/LICENSE) for details.
---
Built for OpenCode with orchestration patterns inspired by multi-agent systems research.