Worker Orchestrator

Architecture

Two Pools, One Orchestrator

Hermes (Orchestrator)
    |
    |-- Decomposes task into subtasks
    |-- Spawns workers (max 6 parallel, max 3 per provider)
    |-- Monitors progress
    |-- Evaluates worker output
    |-- Gives feedback / respawns if needed
    |-- Rebalances work across OpenCode + Codex pools
    |-- Synthesizes final deliverable
    

OpenCode Pool

Spawned via execute_code with Python subprocess.Popen. Reliable for parallel coding, research, and structured repo work.

Codex Pool

Spawned via terminal(pty=true). Good for patching, validation, and overflow capacity.

Hermes Orchestrator

Handles decomposition, evaluation, provider allocation, and synthesis. Uses ~15-25% of token budget.

Capabilities

What It Does

1. Decompose

Break your task into 2-5 independent subtasks. Each worker gets a self-contained prompt with all context it needs.

2. Spawn

Launch OpenCode and Codex workers as actual OS processes with isolated workdirs. No subagents — real CLI processes.

3. Monitor

Batch-style monitoring via subprocess output capture. Inspect logs before trusting files alone.

4. Evaluate

Score every worker against a rubric: Presence, Correctness, Completeness, Quality. Pass threshold: average >= 3.0.

5. Respawn

Failed workers get specific corrective feedback and are respawned. Max 2 respawns per subtask. Circuit breaker detects rate limits.

6. Rebalance

Shift work between OpenCode and Codex pools based on capacity, reliability, and task fit. Not a one-way fallback chain.

7. Dynamic Spawn

After the first batch, spawn additional workers if gaps remain or user feedback arrives mid-orchestration.

8. Synthesize

Merge all worker outputs into a single coherent deliverable, resolve conflicts, and credit which worker produced what.

Safety & Limits

Hard Caps

Limit	Value	Why
Global workers	6 active max	Prevents orchestrator overload and token burn
OpenCode pool	3 active max	Respects provider concurrency limits
Codex pool	3 active max	Respects provider concurrency limits
Respawns per subtask	2 max	Avoids infinite retry loops
Worker timeout	300s default, 600s large tasks	Kills stuck workers promptly

Installation

Get Started

# Option 1 — direct clone
git clone https://github.com/hackafrik/worker-orchestrator.git ~/.hermes/skills/worker-orchestrator

# Option 2 — skills.sh
npx skills add hackafrik/worker-orchestrator
    

Requirements

Hermes Agent
OpenCode CLI installed and authenticated
Codex CLI installed and authenticated

Usage

Trigger Phrases

The skill auto-triggers when you say things like:

"Spawn workers to refactor these files"

"Use OpenCode to research this topic"

"Delegate this task to cheaper models"

"Parallelize this work across multiple agents"

"Run agents in parallel"

"Fan out these tasks to workers"

Tools

Helper Scripts

Script	Purpose
`scripts/evaluate_output.py`	Score worker output against criteria (Presence, Correctness, Completeness, Quality)
`scripts/evaluate_worker_logs.py`	Parse worker terminal output into structured JSON findings
`scripts/circuit_breaker.py`	Detect rate-limit / API exhaustion errors and recommend respawn actions
`scripts/synthesize_outputs.py`	Merge multiple worker outputs into one deliverable