Hivemind

Multi-agent orchestration framework for Claude Code. Coordinates specialized bioforms to plan, build, review, and ship code — so you don't have to manage the pipeline yourself.

Install

Inside Claude Code, add the marketplace then install the plugin:

/plugin marketplace add https://github.com/brenpike/hivemind.git
/plugin install hivemind@brenpike

Requirements

• bash (macOS, Linux, or WSL on Windows)
• git and gh (GitHub CLI)
• Claude Code CLI

As of v1.0.0, PowerShell and native Windows support have been removed. All toolchain scripts are bash-based.

Per-project setup

1. Enable the plugin and set the overlord as the session default agent in .claude/settings.json:

{
  "enabledPlugins": {
    "hivemind@brenpike": true
  },
  "agent": "hivemind:overlord"
}

The agent key sets the default agent for the project session. Without it, Claude Code starts with the default agent and the overlord is only reachable on-demand via the Agent tool — bypassing the workflow guarantees.

Or run the setup skill once to apply the required keys automatically:

/hivemind:seed-hive

The setup skill also adds .hivemind/ to your project's .gitignore. This directory is created at runtime by the overlord for ephemeral plans, handoffs, and checkpoints — it should not be committed. If you prefer manual setup, add .hivemind/ to your project's .gitignore directly.

seed-hive detects which companion plugins are installed (caveman, claude-mem, codex) and interactively prompts you to enable each one, recommending yes for any that are detected. Pass an explicit =yes or =no argument to skip the prompt for that companion (e.g. caveman=no opts out without prompting; claude_mem=yes enables without prompting).

Least-privilege permission allowlist. By default, seed-hive merges a recommended set of permissions.allow entries into .claude/settings.json. Pass seed_allowlist=no to skip this step:

/hivemind:seed-hive seed_allowlist=no

The seeded entries cover read/output helper Bash commands (echo, printf, cat, grep, jq, head, tail, ls, wc, sort, uniq) and scoped git read subcommands (git ls-files, git ls-tree, and git grep are read-only listers/searchers; git stash list and git stash show * are read-only stash inspection; git tag is list-only). They are appended-if-absent — existing entries are never overwritten or removed. echo/printf/cat/sort are included: Claude Code re-prompts (ask/deny) on any command that writes or redirects to a path outside the session working directory (only > /dev/null is exempt) and splits compound commands (&&/||/;/|/newline), requiring each subcommand to match a rule independently — so granting them does not create an arbitrary-file-write vector (echo evil > /etc/passwd, printf x > ~/.bashrc, cmd && rm -rf y all re-prompt). The only silent write any of these helpers permits is bounded to the working directory, identical to grep/jq/head/tail/ls/wc/uniq. node, Edit, and Write are not auto-approved; those require explicit per-project decisions.

For prompt-free local Codex review (hivemind:adaptation-cycle), add your Codex cache path to the project's .claude/settings.json (or the gitignored .claude/settings.local.json):

"Bash(node /path/to/.claude/plugins/cache/openai-codex/codex/*)"

Replace /path/to/ with your actual home directory path. The codex/* wildcard covers all Codex CLI entry points so the entry does not need updating when Codex is upgraded.

2. Create CLAUDE.md with project-specific details:

   • Build/test commands
   • Package names and version file paths
   • Versioning configuration (bump triggers, changelogs, tag prefixes)
   • Architecture and code style notes

3. Create AGENTS.md at the project root with project-specific Codex review guidance. Include:

   • Review focus areas
   • Severity definitions
   • Project-specific conventions for reviewers

Once configured, the overlord is the session default agent. All skills are available namespaced as hivemind:<skill-name>.

Recommended companion plugins

• claude-mem — provides optional cross-session memory and continuity. Install separately as a Claude Code plugin. Hivemind works without it; if installed, the cerebrate reads claude-mem memory directly via the MCP search tool (mcp__plugin_claude-mem_mcp-search__*) before every plan unless the repo has zero commits or the user explicitly opts out. Writes happen through claude-mem's automatic capture (there is no write MCP tool). uvx (from Astral's uv) is an optional dependency of claude-mem that enables its semantic (vector/Chroma) search backend; without it, claude-mem falls back to keyword search and MCP tools remain fully callable. Install with curl -LsSf https://astral.sh/uv/install.sh | sh; diagnostics at ~/.claude-mem/logs/ (look for CHROMA_MCP entries).

• codex — provides local and GitHub-integrated Codex code review. Install and configure with:

  /plugin marketplace add https://github.com/openai/codex-plugin-cc.git
  /plugin install codex@openai-codex
  /reload-plugins
  /codex:setup
  

  When installed, enables local pre-PR Codex review via the local-reviewer agent (backed by hivemind:adaptation-cycle) and post-PR review automation via the hivemind:github-review-loop skill (which watches the PR and dispatches the stateless fix-mode github-reviewer agent to handle feedback classification, fixes, and thread resolution). The framework works without it; if not installed, local review steps are skipped gracefully.

• caveman (caveman@caveman) — Token-compressed communication. Optional. When installed, all framework agents output in caveman ultra mode. seed-hive detects it and prompts to enable it automatically, or add manually to .claude/settings.json:

  "enabledPlugins": { "caveman@caveman": true },
  "pluginConfigs": { "caveman@caveman": { "options": { "defaultLevel": "ultra" } } }

Dev container

This repo ships a .devcontainer/ that provisions a CI-parity toolchain so contributors can run the full validation suite locally — in GitHub Codespaces or in VS Code Dev Containers (Dev Containers: Reopen in Container) — and dogfood the plugin. The base image is Ubuntu (Debian/Ubuntu family is mandatory: the policy linter uses GNU grep -P and perl, which Alpine/BusyBox lack).

Auto-provisioned by .devcontainer/postCreate.sh:

• Validation toolchain — jq and perl are explicitly installed via apt before any gate runs (idempotent: skipped if already present); gh, Node 20, python3, GNU grep, and git are verified at startup and the script hard-fails if any are missing.
• CLI tools via npm global — Claude Code CLI (@anthropic-ai/claude-code), Codex CLI (@openai/codex), claude-mem.
• uv / uvx (Astral) via the official install script — claude-mem's optional vector-search backend.
• tmux via apt — terminal multiplexer used by the hivemind:spawn-brood / hivemind:brood-status skills.
• bun via the official installer (bun.sh/install) — fast JS runtime required by claude-mem.
• A CI-parity smoke test that runs the same three gates as .github/workflows/policy-check.yml: the python3 JSON-manifest parse, tools/policy_check.sh --strict, and tools/validate_reports.sh --batch tests/reports/. A green run is a strong best-effort signal that the branch will pass CI — not an absolute guarantee, since CI runs on ubuntu-latest while this container pins ubuntu-20.04 (coreutils/grep/perl/python versions can differ). It also trips on CRLF line endings, which have corrupted these linters before.

Stays manual — installing the Claude Code plugins requires an authenticated claude CLI, which a fresh container does not have. postCreate.sh registers the marketplaces (no auth needed) and prints the exact install commands to run once you have signed in:

claude plugin install hivemind@brenpike
claude plugin install codex@openai-codex
claude plugin install claude-mem@thedotmack
claude plugin install caveman@caveman
/codex:setup

Caveman marketplace is registered automatically. postCreate.sh registers the caveman marketplace (no auth required). Caveman enablement (enabledPlugins, pluginConfigs, SubagentStart hook, .envrc) is handled by hivemind:seed-hive caveman=yes — the canonical path for all plugin config — rather than being hand-seeded by postCreate.

The optional npm installs are wrapped so a single failure (for example in an offline/locked-down Codespace) prints a warning but does not abort — only the CI-parity gates are must-pass. The script is idempotent: re-running bash .devcontainer/postCreate.sh is safe.

The Codex cache permission grant (container $HOME node path) is seeded into the gitignored .claude/settings.local.json (never the tracked .claude/settings.json), using a jq-merge that does not clobber existing entries.

See .devcontainer/README.md for full launch instructions (Codespaces and local Dev Containers), the complete list of what is auto-provisioned, and troubleshooting.

After cloning a project that uses this plugin

/plugin marketplace add https://github.com/brenpike/hivemind.git
/plugin install hivemind@brenpike

The Swarm

Hivemind coordinates specialized bioforms to plan, build, review, and ship code — so you don't have to manage the pipeline yourself.

Know Your Bioforms

Bioform	Role	What it does
👁️ Overlord	Orchestrator	The control plane. Routes the Overmind's directives, distributes the cerebrate's plan, owns the git lifecycle, spawns specialists. Never writes code. Your main interface.
🧠 Cerebrate	Strategist	Originates the plan. Scans the territory and produces the directive — the intelligence the swarm executes. Read-only; thinks, never writes.
🔨 Drone	Builder	Builds code within its assigned scope. The workhorse of the swarm.
🎭 Changeling	Shaper	Handles UI, styling, and visual presentation. Reshapes how things look and feel.

The Lifecycle

You --> Overlord --> Cerebrate (plan) --> Directive
                 --> Drone/Changeling (build) --> Essence
                 --> Adaptation Cycle (review) --> PR

1. You give the overlord a task
2. The cerebrate scans the territory and returns a directive
3. The overlord spawns specialists (drones / changelings) phase by phase
4. Each phase produces essence — knowledge carried forward
5. An adaptation cycle reviews the work before shipping
6. A PR is opened when the swarm stabilizes

Brood Mode — Parallel Execution

When the work is big enough, the overlord can split it into independent strains and dispatch a brood — multiple parallel sessions, each running its own full lifecycle in a separate git worktree.

You --> Overlord --> Cerebrate (decompose)
                 --> "3 independent strains detected. Deploy brood?"
                 --> Yes --> Hatchery mode
                           --> Strain A (tmux tab) --> own branch, own PR
                           --> Strain B (tmux tab) --> own branch, own PR
                           --> Strain C (tmux tab) --> own branch, own PR

The overlord enters hatchery mode — monitoring the brood from home base while each strain evolves independently.

Signals

Signal	Meaning
🔥 Flare	Urgent — agent hit something it can't resolve alone. Overlord stops and asks you.
⚡ Reflex	Simple task — overlord skips the cerebrate and spawns a drone directly.
🧬 Mutation Decay	Two fixes are fighting each other. Swarm stops. You decide.
🔄 Adaptation Cycle	Review in progress — the swarm is stabilizing before shipping.

Plain English Still Works

Every themed term maps to a plain concept. You don't need to learn the language to use the framework:

You can say...	Or say...	Same thing
"checkpoint commit"	"molt"	Save progress at a phase boundary
"spawn a brood"	"dispatch a fleet"	Run parallel sessions
"what's the status"	"brood status"	Check progress across sessions
"plan this"	"send the cerebrate"	Get a plan before building

The theme is for fun. The framework works with or without it.

Repository layout

.claude-plugin/
  marketplace.json          # marketplace manifest (lives at repo root; points to ./plugin)
plugin/                     # plugin root — everything Claude Code loads lives here
  .claude-plugin/
    plugin.json             # plugin manifest
  agents/                   # agent definitions (overlord, cerebrate, drone, changeling, local-reviewer, github-reviewer)
  skills/                   # skill definitions (incl. _shared/ helpers)
  governance/               # runtime governance docs loaded via ${CLAUDE_PLUGIN_ROOT}/governance/
docs/
tools/                      # dev-only validation scripts (policy linter, report validator)
tests/                      # dev-only test fixtures and checks (policy, reports, plugin compatibility)
AGENTS.md                   # project-specific Codex reviewer guidance
CHANGELOG.md                # project changelog (Keep a Changelog format)
CLAUDE.md                   # project instructions for Claude Code
README.md

plugin/governance/ is the active runtime governance directory. Agents and skills reference these files via ${CLAUDE_PLUGIN_ROOT}/governance/ paths; they are loaded at runtime and affect agent behavior.

tools/ and tests/ contain development-time validation scripts and test fixtures. They live outside plugin/ and are not distributed as plugin runtime data.

${CLAUDE_PLUGIN_ROOT} resolves to the plugin/ directory at runtime, so all internal cross-references (e.g. ${CLAUDE_PLUGIN_ROOT}/governance/definitions.md) resolve correctly without per-consumer configuration.

Agents

Agent	Role
hivemind:overlord	Default agent. Coordinates all work, owns git workflow, branch/PR decisions, versioning decisions, and external review routing.
hivemind:cerebrate	Research and implementation planning. Read-only — no file writes.
hivemind:drone	Implementation within explicitly assigned file scope.
hivemind:changeling	Presentational UI/UX work within explicitly assigned file scope.
hivemind:local-reviewer	Pre-PR iterative Codex review with self-owning fix delegation at sonnet tier.
hivemind:github-reviewer	Stateless fix-mode worker: deep-fetches and classifies post-PR feedback, applies fixes, pushes, and resolves threads. The hivemind:github-review-loop skill does the monitoring.

Skills

All skills are invoked using the namespaced form:

Skill	Purpose
hivemind:creep-spread	Analyze project artifacts and generate a populated CONTEXT.md (or CONTEXT-MAP.md for multi-context repos) with domain terms extracted from code, docs, and config
hivemind:molt	Commit a completed phase, milestone, version bump, or review-remediation item
hivemind:create-working-branch	Create or confirm a compliant working branch before implementation
hivemind:adaptation-cycle	Run a pre-PR local Codex review on the current branch diff — invocable directly by users or via hivemind:local-reviewer
hivemind:github-review-loop	Watch a PR in the main session and dispatch the fix-mode github-reviewer per actionable event — owns the post-PR review loop
hivemind:open-plan-pr	Open a pull request after completion, validation, and versioning gates pass
hivemind:plan-interrogation	Interactive plan interview — challenges a plan against the project's domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) as decisions crystallise
hivemind:create-handoff	Generate an optional session-resumption handoff doc from a plan
hivemind:plan-to-prd	Turn an interrogated plan into a committed WHAT-only PRD
hivemind:prd-to-issues	Slice a PRD into vertically-sliced, brood-ready GitHub issues
hivemind:seed-hive	One-time project setup: write required .claude/settings.json keys (enabledPlugins + default agent) and add .hivemind/ to .gitignore
hivemind:tdd	Implement features using Test-Driven Development (TDD) with the red-green-refactor cycle — invoke only in a context that can modify source and test files
hivemind:spawn-brood	Dispatch parallel overlord sessions — spawns N Claude Code instances in separate git worktrees via tmux
hivemind:brood-status	Check status of all active brood sessions — reports per-strain tmux session state, branch existence, and PR status
hivemind:zoom-out	Zoom out for broader context — maps relevant modules and callers using the project's domain glossary vocabulary
hivemind:improving-architecture	Read-only architecture analysis — emits a ranked refactoring blueprint of deepening opportunities (shallow → deep modules) for testability and AI-navigability
hivemind:refactor-to-depth	Execution skill that performs a behavior-preserving deepening refactor via a refactor-under-green loop — the in-implementation counterpart to the read-only improving-architecture blueprint
hivemind:setup-project	DEPRECATED — renamed to hivemind:seed-hive. Stub forwards to the new skill; will be removed in a future MAJOR release.
hivemind:bootstrap-context	DEPRECATED — renamed to hivemind:creep-spread. Stub forwards to the new skill; will be removed in a future MAJOR release.

Governance

Reference documentation in plugin/governance/:

File	Contents
definitions.md	Canonical vocabulary, authority matrix, agent roles, and cross-agent constraints
workflow.md	Branch taxonomy, naming rules, commit and PR policy, overlord workflow
safety-rails.md	Hard-stop rules, security constraints, secret-handling, and escalation triggers
report-format.md	Phase-closing report schemas, handoff formats, and step-delta structure
versioning.md	SemVer rules, bump triggers, changelog and tag policy
security-policy.md	External content boundaries, destructive-fix confirmation gate, injection classification

Governance docs are plugin runtime data — agents load them via ${CLAUDE_PLUGIN_ROOT}/governance/ paths at runtime. They are load-bearing: renaming section headers or files can break agent rules that reference them. See CLAUDE.md for editing constraints.

Plugin limitations

The following agent frontmatter fields are not supported by the Claude Code plugin system and are omitted from plugin agent definitions:

• mcpServers — configure MCP servers at the project or global level instead
• permissionMode — read-only enforcement is achieved by limiting the cerebrate's tools frontmatter to read-only commands; see the cerebrate's tools list in plugin/agents/cerebrate.md

License

MIT