| name | hivemind |
| 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 (scout/coder/tester) with worktree isolation, benchmarking against opencode, or when the user says "spawn a worker", "swarm", "delegate to opencode", or "/oc". |
Hivemind: Claude Code as Orchestrator, opencode as Free Worker Swarm
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, 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
- Put this skill folder wherever your agent loads skills from (e.g.
~/.claude/skills/hivemind).
- Export
HIVEMIND_HOME pointing at that folder — the bundled slash commands use it:
export HIVEMIND_HOME="$HOME/.claude/skills/hivemind"
- 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)
- Decompose task into 2-5 INDEPENDENT subtasks (no shared files).
- Writing workers get isolated worktrees FIRST:
git worktree add ../<repo>-wt-N -b swarm/N.
- Issue ALL worker invocations as PARALLEL Bash tool calls in ONE message.
- Review every diff yourself (
git diff main...swarm/N). YOU are the only merger.
- Merge approved branches, remove worktrees, run tests.
- 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)
- Worker
ok:false -> re-invoke once against the same dir.
- Still failing -> orchestrator performs that subtask inline, marks it
[orchestrator-sourced].
- 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 howengineering/agent-harness — harness patterns for the orchestrator side of the loopengineering/workflow-builder — for deterministic pipelines that do not need independent worker judgmentengineering/skills and engineering/write-a-skill — authoring conventions used by the worker agent definitions in assets/agents/
