KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #ai-agent #codex #ai-agents #deepseek-harness #claude-code #cli #react #mcp

orchestra

★ 278 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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](./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: "<taskId>" })
```

**Auto-route tasks:**
```bash
task_start({ kind: "auto", task: "Find the official React hooks documentation" })
task_await({ taskId: "<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: "<taskId>" })
```

Resume a paused run:

```bash
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

```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](./docs/quickstart.md) - Your first worker in 5 minutes
- [Examples](./docs/examples.md) - Real-world use cases and workflows
- [Troubleshooting](./docs/troubleshooting.md) - Common issues and fixes

### Reference
- [Configuration](./docs/configuration.md) - Complete configuration reference
- [Guide](./docs/guide.md) - Profiles, workflows, and advanced features
- [Tool Reference](./docs/reference.md) - All tools with examples

### Deep Dive
- [Architecture](./docs/architecture.md) - System design and patterns
- [CHANGELOG](./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](./docs/guide.md) for setup instructions.

## Development

See [docs/standards.md](./docs/standards.md) for engineering standards and [docs/testing.md](./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](./CONTRIBUTING.md) and submit PRs to the `main` branch.

## License

MIT - see [LICENSE](./LICENSE) for details.

---

Built for <a href="https://opencode.ai">OpenCode</a> with orchestration patterns inspired by multi-agent systems research.

orchestra

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README