Skip to content

0xSero/orchestra

BranchesTags

Repository files navigation

HUB Open Orchestra Multi-Agent Orchestration for OpenCode

Version License Bun OpenCode

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
Loading

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"
Loading

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 --> [*]
Loading

Documentation

Getting Started

Reference

Deep Dive

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.

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing
Activity

Stars

213 stars

Watchers

1 watching

Forks

12 forks
Report repository

Releases 3

v0.2.3 - Architecture Simplification & Vision Auto-Routing Latest
Dec 23, 2025
+ 2 releases

Packages

No packages published

Contributors 2

Languages