Skip to content

Add Hivemind: Zero-Cost Multi-Agent Orchestration Skill - #1628

Open
Hanishchow wants to merge 2 commits into
anthropics:mainfrom
Hanishchow:add/hivemind-skill
Open

Hanishchow wants to merge 2 commits into
anthropics:mainfrom
Hanishchow:add/hivemind-skill

Conversation

@Hanishchow

@Hanishchow Hanishchow commented Aug 21, 2026 •

Copy link
Copy Markdown

Adds Hivemind, a skill that lets Claude Code delegate mechanical work to headless opencode workers running on free models, while Claude Code stays the only planner, reviewer, and merger.

Why

The expensive model's context is the scarce resource, not its intelligence. Hivemind moves grunt work — multi-lens review, research sweeps, bulk migrations, partitioned test runs — onto disposable workers, and every worker returns exactly one compact JSON line. Raw agent streams never enter the orchestrator's context, which is the whole point of the protocol.

What's in it

skills/hivemind/
  SKILL.md              invocation contract, swarm flow, fallback ladder, anti-patterns
  LICENSE.txt           Apache 2.0
  scripts/oc-worker.mjs the single sanctioned worker entry point
  scripts/oc-status.mjs fleet progress recovered from run logs
  scripts/oc-aggregate.mjs   consensus-first synthesis across N workers
  scripts/bench/        A/B/C benchmark harness + blind grading rubric
  assets/commands/      the 7 slash-command entry points
  assets/agents/        scout / coder / tester worker personas

Three personas, each least-privilege: scout (read-only, no write/edit/bash), coder (writes, confined to one git worktree), tester (runs tests, never edits source). Writing workers never share a directory, and the orchestrator is the only merger.

Dependency disclosure

This is an orchestration layer over the third-party opencode CLI, and worker traffic goes to opencode's endpoints. SKILL.md opens with a Prerequisites section stating that plainly, including that the free tier belongs to opencode rather than Anthropic and that availability, rate limits, and pricing are theirs to change. It also warns against delegating secrets or private code. Flagging it here too rather than leaving it to be discovered in review.

Canonical home

Maintained at https://github.com/Hanishchow/hivemind (Apache 2.0). This PR is a snapshot; fixes land there first and get ported here.

Contributor: @Hanishchow

@98zc5g5jyw-arch

Copy link
Copy Markdown

Babysit review — needs path fix

Nice content, but the new files live at the repo root hivemind/ instead of skills/hivemind/ — the repo's skill scanner won't pick them up, so the skill is effectively invisible after merge. Also: .runs/hive-smoke.jsonl is a runtime artifact and shouldn't be committed; and oc-worker.mjs defaults to an external opencode model (mimo-v2.5-free) — please document that dependency. Move the directory, drop the .runs/ trace, and re-push.

Hanishchow added a commit to Hanishchow/skills that referenced this pull request Aug 23, 2026
…ode dependency

Addresses review feedback on anthropics#1628:
- relocate hivemind/ -> skills/hivemind/ so the repo skill scanner picks it up
- remove committed .runs/hive-smoke.jsonl runtime artifact; gitignore .runs/
- document the external opencode CLI dependency, free-model caveats, and setup steps
- ship the slash commands and worker agent definitions the skill references
- make the opencode binary resolver cross-platform instead of Windows-only
@Hanishchow Hanishchow closed this Aug 23, 2026
Hivemind delegates grunt work to headless opencode workers (scout/coder/tester)
while Claude Code stays the planner, reviewer, and merger.

- skills/hivemind/SKILL.md documents the invocation contract, swarm flow, and fallbacks
- scripts/ hold the single sanctioned worker entry point plus status/aggregate/bench tools
- assets/ ship the slash commands and opencode agent definitions the skill references
- prerequisites section documents the external opencode CLI + free-model dependency
- runtime state (.runs/) is gitignored, not committed
@Hanishchow Hanishchow reopened this Aug 23, 2026

@98zc5g5jyw-arch 98zc5g5jyw-arch left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review: Hivemind skill (#1628)

Thanks for the submission — the skill is well-structured, the scripts are defensive (argv-array spawning, --dir validation, timeouts, capped stderr, NDJSON parsing with fallbacks), and the "Golden Rule / fallback ladder / worktree isolation" protocol is genuinely good engineering. No credentials or secrets are hardcoded anywhere. Two blocking items below (both cheap to fix), then non-blocking notes.

Blocking

  1. Missing license key in SKILL.md frontmatter — the repo convention (see skills/claude-api/SKILL.md and skills/docx/SKILL.md) requires three keys:

    ---
    name: hivemind
    description: ...
    license: Complete terms in LICENSE.txt
    ---

    The current frontmatter has only name and description. Please add the license key.

  2. Missing LICENSE.txt — every skill directory in this repo ships a LICENSE.txt with complete terms (skill-creator, claude-api, docx, ...). The PR's 17 files contain no license file. Please add skills/hivemind/LICENSE.txt with the appropriate terms for the skill content.

Non-blocking

  1. description length/format — 390 chars, single line, valid YAML (under the ~1024-char limit, so it passes), but it is on the long side; consider tightening the first sentence to the core trigger ("Orchestrate free opencode workers from Claude Code…") and moving the longer trigger phrases later, matching the repo's "short single-paragraph description" convention. Not a blocker.

  2. Security hardening (suggestion) — in scripts/oc-worker.mjs, ensureServer() runs spawn(\${quoted} serve --port ${PORT}`, { shell: true, ... }). PORTis derived from theHIVEMIND_SERVER_URLenv var, so a hostile value for that env var could inject shell syntax. Low severity (local env only), but consider spawning with an args array andshell: false, or validating that PORTis numeric. The mainopencode run` invocation already uses an args array (no shell interpolation) — good.

  3. Third-party dependency note — this skill is an orchestration layer over the third-party opencode CLI and routes worker traffic to opencode's endpoints/free models. The SKILL.md discloses this clearly ("Do not delegate secrets or private code you would not send there") and caveats that free-tier pricing/availability is opencode's to change — thank you for that. Just flagging for maintainer awareness; acceptable as disclosed.

  4. No duplication — checked the existing skills in the repo; no agent-collaboration/orchestration skill exists, so this fills a genuine gap. Directory layout (assets/agents/, assets/commands/, scripts/, scripts/bench/) is consistent with other script-heavy skills.

Summary

Great first contribution. Fix items 1 and 2 (add license key + LICENSE.txt), and this should be good to merge.

@Hanishchow

Copy link
Copy Markdown
Author

Thanks for the review — all three points are addressed, force-pushed as a single verified commit rebased on current main.

  • Path: hivemind/ → skills/hivemind/, so the skill scanner picks it up.
  • Runtime artifact: .runs/hive-smoke.jsonl removed, and .runs/ is now gitignored inside the skill folder so traces can't be committed again.
  • External dependency: SKILL.md opens with a Prerequisites table covering Node >= 18, the opencode CLI, authentication, and the default opencode/mimo-v2.5-free model — including that the free tier belongs to opencode (not Anthropic) and that availability, rate limits, and pricing are theirs to change. It also states plainly that worker traffic leaves for opencode's endpoints, so secrets and private code shouldn't be delegated.

Two things I fixed while in there, since they'd have been the next round of review:

  • The skill referenced seven slash commands and three worker agents that weren't in the PR at all. They now ship under assets/commands/ and assets/agents/, with a Setup section explaining where to copy them. Their invocations previously carried an absolute C:\Users\<me>\... path; that's now $HIVEMIND_HOME.
  • resolveOpencode() probed with where.exe unconditionally, so it silently fell back to a bare opencode on macOS and Linux. It now uses which off-Windows and keeps the .cmd-shim parsing on Windows (Node's EINVAL policy blocks spawning .cmd directly).

…v hardening

- add skills/hivemind/LICENSE.txt (Apache 2.0) and the license key in SKILL.md
  frontmatter, matching every other skill directory in this repo
- tighten the description from 390 to 300 chars, core trigger first
- validate HIVEMIND_SERVER_URL and spawn opencode serve with an args array and
  shell:false, so no environment value is shell-interpolated; a malformed URL or
  out-of-range port now fails fast with one JSON line instead of a stack trace
@Hanishchow

Copy link
Copy Markdown
Author

Both blocking items are fixed, plus 3 and 4. Pushed as a follow-up verified commit.

1. license frontmatter key — added:

name: hivemind
description: ...
license: Complete terms in LICENSE.txt

2. LICENSE.txt — added at skills/hivemind/LICENSE.txt, Apache 2.0, byte-identical to the copy in skills/canvas-design apart from the copyright line, which reads Copyright 2026 N Hanish (@Hanishchow). rather than Anthropic PBC, since I'm contributing the content rather than assigning it. If you'd rather it match the other skills exactly, say so and I'll change it in one push — no objection either way.

3. description — 390 → 300 chars, core trigger first:

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".

4. Shell injection — you were right to flag it, and chasing it turned up a second, more likely bug. ensureServer() now spawns with an args array and shell: false, so nothing is interpolated:

const child = spawn(bin, ["serve", "--port", PORT], { shell: false, detached: true, stdio: "ignore", windowsHide: true });

That also removed the manual path-quoting the shell form needed. PORT is now produced by a resolvePort() that rejects anything non-numeric or out of range.

The second bug: a malformed HIVEMIND_SERVER_URL made new URL() throw at module top level, so the script died with a stack trace on stdout/stderr — breaking the one-JSON-line contract the whole skill depends on. Now:

$ HIVEMIND_SERVER_URL="not a url" node scripts/oc-worker.mjs "task"
{"ok":false,"stage":"args","error":"HIVEMIND_SERVER_URL is not a valid URL","result":"",...}

$ HIVEMIND_SERVER_URL="http://127.0.0.1:70000" node scripts/oc-worker.mjs "task"
{"ok":false,"stage":"args","error":"HIVEMIND_SERVER_URL is not a valid URL","result":"",...}

The env var and its validation are now documented in SKILL.md next to the server-management paragraph.

On 5 — noted, and I'd rather it stay flagged than buried. If the third-party dependency ever becomes disqualifying for this repo, tell me and I'll withdraw it without argument.

@98zc5g5jyw-arch 98zc5g5jyw-arch left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review after b4f0c6f: all previously requested changes are addressed. 1) license key added to frontmatter, 2) LICENSE.txt shipped, 3) description tightened to 373 chars, 4) oc-worker.mjs now validates PORT via resolvePort() and spawns with shell:false args array. Looks good. LGTM.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants