opencode-orchestrator

opencode-orchestrator

A multi-model orchestrator-worker MCP extension for Opencode with a browser-based dashboard. Routes prompts to specialized worker models with VRAM-aware hot-swapping.

by Specific Labs

Features

• Automatic task routing — orchestrator LLM decomposes prompts into a dependency graph of sub-tasks, each assigned to a specialized worker role
• Specialized workers — each role runs with its own model, temperature, and context window
• VRAM-aware model pool — LRU eviction ensures local models stay within a configurable memory budget; API models bypass the pool
• Speculative preloading — the router predicts the next worker needed and begins loading it during the current step
• Parallel execution — independent steps run concurrently up to a configurable worker limit
• Browser dashboard — full React UI with Blueprint design system (dark theme, live execution monitoring, config management)
• macOS .app launcher — double-click to start the server and open the UI
• Multi-provider — supports Ollama (local), OpenAI-compatible APIs, and Anthropic
• OpenCode MCP integration — also works as a native Goose extension via MCP tools

Default Worker Roles

Role	Default Model	Temp	Optimized For
deep_research	qwen3:32b	0.4	Multi-hop web research, paper analysis
local_rag	qwen3:8b	0.2	Local document retrieval, code search
code_gen	qwen2.5-coder:32b	0.3	Code generation, refactoring, debugging
summarizer	qwen3:8b	0.5	Condensing outputs, report writing
math_reasoning	qwen3:32b	0.1	Formal proofs, calculations, logic
creative	llama3:70b	0.9	Creative writing, brainstorming

All roles are fully customizable via the UI or MCP tools.

Quick Start

Prerequisites

• Python 3.12+
• uv
• Node.js 18+ (for frontend build)
• Ollama and/or API keys for OpenAI/Anthropic

Install & Run (Browser UI)

git clone https://github.com/santiagoaraoz2001-sketch/opencode-orchestrator.git
cd opencode-orchestrator

# Build everything
uv sync
cd frontend && npm install && npm run build && cd ..

# Launch (opens browser to http://localhost:7432)
uv run opencode-orchestrator-ui

macOS App (one-click launcher)

bash build-app.sh
cp -r "dist/OpenCode Orchestrator.app" /Applications/

Then launch from Spotlight or your Applications folder.

OpenCode MCP Extension

Add to ~/.config/goose/config.yaml:

extensions:
  multi_model_orchestrator:
    enabled: true
    type: stdio
    name: Multi-Model Orchestrator
    cmd: uv
    args:
      - run
      - --project
      - /path/to/opencode-orchestrator
      - opencode-orchestrator
    timeout: 600

Architecture

User Prompt → Orchestrator LLM (task classification)
                    ↓
            Task Plan (dependency graph)
                    ↓
        ┌───────────┼───────────┐
        ↓           ↓           ↓
    Worker A      Worker B      Worker C      (parallel)
   (research)    (code_gen)    (summarizer)
        ↓           ↓           ↓
        └───────────┼───────────┘
                    ↓
           Assembled Response

The Model Pool enforces a strict VRAM budget with LRU eviction. The orchestrator model is pinned and never evicted. API-backed models have zero local VRAM cost.

API Endpoints

Method	Path	Description
GET	/api/config	Full configuration
PATCH	/api/config/orchestrator	Update orchestrator model
GET	/api/config/workers	List all worker roles
PATCH	/api/config/workers/{role}	Update a worker role
POST	/api/config/workers/{role}	Create a worker role
DELETE	/api/config/workers/{role}	Remove a worker role
PATCH	/api/config/resources	Update resource limits
GET	/api/status	Model pool status
POST	/api/orchestrate	Run orchestration (REST)
WS	/api/ws	Live execution streaming
GET	/api/models/{provider}	List available models

Development

# Backend (hot-reload)
uv run uvicorn opencode_orchestrator.backend.app:app --reload --port 7432

# Frontend (Vite dev server with proxy)
cd frontend && npm run dev

# Tests
uv run --extra dev pytest tests/ -v

License

MIT