---

⚡ Quick Start

``bash
npm install -g opencode-orchestrator
`

Inside an OpenCode environment:
`bash
/task "Implement a new authentication module with JWT and audit logs"
`

---

---

🚀 Engine Workflow

OpenCode Orchestrator utilizes a Hub-and-Spoke Topology with Work-Stealing Queues to execute complex engineering tasks through parallel, context-isolated sessions.

`text
[ User Task ]
│
┌──────────▼──────────┐
│ COMMANDER │◄───────────┐ (Loop Phase)
│ [Work-Stealing] │ │
└────────┬────────────┘ │
│ │
┌────────▼──────────┐ │
│ PLANNER │ (Todo.md) │
│ [Session Pool] │ │
└────────┬──────────┘ │
│ │ (MVCC Atomic Sync)
┌─────────────┼──────────────┐ │
▼ (Isolated Session Pool)▼ │
[ Session A ] [ Session B ] [ Session C ] │
[ Worker ] [ Worker ] [ Reviewer ] │
│ [Memory ] │ [Memory ] │ [Memory │ │
│ Pooling] │ │ Pooling] │ │ Pooling] │ │
└─────────────┬──────────────┘ │
│ │
┌────────▼──────────┐ │
│ MSVP MONITOR │──────────────┘
│ [Adaptive Poll] │
└────────┬──────────┘
│
┌────────▼──────────┐
│ QUALITY ASSURANCE │
└────────┬──────────┘
│
[ ✨COMPLETED ]
`

---

🛠️ Core Capabilities

$3

The engine solves the "Concurrent TODO Update" problem using Multi-Version Concurrency Control (MVCC) + Mutex. Agents can safely mark tasks as complete in parallel without data loss or race conditions. Every state change is cryptographically hashed and logged for a complete audit trail.

$3

Execution flows are governed by a Priority-Phase Hook Registry. Hooks (Safety, UI, Protocol) are grouped into phases (early, normal, late) and executed using a Topological Sort to handle complex dependencies automatically, ensuring a predictable and stable environment.

$3

- 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

$3

Reused sessions in the SessionPool are explicitly reset using server-side compaction triggered by health monitors. This ensures that previous task context (old error messages, stale file references) never leaks into new tasks, maintaining 100% implementation integrity.

$3

Leverages system.transform to unshift massive agent instruction sets on the server side. This reduces initial message payloads by 90%+, slashing latency and preventing context fragmentation during long autonomous loops.

---

🛠️ Infrastructure & Reliability

$3

- RAII Pattern (ConcurrencyToken): Guaranteed resource cleanup with zero leaks
- ShutdownManager: Priority-based graceful shutdown with 5-second timeout per handler
- Automatic Backups: All config changes backed up with rollback support
- Atomic File Operations: Temp file + rename for corruption-proof writes
- Finally Blocks: Guaranteed cleanup in all critical paths
- Zero Resource Leaks: File watchers, event listeners, concurrency slots all properly released

$3

- Work-Stealing Queues: Chase-Lev deque implementation for 90%+ CPU utilization
- Planner: 2 workers, Worker: 8 workers, Reviewer: 4 workers
- LIFO for owner (cache locality), FIFO for thieves (fairness)
- Memory Pooling: 80% GC pressure reduction
- Object Pool: 200 ParallelTask instances (50 prewarmed)
- String Interning: Deduplication for agent names, status strings
- Buffer Pool: Reusable ArrayBuffers (1KB, 4KB, 16KB, 64KB)
- Session Reuse: 90% faster session creation (500ms → 50ms)
- Pool size: 5 sessions per agent type
- Max reuse: 10 times per session
- Health check: Every 60 seconds
- Rust Connection Pool: 10x faster tool calls (50-100ms → 5-10ms)
- Max 4 persistent processes
- 30-second idle timeout
- Adaptive Polling: Dynamic 500ms-5s intervals based on system load

$3

- 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 (depth limit enforcement)
- Auto-Scaling: Concurrency slots adjust based on success/failure rate

---

🛠️ Key Innovations

$3

Maintains focus across thousands of conversation turns using a 4-tier memory structure and EMA-based Context Gating to preserve "Architectural Truth" while pruning operational noise.

$3

Slots for parallel implementation scale up automatically after a 3-success streak and scale down aggressively upon detection of API instability or implementation failures.

$3

Combines LLM reasoning with deterministic AST/LSP verification. Every code change is verified by native system tools before being accepted into the master roadmap.

$3

- Stagnation Detection: Automatically senses when no progress is made across multiple iterations
- Diagnostic Intervention: Forces the agent into a "Diagnostic Mode" when stagnation is detected, mandating log audits and strategy pivots
- Proactive Agency: Mandates Speculative Planning and Parallel Thinking during background task execution

$3

Seamless integration with OpenCode's native TUI via TaskToastManager. Provides non-intrusive, real-time feedback on Mission Progress, active Agent Sub-sessions, and Technical Metrics using protocol-safe Toast notifications.

$3

Utilizes a hybrid event-driven pipeline (EventHandler + TaskPoller) to maximize responsiveness while maintaining robust state tracking and resource cleanup.

$3

Runtime agent configuration is strictly validated using Zod schemas, ensuring that custom agent definitions in agents.json are type-safe and error-free before execution.

---

⚡ Elite Multi-Agent Swarm

| Agent | Expertise | Capability |
|:------|:-----|:---|
| Commander | Mission Hub | Session pooling, parallel thread control, state rehydration, work-stealing coordination |
| Planner | Architect | Symbolic mapping, dependency research, roadmap generation, file-level planning |
| Worker | Implementer | High-throughput coding, TDD workflow, documentation, isolated file execution |
| Reviewer | Auditor | Rigid verification, LSP/Lint authority, integration testing, final mission seal |

---

📈 Performance Benchmarks

$3

- Concurrent Sessions: 50+ parallel agent sessions with work-stealing
- CPU Utilization: 90%+ (up from 50-70%)
- Tool Call Speed: 10x faster (5-10ms vs 50-100ms) via Rust connection pool
- Session Creation: 90% faster (50ms vs 500ms) via session pooling
- Processing Speed: 3-5x baseline throughput

$3

- Memory Usage: 60% reduction (40% of baseline) via pooling
- GC Pressure: 80% reduction via object/string/buffer pooling
- Token Efficiency: 40% reduction via Incremental State & System Transform

$3

- Sync Accuracy: 99.95% reliability via MVCC+Mutex transaction logic
- Mission Survival: 100% uptime through plugin restarts via S.H.R (Self-Healing Rehydration)
- Resource Leaks: Zero (guaranteed by RAII pattern)
- Config Safety: 100% (atomic writes + auto-backup + rollback)

$3

- Work-Stealing Efficiency: 80% improvement in parallel efficiency (50% → 90%+)
- Adaptive Polling: Dynamic 500ms-5s based on load
- Auto-Scaling: Concurrency slots adjust automatically based on success 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 pattern + circuit breaker + resource pressure detection

---

📚 Documentation

- Why We Built a Custom Orchestrator Instead of Using OpenCode's APIs →
- System Architecture Deep-Dive →
- Windows Configuration Guide →
- Developer Notes →

---

🔧 Installation & Configuration

$3

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. ✅ Write verification - ensures correctness after every change
5. ✅ Automatic rollback - restores from backup on any failure
6. ✅ Cross-platform - Windows (native, Git Bash, WSL), macOS, Linux

$3

- Unix: /tmp/opencode-orchestrator.log
- Windows: %TEMP%\opencode-orchestrator.log`

---

📄 License

MIT License - see LICENSE for details.

---