Package Exports
- opencode-orchestrator
Readme
OpenCode Orchestrator 🎯
Enterprise-Grade Autonomous Multi-Agent Plugin for OpenCode
🚀 What's New in v0.6.0
Ultimate Agent Architecture - Production-ready distributed agent orchestration!
| Feature | Description |
|---|---|
| ♾️ Unlimited Mode | No step limits - runs until mission complete |
| 🧠 Anti-Hallucination | Research before coding, verify with docs |
| ⚡ 50x Parallel Sessions | Massive concurrent task execution |
| 📊 Auto Memory Management | GC, archiving, zero memory leaks |
| 🔄 Auto Recovery | Handles rate limits, errors automatically |
| 📡 Event-Driven | Real-time pub/sub across all components |
🏛️ System Architecture
┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ USER REQUEST │
│ (OpenCode Terminal / UI) │
│ │ │
└──────────────────────────────────────────────┼────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ ORCHESTRATOR PLUGIN (src/index.ts) │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Session State │ │ Agent Definitions │ │ Tools Registry │ │ Toast.enable │ │
│ │ Map<sessionId, │ │ (7 agents) │ │ (15+ tools) │ │ AutoToasts() │ │
│ │ {step, maxSteps, │ │ │ │ │ │ → EventBus sub │ │
│ │ timestamp}> │ │ • Commander 🎯 │ │ • call_agent │ │ │ │
│ │ │ │ • Architect 🏗️ │ │ • launch_parallel │ └─────────────────────┘ │
│ │ Cleanup: │ │ • Builder 🔨 │ │ • check_parallel │ │
│ │ session.deleted │ │ • Inspector 🔍 │ │ • webfetch │ ┌─────────────────────┐ │
│ │ → sessions.delete │ │ • Recorder 💾 │ │ • websearch │ │ ProgressTracker │ │
│ │ → Progress.clear │ │ • Librarian 📚 │ │ • grep_search │ │ .startSession() │ │
│ └─────────────────────┘ │ • Researcher 🔬 │ │ • run_background │ │ .recordSnapshot() │ │
│ └─────────────────────┘ └─────────────────────┘ │ .clearSession() │ │
│ └─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ PARENT SESSION (Main Execution Loop) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Commander │───▶│ Architect │───▶│ Builder │───▶│ Inspector │───▶│ Recorder │ │ │
│ │ │ 🎯 │ │ 🏗️ │ │ 🔨 │ │ 🔍 │ │ 💾 │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ Orchestrate │ │ Decompose │ │ Implement │ │ Audit & │ │ Save │ │ │
│ │ │ & delegate │ │ into tasks │ │ code │ │ verify │ │ context │ │ │
│ │ └─────────────┘ └─────────────┘ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │ │
│ │ │ launch_parallel_agent() │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ hooks: "chat.message" / "tool.execute.after" / "handler" │ │ │
│ │ │ │ │ │
│ │ │ chat.message: │ │ │
│ │ │ • Parse /task, /plan slash commands │ │ │
│ │ │ • Auto-start session on Commander agent selection │ │ │
│ │ │ • emit(TASK_EVENTS.STARTED, { taskId, agent }) │ │ │
│ │ │ │ │ │
│ │ │ tool.execute.after: │ │ │
│ │ │ • Check "MISSION COMPLETE" → emit(MISSION_EVENTS.COMPLETE) │ │ │
│ │ │ • Check "/stop" or "/cancel" → emit(TASK_EVENTS.FAILED) │ │ │
│ │ │ • Record ProgressTracker.recordSnapshot() │ │ │
│ │ │ • Inject CONTINUE_INSTRUCTION → client.session.prompt() │ │ │
│ │ │ │ │ │
│ │ │ handler (event): │ │ │
│ │ │ • session.deleted → cleanup sessions, state, ProgressTracker │ │ │
│ │ │ • Pass to ParallelAgentManager.handleEvent() │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────┬───────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ PARALLEL AGENT MANAGER (src/core/agents/manager.ts) │
│ │
│ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ Component Composition │ │
│ │ │ │
│ │ ┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐ │ │
│ │ │ TaskLauncher │ │ TaskResumer │ │ TaskPoller │ │ │
│ │ │ (task-launcher.ts) │ │ (task-resumer.ts) │ │ (task-poller.ts) │ │ │
│ │ │ ───────────────── │ │ ───────────────── │ │ ───────────────── │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ async launch(): │ │ async resume(): │ │ poll() every 1s: │ │ │
│ │ │ 1. await acquire() │ │ 1. Find task │ │ 1. Get running │ │ │
│ │ │ 2. session.create()│ │ 2. session.message │ │ 2. Check events │ │ │
│ │ │ 3. store.set() │ │ 3. Notify parent │ │ 3. If idle+stable │ │ │
│ │ │ 4. emit(STARTED) │ │ │ │ → completed │ │ │
│ │ │ 5. session.message │ └───────────────────────┘ │ 4. emit(COMPLETED) │ │ │
│ │ │ 6. Start poller │ │ 5. scheduleCleanup │ │ │
│ │ │ │ │ │ │ │
│ │ └───────────┬───────────┘ └───────────┬───────────┘ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐ │ │
│ │ │ TaskCleaner │ │ EventHandler │ │ ConcurrencyController │ │ │
│ │ │ (task-cleaner.ts) │ │ (event-handler.ts) │ │ (concurrency.ts) │ │ │
│ │ │ ───────────────── │ │ ───────────────── │ │ ───────────────── │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ pruneExpiredTasks(): │ │ handle(event): │ │ acquire(key): │ │ │
│ │ │ • TTL > 60min │ │ │ │ • limit = 10 │ │ │
│ │ │ → status=timeout │ │ session.idle: │ │ • if < limit │ │ │
│ │ │ → release() │ │ • MIN_STABILITY │ │ → immediate │ │ │
│ │ │ → session.delete() │ │ • validateOutput │ │ • else queue.push │ │ │
│ │ │ │ │ → completed │ │ │ │ │
│ │ │ scheduleCleanup(): │ │ → release() │ │ release(key): │ │ │
│ │ │ • setTimeout 10min │ │ → scheduleClean │ │ • if queue.length │ │ │
│ │ │ → session.delete() │ │ │ │ → queue.shift() │ │ │
│ │ │ → store.delete() │ │ session.deleted: │ │ → next() │ │ │
│ │ │ │ │ → release() │ │ • else count-- │ │ │
│ │ │ notifyParent(): │ │ → store.delete() │ │ │ │ │
│ │ │ → session.prompt() │ │ │ │ getLimit(key): │ │ │
│ │ │ │ └───────────────────────┘ │ • MAX_TOTAL = 50 │ │ │
│ │ └───────────────────────┘ │ • PER_AGENT = 10 │ │ │
│ │ └───────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ TaskStore (task-store.ts) │ │
│ │ │ │
│ │ ┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────────┐ │ │
│ │ │ tasks: Map<id, Task> │ │ pendingByParent: Map │ │ notifications: Map │ │ │
│ │ │ MAX: 1000 │ │ <parentId, Set<taskId>> │ │ <parentId, Task[]> │ │ │
│ │ │ │ │ │ │ MAX: 100/parent │ │ │
│ │ │ set() → auto gc() │ │ trackPending() │ │ │ │ │
│ │ │ getRunning() │ │ untrackPending() │ │ queueNotification() │ │ │
│ │ │ getByParent() │ │ hasPending() │ │ → FIFO eviction │ │ │
│ │ └─────────────────────────┘ └─────────────────────────┘ └─────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ async gc(): │ │ │
│ │ │ • completed > 30min → archiveTasks() → .cache/task-archive/tasks_YYYY-MM-DD.jsonl │ │ │
│ │ │ • error/cancelled > 10min → delete │ │ │
│ │ │ │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ CHILD SESSIONS POOL (up to 50 concurrent) │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │Session 1 │ │Session 2 │ │Session 3 │ │Session 4 │ │Session 5 │ │Session 6 │ │ ... 50 │ │ │
│ │ │ Builder │ │Librarian │ │Researcher│ │Inspector │ │ Builder │ │ Builder │ │ │ │ │
│ │ │ 🔨 │ │ 📚 │ │ 🔬 │ │ 🔍 │ │ 🔨 │ │ 🔨 │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ running │ │ running │ │completed │ │ running │ │ error │ │ pending │ │ │ │ │
│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────────┘ │ │
│ │ │ │ │ │ │ │ │ │
│ │ └────────────┴────────────┴────────────┴────────────┴────────────┘ │ │
│ │ │ │ │
│ └─────────────────────────────────────────┼───────────────────────────────────────────────────────┘ │
│ │ │
└─────────────────────────────────────────────┼──────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ EVENT BUS (src/core/bus/) │
│ │
│ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Event Types (Pub/Sub) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│ │ │task.started │ │task.completed│ │ task.failed │ │session.idle │ │ mission.complete │ │ │
│ │ │ │ │ │ │ │ │session.delete│ │ mission.all_complete│ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ │
│ │ │ │ │ │ │ │ │
│ │ └────────────────┴────────────────┴────────────────┴────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Subscribers │ │ │
│ │ │ │ │ │
│ │ │ Toast.enableAutoToasts(): EventHandler.handle(): │ │ │
│ │ │ • task.started → presets.taskStarted() • release concurrency │ │ │
│ │ │ • task.completed → presets.taskCompleted() • cleanup resources │ │ │
│ │ │ • task.failed → presets.taskFailed() │ │ │
│ │ │ • mission.complete → presets.missionComplete() │ │ │
│ │ │ • document.cached → presets.documentCached() │ │ │
│ │ │ │ │ │
│ │ │ Returns: () => void (unsubscribe function for cleanup) │ │ │
│ │ │ │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ EventBusImpl: │ │ │
│ │ │ • subscribe(type, handler) → unsubscribe fn │ │ │
│ │ │ • publish(type, properties) → Event │ │ │
│ │ │ • emit(type, properties) → void │ │ │
│ │ │ • once(type, handler) → unsubscribe fn │ │ │
│ │ │ • waitFor(type, timeout) → Promise<Event> │ │ │
│ │ │ • history: Event[] (max 100, FIFO) │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────┬───────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ CORE SYSTEMS LAYER │
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ Progress Tracker │ │ Auto Recovery │ │ Document Cache │ │
│ │ (src/core/progress/) │ │ (src/core/recovery/) │ │ (src/core/cache/) │ │
│ │ ────────────────── │ │ ────────────────── │ │ ────────────────── │ │
│ │ │ │ │ │ │ │
│ │ startSession(id) │ │ handleError(context) │ │ get(filename) │ │
│ │ recordSnapshot(id, { │ │ → match patterns │ │ set(filename, content) │ │
│ │ currentStep, │ │ → return action │ │ list() │ │
│ │ maxSteps │ │ │ │ clear(filename) │ │
│ │ }) │ │ Patterns: │ │ cleanExpired() │ │
│ │ formatCompact(id) │ │ • rate_limit │ │ │ │
│ │ clearSession(id) │ │ → retry+backoff │ │ Storage: │ │
│ │ │ │ • context_overflow │ │ .cache/docs/*.md │ │
│ │ Store: │ │ → compact │ │ │ │
│ │ sessions: Map<id, │ │ • network │ │ │ │
│ │ ProgressSnapshot[]> │ │ → retry 3x │ │ │ │
│ │ max 100/session │ │ • parse_error │ │ │ │
│ │ │ │ → skip │ │ │ │
│ └──────────────────────────┘ └──────────────────────────┘ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ Toast Notifier │ │ Async Queue │ │ Background Commands │ │
│ │ (src/core/notification)│ │ (src/core/queue/) │ │ (src/core/commands/) │ │
│ │ ────────────────── │ │ ────────────────── │ │ ────────────────── │ │
│ │ │ │ │ │ │ │
│ │ show({ title, msg }) │ │ workPool(items, fn, │ │ runBackground(cmd) │ │
│ │ │ │ concurrency) │ │ checkBackground(id) │ │
│ │ presets: │ │ workPoolWithResults() │ │ listBackground() │ │
│ │ • taskStarted() │ │ processBatches() │ │ killBackground(id) │ │
│ │ • taskCompleted() │ │ │ │ │ │
│ │ • taskFailed() │ │ retryWithBackoff(fn, │ │ Storage: │ │
│ │ • missionComplete() │ │ maxRetries, delay) │ │ backgroundJobs: Map │ │
│ │ • documentCached() │ │ withTimeout(fn, ms) │ │ <id, BackgroundTask> │ │
│ │ │ │ debounceAsync(fn, ms) │ │ │ │
│ │ enableAutoToasts() │ │ │ │ │ │
│ │ → EventBus.subscribe() │ │ AsyncQueue<T>: │ │ │ │
│ │ → returns disable fn │ │ async iterator │ │ │ │
│ │ │ │ │ │ │ │
│ └──────────────────────────┘ └──────────────────────────┘ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ Shared Context │ │ Task Decomposer │ │ Todo Enforcer │ │
│ │ (src/core/session/) │ │ (src/core/task/) │ │ (src/core/loop/) │ │
│ │ ────────────────── │ │ ────────────────── │ │ ────────────────── │ │
│ │ │ │ │ │ │ │
│ │ create(id, parentId) │ │ create(id, objective) │ │ parseTodos(data) │ │
│ │ get(id) │ │ addTask(id, { │ │ getIncompleteCount() │ │
│ │ getMerged(id) │ │ description, │ │ hasRemainingWork() │ │
│ │ → includes parent ctx │ │ level: 1|2|3, │ │ getNextPending() │ │
│ │ │ │ parallelGroup?, │ │ getStats() │ │
│ │ addDocument(id, doc) │ │ dependsOn? │ │ formatProgress() │ │
│ │ addFinding(id, find) │ │ }) │ │ isMissionComplete() │ │
│ │ addDecision(id, dec) │ │ updateStatus(id, task) │ │ │ │
│ │ │ │ getNextTasks(id) │ │ generateContinuation │ │
│ │ delete(id) │ │ getParallelBatch(id) │ │ Prompt() │ │
│ │ getStats(id) │ │ getSummary(id) │ │ generateCompletion │ │
│ │ │ │ │ │ Message() │ │
│ └──────────────────────────┘ └──────────────────────────┘ └──────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────────────────────────────┘🎯 Key Differentiators
| Capability | OpenCode Orchestrator | Basic Plugins |
|---|---|---|
| Parallel Sessions | Up to 50 concurrent | Single session |
| Memory Management | Auto GC + disk archiving | Memory leaks |
| Error Recovery | Pattern-based auto retry | Crash |
| Context Sharing | Parent-child merge | Isolated |
| Event System | Real-time pub/sub | None |
| Task Decomposition | 3-level hierarchy | Flat |
Installation
npm install -g opencode-orchestratorRestart OpenCode after installation.
Usage
🚀 Two Modes of Operation
| Mode | Trigger | Behavior |
|---|---|---|
| Commander Mode 🎯 | /task "mission" |
Full autonomous execution until MISSION COMPLETE |
| Chat Mode 💬 | Regular conversation | Simple Q&A, no autonomous behavior |
🎯 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
/taskfor anything that requires multiple steps, file changes, or verification. Use Chat Mode for quick questions.
The 7 Agents
| Agent | Role | Responsibility |
|---|---|---|
| Commander 🎯 | Orchestrator | Autonomous mission control |
| Architect 🏗️ | Planner | Hierarchical task decomposition |
| Builder 🔨 | Developer | Full-stack implementation |
| Inspector 🔍 | Quality | Audit, auto-fix & doc verification |
| Recorder 💾 | Context | Progress tracking |
| Librarian 📚 | Research | Documentation & API research |
| Researcher 🔬 | Investigation | Pre-task research & analysis |
🛠️ Available Tools
| Tool | Description |
|---|---|
call_agent |
Call another agent synchronously |
launch_parallel_agent |
Start parallel async session |
check_parallel_task |
Check task status |
collect_parallel_results |
Gather completed results |
webfetch |
Fetch URL content as Markdown |
websearch |
Search web (SearXNG → Brave → DuckDuckGo) |
codesearch |
Search open source code patterns |
cache_docs |
Manage cached documentation |
run_background |
Run command in background |
grep_search / glob_search |
Fast file search |
📊 Resource Guarantees
| Resource | Limit | Safety Mechanism |
|---|---|---|
| Parallel Sessions | 50 | Queue overflow protection |
| Tasks in Memory | 1,000 | Auto GC + disk archive |
| Notifications | 100/parent | FIFO eviction |
| Event History | 100 | Ring buffer |
| Session TTL | 60 min | Auto cleanup |
| Poll Interval | 1 second | Fast completion detection |
🧪 Test Coverage
Test Files: 18 passed
Tests: 211 passed
Duration: ~4.3sUninstall
npm uninstall -g opencode-orchestratorDocumentation
- System Architecture — Detailed technical docs
- OpenCode SDK Reference — API usage reference
- Release Notes — Version history
- Troubleshooting
License
MIT License. LICENSE
Enterprise-scale. Memory-safe. Self-healing. Unlimited.