claude-skills/docs/skills/engineering/hivemind.md

---
title: "Hivemind: Claude Code as Orchestrator, opencode as Free Worker Swarm — Agent Skill for Codex & OpenClaw"
description: "Orchestrate free opencode workers from Claude Code to cut token costs. Use when delegating grunt work to a single worker or a parallel swarm."
---

# Hivemind: Claude Code as Orchestrator, opencode as Free Worker Swarm

<div class="page-meta" markdown>
<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span>
<span class="meta-badge">:material-identifier: `hivemind`</span>
<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/hivemind/SKILL.md">Source</a></span>
</div>

<div class="install-banner" markdown>
<span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code>
</div>


Claude Code = brain (plans, reviews, merges). opencode = disposable workers on free models
(`opencode/mimo-v2.5-free` default; verified $0.00 per run).

## Prerequisites (external dependency)

This skill is a thin orchestration layer over **[opencode](https://opencode.ai)**, a
third-party CLI. It is not bundled — install and authenticate it yourself first:

| Requirement | Notes |
|---|---|
| Node.js >= 18 | The scripts use `fetch` and `node:timers/promises`. |
| `opencode` CLI on `PATH` | `npm i -g opencode-ai` (or the installer opencode documents). |
| An authenticated opencode account | `opencode auth login`. Workers run as your account. |
| Default model `opencode/mimo-v2.5-free` | A free tier offered by opencode, not by Anthropic. Availability, rate limits, and pricing are opencode's to change — override with `--model` at any time. |
| Windows only: `OPENCODE_GIT_BASH_PATH` | Point at `C:\Program Files\Git\bin\bash.exe`, set persistently. |

Nothing here calls the Anthropic API on the worker side; worker traffic goes to
opencode's endpoints. Do not delegate secrets or private code you would not send there.

## Setup

1. Put this skill folder wherever your agent loads skills from (e.g. `~/.claude/skills/hivemind`).
2. Export `HIVEMIND_HOME` pointing at that folder — the bundled slash commands use it:
   ```
   export HIVEMIND_HOME="$HOME/.claude/skills/hivemind"
   ```
3. Copy the bundled assets into place:
   - `assets/commands/*.md` -> `~/.claude/commands/` (the `/hive`, `/oc`, `/swarm`, ... entry points)
   - `assets/agents/*.md` -> `~/.config/opencode/agent/` (the scout / coder / tester worker personas)

Both copies are optional: everything the commands do can be driven by invoking
`scripts/oc-worker.mjs` directly, and any opencode agent name works with `--agent`.

Runtime state (`.runs/*.jsonl`) is written inside this folder and is gitignored.

## Components

| Path (relative to this skill dir) | Purpose |
|---|---|
| `scripts/oc-worker.mjs` | ONLY sanctioned way to invoke a worker. Hardened join point. |
| `scripts/oc-status.mjs` | Fleet progress from run logs (`oc-status.mjs <run-id>`) |
| `scripts/oc-aggregate.mjs` | Dedupe/synthesize N worker outputs; consensus findings first |
| `scripts/bench/run-bench.mjs` | Benchmark configs A (claude solo), B (opencode solo), C (orchestrated swarm) |
| `scripts/bench/grader-prompt.md` | Blind grading rubric (max 12 pts + PASS/FAIL gate) |
| `assets/commands/` | Slash-command entry points to copy into `~/.claude/commands/` |
| `assets/agents/` | scout / coder / tester agent definitions for opencode |

Slash commands (ship in `assets/commands/`, copy to `~/.claude/commands/`):
- `/hive <task>` - AUTO-ROUTER. Classifies task -> single worker, generic swarm, or template. Default entry point; prefer this over manual routing.
- `/oc <task>` - single worker delegation
- `/swarm <task>` - generic parallel swarm
- `/review-panel <diff>` - 4-lens parallel review (correctness/security/performance/style) + consensus aggregation
- `/research-sweep <question>` - 3-5 parallel research angles, synthesized
- `/migration <task>` - batched per-worktree migration workers + sequenced merge
- `/test-fleet <target>` - partitioned parallel test runs with safety checks

Worker agents (ship in `assets/agents/`, copy to `~/.config/opencode/agent/`):
- **scout** - read-only research (no write/edit/bash)
- **coder** - implements one subtask in its worktree
- **tester** - runs tests only, never edits source

## Invocation contract

```
node "<skill-dir>\scripts\oc-worker.mjs" [--agent scout|coder|tester] [--dir <path>] [--model <p/m>] [--timeout 900] [--run <id> --label <name>] "TASK TEXT"
```

Returns exactly ONE compact JSON line:
`{ ok, result, tokens:{total,input,output,cache}, cost_usd, duration_ms, label, agent, model }`

On failure: `{ ok:false, stage:"args"|"exec"|"api"|"parse"|"empty", error }` with stderr capped at 300 chars.

`--run <id>` + `--label <name>` append lifecycle events (start/done/fail) to `.runs/<id>.jsonl`
inside this skill dir. Use them for EVERY swarm worker so progress is recoverable via
`oc-status.mjs` even after orchestrator context loss.

The script auto-manages the shared server: health-checks `127.0.0.1:4096`, spawns `opencode serve` if dead, waits 5s, falls back to cold start. Workers are idempotent against their `--dir`; re-run once on `ok:false` before giving up.

`HIVEMIND_SERVER_URL` overrides that address (default `http://127.0.0.1:4096`). It must be a
valid URL with a numeric port; anything else fails fast with a single `stage:"args"` JSON line
rather than reaching the spawned process.


## Golden Rule (non-negotiable)

Raw opencode NDJSON streams must NEVER enter your context. All output arrives via the
script's single JSON line. Never pipe `opencode run --format json` directly into this
conversation; never re-implement what the script does.

## Single worker flow (/oc)

For one read-only question or small delegation: run oc-worker.mjs without worktrees.
Read-only tasks may omit `--agent`/`--dir`. Summarize `result` for the user.
If files were written: show `git diff` before letting the user commit.

## Swarm flow (multi-worker)

1. Decompose task into 2-5 INDEPENDENT subtasks (no shared files).
2. Writing workers get isolated worktrees FIRST: `git worktree add ../<repo>-wt-N -b swarm/N`.
3. Issue ALL worker invocations as PARALLEL Bash tool calls in ONE message.
4. Review every diff yourself (`git diff main...swarm/N`). YOU are the only merger.
5. Merge approved branches, remove worktrees, run tests.
6. Report table: subtask | agent | tokens | outcome + total worker tokens.

HARD RULES: workers never share directories; never delegate merging/reviewing;
escalate to your own Sonnet only when a free-model worker demonstrably fails twice.

## Benchmarking

```
node scripts\bench\run-bench.mjs --repo <project> [--configs a,b,c] [--task 1-5]
```
Appends JSONL records (ts, config, tokens, cost, duration) to `bench-results.jsonl`.
Grade artifacts blind with `grader-prompt.md` (grader sees only task spec + output).
Configs: A=claude solo baseline, B=opencode solo, C=claude orchestrating 2 workers.

## Fallback ladder (all flows)

1. Worker `ok:false` -> re-invoke once against the same dir.
2. Still failing -> orchestrator performs that subtask inline, marks it `[orchestrator-sourced]`.
3. opencode entirely down (`exec`/`api` twice) -> announce, abandon workers, do the task directly.
Never let a swarm fail a task that Claude could have done itself.

## Fleet patterns

Four reusable topologies ship as slash commands (see table above). Shared invariants:
parallel spawns in one message; `--run/--label` on every worker; aggregation via
`oc-aggregate.mjs` when 3+ workers produce findings; consensus beats single-lens claims;
worktree isolation whenever any worker writes.

## Windows notes (hard-won)

- Requires `OPENCODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe` (set persistently).
- The script resolves the REAL `opencode.exe` by parsing the npm `.cmd` shim — Node's
  EINVAL policy blocks spawning `.cmd` directly. Do not "simplify" resolver back to
  `where.exe` first-line.
- Free models: `opencode/mimo-v2.5-free`, `opencode/nemotron-3.5-lightning-free`,
  `opencode/hy3-free`. NOTE: `opencode-go/*` models require workspace billing — avoid.

## Known limits

- Free-tier rate limits can 429 under heavy swarms; space out retries.
- Worker quality varies; always review diffs. Scout answers are evidence-cited.
- Bench config C consumes real Claude tokens for orchestration (~1-2k/task).

## Anti-patterns

| Anti-pattern | Why it breaks | Do this instead |
|---|---|---|
| Piping `opencode run --format json` straight into the orchestrator | Raw NDJSON floods context — the exact cost the skill exists to avoid | Always go through `scripts/oc-worker.mjs`, which returns one compact JSON line |
| Two writing workers in one directory | Concurrent edits corrupt each other's diffs | One git worktree per writing worker, created before the spawn |
| Letting a worker merge, review, or approve its own branch | Free-tier workers are the least reliable judges of their own output | The orchestrator is the only merger and the only reviewer |
| Spawning workers sequentially, one per message | Loses the entire wall-clock benefit of a swarm | Issue every worker invocation as parallel calls in ONE message |
| Retrying a failing worker indefinitely | Burns rate limit and stalls the task | Retry once, then do the subtask inline and mark it `[orchestrator-sourced]` |
| Delegating secrets, credentials, or private code | Worker traffic leaves for opencode's endpoints | Keep sensitive context in the orchestrator; send workers only what is safe to share |
| Trusting `cost_usd: 0` as a permanent guarantee | The free tier belongs to opencode and can change | Re-check pricing before relying on zero cost for bulk work |

## Cross-references

- `engineering/llm-cost-optimizer` — decide *whether* a task is worth delegating before Hivemind decides *how*
- `engineering/agent-harness` — harness patterns for the orchestrator side of the loop
- `engineering/workflow-builder` — for deterministic pipelines that do not need independent worker judgment
- `engineering/skills` and `engineering/write-a-skill` — authoring conventions used by the worker agent definitions in `assets/agents/`