OpenCode Orchestrator

Autonomous multi-agent plugin for OpenCode

Overview

Multi-agent system that autonomously executes complex tasks. Commander delegates work to specialized agents, manages parallel execution, and maintains shared context.

🏛️ System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           👤 USER REQUEST                                   │
│                        OpenCode Terminal / UI                               │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        🔌 ORCHESTRATOR PLUGIN                               │
│                                                                             │
│  ┌─────────────────┐  ┌─────────────────────────────────────────────────┐  │
│  │  Session State  │  │                   7 AGENTS                      │  │
│  │  Map<id,state>  │  │  🎯 Commander (primary)                         │  │
│  └─────────────────┘  │     ↓ delegate_task / OpenCode Task tool        │  │
│                       │  🏗️ Architect  🔨 Builder  🔍 Inspector         │  │
│  ┌─────────────────┐  │  💾 Recorder   📚 Librarian 🔬 Researcher       │  │
│  │  Plugin Hooks   │  │     (subagents, hidden)                         │  │
│  │  config         │  └─────────────────────────────────────────────────┘  │
│  │  chat.message   │                                                       │
│  │  tool.execute   │  ┌─────────────────────────────────────────────────┐  │
│  └─────────────────┘  │                  12 TOOLS                       │  │
│                       │  delegate_task    get_task_result   list_tasks  │  │
│                       │  webfetch         websearch         codesearch  │  │
│                       │  run_background   grep_search       mgrep       │  │
│                       └─────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      ⚙️ PARALLEL AGENT MANAGER                              │
│                                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────────────────────┐   │
│  │ TaskLauncher │  │  TaskPoller  │  │    ConcurrencyController        │   │
│  │   launch()   │  │   poll()     │  │    MAX=50, PER_AGENT=10         │   │
│  └──────────────┘  └──────────────┘  └─────────────────────────────────┘   │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    TaskStore (MAX: 1000 tasks)                      │   │
│  │    pending → running → completed/error → archived (disk)            │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                       🔄 CHILD SESSIONS POOL (up to 50)                     │
│                                                                             │
│    Session 1        Session 2        Session 3            Session N         │
│    Builder 🔨       Librarian 📚     Inspector 🔍         ...               │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                       📁 SMART CONTEXT (.opencode/)                         │
│                                                                             │
│    .opencode/todo.md    - Master TODO list (Recorder manages)               │
│    .opencode/context.md - Adaptive size based on project phase              │
│    .opencode/docs/      - Cached documentation (auto-cleanup)               │
│    .opencode/archive/   - Old context for reference                         │
└─────────────────────────────────────────────────────────────────────────────┘

Installation

npm install -g opencode-orchestrator

Restart OpenCode after installation.

Usage

🚀 Two Modes of Operation

🎯 Commander Mode - /task (Recommended for Real Work)

Use /task when you need the AI to complete a mission autonomously:

/task "Fix the login bug in the docker-compose environment"
/task "Add dark mode support to the entire app"
/task "Refactor the API to use TypeScript"

What Commander Mode Does:

• ♾️ Runs until done — Never stops until "MISSION COMPLETE"
• 🧠 Anti-Hallucination — Researches docs before coding
• ⚡ Parallel Execution — Up to 50 concurrent agents
• 🔄 Auto-Recovery — Handles errors automatically
• 📊 Trriage System — Adapts strategy to complexity (L1/L2/L3)

_{/task "mission" triggers full Commander mode}

💬 Chat Mode - Regular Conversation (Simple Q&A)

Just type normally without /task for simple questions:

How do I add a loading spinner?
What's the difference between useState and useReducer?

Chat Mode is just regular conversation — no autonomous execution, no parallel agents, no mission tracking.

💡 Pro Tip: Use /task for anything that requires multiple steps, file changes, or verification. Use Chat Mode for quick questions.

The 7 Agents

🛠️ Available Tools

📊 Resource Guarantees

🧪 Test Coverage

Test Files:  18 passed
Tests:       198 passed
Duration:    ~4.3s

Uninstall

npm uninstall -g opencode-orchestrator

🔧 Debugging

Log file location:

# Find log path (macOS uses /var/folders/...)
npm run log
# or:
tail -f "$(node -e 'console.log(require("os").tmpdir())')/opencode-orchestrator.log"

# Windows
# C:\Users\<username>\AppData\Local\Temp\opencode-orchestrator.log

Documentation

• System Architecture — Detailed technical docs
• OpenCode SDK Reference — API usage reference
• Release Notes — Version history
• Troubleshooting

License

MIT License. LICENSE