] [--model ] [--timeout 900] [--run --label ] "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 ` + `--label ` append lifecycle events (start/done/fail) to `.runs/.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 ../-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 [--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/`