Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/agnusdei1207/opencode-orchestrator

Opencode Plugin for AI-Agent Orchestration
https://github.com/agnusdei1207/opencode-orchestrator

ai-orchestration opencode rust

Last synced: 2 days ago
JSON representation

Opencode Plugin for AI-Agent Orchestration

Awesome Lists containing this project

README 

          

---





  logo

  
OpenCode Orchestrator


  
Production-Grade Multi-Agent Orchestration Engine for High-Integrity Software Engineering



  [![MIT License](https://img.shields.io/badge/license-MIT-red.svg)](LICENSE)

  [![npm](https://img.shields.io/npm/v/opencode-orchestrator.svg)](https://www.npmjs.com/package/opencode-orchestrator)

  

  **Version:** `1.3.1`

  




---



## ⚡ Quick Start



```bash

npm install -g opencode-orchestrator

```



Install hooks are source-checkout safe, prefer `opencode.jsonc` when present, preserve sibling plugin entries, and skip automatic config mutation in CI environments.



To remove the plugin safely later, run:



```bash

npm explore -g opencode-orchestrator -- npm run cleanup:plugin

npm uninstall -g opencode-orchestrator

```



`npm uninstall -g` does not run dependency uninstall hooks in the npm 11 flow verified for this repo, so config cleanup is explicit.



Inside an OpenCode environment:

```bash

/task "Implement a new authentication module with JWT and audit logs"

```



---



## 🚀 Engine Workflow



**Hub-and-Spoke Architecture** with Work-Stealing Queues for parallel, context-isolated task execution.

```

╔══════════════════════════════════════════════════════════════════════════════╗

║                           USER INPUT /task "..."                              ║

╚══════════════════════════════════════════════════════════════════════════════╝

                                         │

                                         ▼

╔══════════════════════════════════════════════════════════════════════════════╗

║  ┌─────────────────────────────────────────────────────────────────────────┐ ║

║  │                            C O M M A N D E R                           │ ║

║  │                    [ Mission Analysis & Delegation ]                    │ ║

║  │                                                                          │ ║

║  │    • Interprets user intent    • Coordinates multi-agent workflow      │ ║

║  │    • Monitors progress          • Manages work-stealing queues         │ ║

║  └─────────────────────────────────────────────────────────────────────────┘ ║

╚══════════════════════════════════════════════════════════════════════════════╝

                                         │

                         ┌───────────────┼───────────────┐

                         ▼               ▼               ▼

╔═════════════════╗  ╔═════════════════╗  ╔═════════════════╗

║   P L A N N E R ║  ║     W O R K E R ║  ║    W O R K E R   ║

║  [Architect]    ║  ║  [Implementer]  ║  ║  [Implementer]   ║

║                 ║  ║                 ║  ║                 ║

║  • Dependency   ║  ║  • File coding ║  ║  • File coding  ║

║    analysis     ║  ║  • TDD workflow ║  ║  • TDD workflow ║

║  • Roadmap gen ║  ║  • Documentation║  ║  • Documentation║

║  • TODO.md      ║  ║                 ║  ║                 ║

╚═════════════════╝  ╚═════════════════╝  ╚═════════════════╝

         │                   │                     │

         │    ┌──────────────┼─────────────────────┘

         │    │              │

         ▼    ▼              ▼

╔══════════════════════════════════════╗

║         SESSION POOL (MVCC Sync)   ║

║   ┌─────────────────────────────────┐ ║

║   │  Object Pool │ Buffer Pool      │ ║

║   │  String Pool │ Connection Pool  │ ║

║   └─────────────────────────────────┘ ║

╚══════════════════════════════════════╝

         │

         ▼

╔══════════════════════════════════════╗

║       MSVP MONITOR / REVIEWER       ║

║  ┌─────────────────────────────────┐ ║

║  │  • Adaptive polling (500ms-5s) │ ║

║  │  • Stability detection         │ ║

║  │  • Unit test verification      │ ║

║  └─────────────────────────────────┘ ║

╚══════════════════════════════════════╝

                 │

                 ▼

        ┌────────────────┐

        │  ✨ COMPLETED  │

        └────────────────┘

```



---



## 🏗️ Architecture Layers



```

┌─────────────────────────────────────────────────────────────────────────────┐

│                           PRESENTATION LAYER                                │

│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │

│  │ Task Toast  │  │ Progress    │  │ Notification│  │ Mission Summary │  │

│  │ Manager     │  │ Notifier    │  │ Manager     │  │ Display         │  │

│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────┘  │

├─────────────────────────────────────────────────────────────────────────────┤

│                           BUSINESS LOGIC LAYER                              │

│  ┌───────────────────────────────────────────────────────────────────────┐  │

│  │                    Parallel Agent Orchestration                        │  │

│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────────┐  │  │

│  │  │ Commander  │  │  Planner   │  │  Worker    │  │   Reviewer     │  │  │

│  │  │   Agent    │  │   Agent    │  │   Agent    │  │     Agent      │  │  │

│  │  └────────────┘  └────────────┘  └────────────┘  └────────────────┘  │  │

│  └───────────────────────────────────────────────────────────────────────┘  │

│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐│

│  │ Concurrency     │  │   Task Store   │  │    Hook System              ││

│  │ Controller      │  │   (In-Memory)  │  │  [Early/Normal/Late Phases] ││

│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘│

├─────────────────────────────────────────────────────────────────────────────┤

│                           INFRASTRUCTURE LAYER                              │

│  ┌────────────────┐  ┌────────────────┐  ┌────────────────────────────┐  │

│  │ Session Pool   │  │ Work-Stealing  │  │    Memory Pools           │  │

│  │ [5 per agent]  │  │ [Chase-Lev]    │  │  ┌──────┐ ┌──────┐ ┌─────┐│  │

│  │ [10 reuse max] │  │ [LIFO/FIFO]    │  │  │Object│ │String│ │Buffer││  │

│  └────────────────┘  └────────────────┘  │  │ 200  │ │ intern│ │ 4KB ││  │

│                                          │  └──────┘ └──────┘ └─────┘│  │

│  ┌────────────────┐  ┌────────────────┐  └────────────────────────────┘  │

│  │ MVCC State     │  │ Circuit Breaker │  ┌────────────────────────────┐  │

│  │ [Atomic Sync]  │  │ [5 failures→open│  │ Rust Connection Pool     │  │

│  │                │  │  [2 success→close│ │ [4 processes, 30s idle]   │  │

│  └────────────────┘  └────────────────┘  └────────────────────────────┘  │

├─────────────────────────────────────────────────────────────────────────────┤

│                           SAFETY LAYER                                      │

│  ┌────────────────┐  ┌────────────────┐  ┌─────────────────────────────┐ │

│  │ RAII Pattern   │  │ Shutdown       │  │ Auto-Recovery               │ │

│  │ [Zero Leaks]   │  │ Manager        │  │ [Exponential Backoff]       │ │

│  │                │  │ [5s timeout]   │  │ [Rate limit handling]       │ │

│  └────────────────┘  └────────────────┘  └─────────────────────────────┘ │

└─────────────────────────────────────────────────────────────────────────────┘

```



---



## 🧪 Test Utilities



Reusable test helpers keep filesystem, task, and process-heavy flows deterministic:



```

tests/harness/

├── fixture.ts          Disposable tmpdir utilities

│   ├── tmpdir()        async disposable with cleanup

│   ├── tmpdirSync()    sync disposable with cleanup  

│   ├── createMockFs()  In-memory fs mock

│   └── waitFor()       Async condition waiter

│

├── builders.ts         Factory functions for test objects

│   ├── createParallelTask()    Build ParallelTask instances

│   ├── createBackgroundTask()  Build BackgroundTask instances

│   └── createTodo()            Build Todo instances

│

├── mocks.ts           Mock utilities

│   ├── mockConsole()         Spy on console.log/error

│   ├── mockProcessExit()     Mock process.exit

│   ├── useFakeTimers()       Time manipulation

│   └── createMockEmitter()   EventEmitter spy

│

└── index.ts           Unified exports

```



### Usage Example



```typescript

import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";



describe("My test", () => {

  let consoleMock;



  beforeEach(() => {

    consoleMock = mockConsole();

    consoleMock.setup();

  });



  afterEach(() => {

    consoleMock.restore();

  });



  it("should work", async () => {

    await using tmp = await tmpdir({ git: true });

    const task = createParallelTask({ description: "Test" });

    expect(task.status).toBe("pending");

  });

});

```



---



## ⚡ Elite Multi-Agent Swarm



| Agent | Role | Core Responsibilities |

|:------|:-----|:------------------------|

| **Commander** | Mission Hub | Task decomposition, agent coordination, work-stealing orchestration, final mission seal |

| **Planner** | Architect | Dependency analysis, roadmap generation, TODO.md creation via MVCC, file-level planning |

| **Worker** | Implementer | High-throughput coding, TDD workflow, documentation, isolated file execution |

| **Reviewer** | Auditor | Unit test verification, LSP/Lint validation, integration testing, quality gate |

---



## 🛠️ Core Capabilities



### 🔒 Atomic MVCC State Synchronization

Solves the "Concurrent TODO Update" problem using **MVCC + Mutex**. Agents safely mark tasks complete in parallel without data loss or race conditions. Every state change is cryptographically hashed and logged.



### 🧩 Advanced Hook Orchestration

Execution flows governed by a **Priority-Phase Hook Registry**. Hooks are grouped into phases (`early`, `normal`, `late`) and executed via **Topological Sort** for predictable, dependency-aware ordering.



### 🛡️ Autonomous Recovery

- **Self-healing loops** with adaptive stagnation detection

- **Proactive Agency**: Smart monitoring that audits logs and plans ahead during background tasks

- **Auto-retry with backoff**: Exponential backoff for transient failures



### 🎯 State-Level Session Isolation

Reused sessions in the **SessionPool** are explicitly reset via server-side compaction, ensuring previous task context never leaks into new tasks.



### 🚀 Zero-Payload Turbo Mode

Leverages `system.transform` to unshift agent instruction sets server-side, reducing initial message payloads by **90%+** and preventing context fragmentation.



### 🧠 Hierarchical Memory System

Maintains focus across thousands of conversation turns using a 4-tier memory structure with **EMA-based Context Gating** to preserve architectural truth while pruning noise.



### 🔄 Adaptive Intelligence Loop

- **Stagnation Detection**: Senses when no progress is made across iterations

- **Diagnostic Intervention**: Forces "Diagnostic Mode" mandating log audits and strategy pivots

- **Proactive Agency**: Mandates Speculative Planning during background task execution



### 🧬 Knowledge Graph RAG (Second Brain)

An autonomous **Obsidian-style evolutionary memory system** that gives agents persistent, searchable knowledge across sessions.



```

  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐

  │  📝 Ingest   │────▶│  🔍 Search   │────▶│  🧠 Recall   │

  │  ──────────  │     │  ──────────  │     │  ──────────  │

  │  YAML Parser │     │  BM25 Lexical│     │  RRF-Ranked  │

  │  Tag HashMap │     │  Tag Index   │     │  Top-K Notes │

  │  Wiki-Links  │     │  2-Hop Graph │     │  → Context   │

  └──────┬───────┘     └──────────────┘     └──────────────┘

         │

         ▼

  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐

  │  🔄 Evolve   │────▶│  🛡️ Guard    │────▶│  📦 Archive  │

  │  ──────────  │     │  ──────────  │     │  ──────────  │

  │  Fission     │     │  Cycle DFS   │     │  Orphan GC   │

  │  Fusion      │     │  Write FIFO  │     │  MOC Hubs    │

  │  (Auto-Split │     │  Keep-Pin    │     │  MD Export   │

  │   & Merge)   │     │  Shield      │     │              │

  └──────────────┘     └──────────────┘     └──────────────┘

```



**Six integrated modules** power the knowledge pipeline:



| Module | Purpose |

|:-------|:--------|

| **TagIndexer** | O(1) YAML frontmatter parsing → tag-to-file HashMap |

| **GraphParser** | `[[wiki-link]]` extraction, bi-directional adjacency graph |

| **HybridSearch** | BM25 + Tag + 2-Hop Graph → **Reciprocal Rank Fusion** (k=60) |

| **Scratchpad** | LRU register cache (64 slots, 4KB max) with markdown persistence |

| **SafetyGuards** | Circular link DFS, async FIFO write queue, keep-pin shield |

| **MemoryConsolidation** | Fission/Fusion/GC/MOC — pure functional analysis |



---



## ⚙️ Performance Benchmarks



| Metric | Improvement |

|:-------|:------------|

| CPU Utilization | 90%+ (up from 50-70%) |

| Tool Call Speed | 10x faster (5-10ms vs 50-100ms) via Rust pool |

| Session Creation | 90% faster (50ms vs 500ms) via session pooling |

| Memory Usage | 60% reduction via object/string/buffer pooling |

| GC Pressure | 80% reduction |

| Token Efficiency | 40% reduction via Incremental State & System Transform |

| Sync Accuracy | 99.95% via MVCC+Mutex |

| Parallel Efficiency | 80% improvement (50% → 90%+) |



---



## 🏗️ Infrastructure & Reliability



### Resource Safety

- **RAII Pattern**: Guaranteed resource cleanup with zero leaks

- **ShutdownManager**: Priority-based graceful shutdown (5s timeout per handler)

- **Atomic File Operations**: Temp file + rename for corruption-proof writes

- **Automatic Backups**: Timestamped config backups with rollback support



### Safety Features

- **Circuit Breaker**: Auto-recovery from API failures (5 failures → open)

- **Resource Pressure Detection**: Rejects low-priority tasks when memory > 80%

- **Terminal Node Guard**: Prevents infinite recursion via depth limit

- **Auto-Scaling**: Concurrency slots adjust based on success/failure rate



### Technical Stack

- **Runtime**: Node.js 18+ (TypeScript)

- **Tools**: Rust-based CLI tools (grep, glob, ast) via connection pool

- **Concurrency**: Chase-Lev work-stealing deque + priority queues

- **Memory**: Object pooling + string interning + buffer pooling

- **State Management**: MVCC + Mutex

- **Safety**: RAII + circuit breaker + resource pressure detection

- **Knowledge**: In-memory graph RAG with BM25/Tag/Graph search fusion



---



## 🔧 Installation & Configuration



### Safe Installation

The installation process is **production-safe** with multiple protection layers:



1. ✅ **Never overwrites** — always merges with existing config

2. ✅ **Automatic backups** — timestamped, last 5 kept

3. ✅ **Atomic writes** — temp file + rename (OS-level atomic)

4. ✅ **Automatic rollback** — restores from backup on any failure

5. ✅ **Cross-platform** — Windows (native, Git Bash, WSL2), macOS, Linux

6. ✅ **CI-aware** — skips non-essential operations in CI environments

7. ✅ **Timeout protection** — 30s timeout prevents hanging

8. ✅ **Graceful degradation** — exits 0 on non-critical failures



### Safe Removal

OpenCode config cleanup is provided as an explicit command because global package uninstall does not invoke dependency uninstall hooks in the npm flow validated for this package.



```bash

npm explore -g opencode-orchestrator -- npm run cleanup:plugin

npm uninstall -g opencode-orchestrator

```



Manual fallback:

- Open `~/.config/opencode/opencode.json` or `opencode.jsonc`

- Remove `"opencode-orchestrator"` from the `plugin` array



### Configuration Logs

- Unix: `/tmp/opencode-orchestrator.log`

- Windows: `%TEMP%\opencode-orchestrator.log`



---



## 🧪 Testing & Stability



### Test Utilities

Reusable helpers under `tests/harness/` provide:

- **Disposable tmpdir**: Automatic cleanup with `Symbol.asyncDispose` / `Symbol.dispose`

- **Test builders**: Factory functions for `ParallelTask`, `BackgroundTask`, `Todo`

- **Mock utilities**: Console, process, timers, file system, event emitter mocks



```typescript

import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";



await using tmp = await tmpdir({ git: true });

const task = createParallelTask({ description: "Test" });

```



### TUI Stability

- **Cleanup guarantees**: `initToastClient()` returns a cleanup function

- **Timeout protection**: AbortController-based 2-10s timeout for async toast operations

- **Error isolation**: Try/catch around all toast operations prevents cascade failures



### Cross-Platform Reliability

- **Windows guard**: Proper handling of WSL2, Git Bash, native Windows paths

- **Signal handling**: Graceful shutdown on SIGINT/SIGTERM

- **Process isolation**: Child process cleanup with timeout



---



## 📚 Documentation



- [System Architecture Deep-Dive →](docs/SYSTEM_ARCHITECTURE.md)

- [Developer Notes →](docs/DEVELOPERS_NOTE.md)

- [Knowledge RAG Roadmap →](docs/histories/2026/05/31/PLAN_SecondBrainOrchestration_2026-05-31.md)



---



## 📄 License



MIT License — see [LICENSE](LICENSE) for details.



---





  Built with ⚡ for production-grade autonomous software engineering