{"id":50488647,"url":"https://github.com/brenpike/hivemind","last_synced_at":"2026-06-02T00:30:58.212Z","repository":{"id":354799723,"uuid":"1225183223","full_name":"brenpike/hivemind","owner":"brenpike","description":"Multi-agent orchestration framework for Claude Code — a self-coordinating swarm of specialized bioforms that plans, builds, reviews, and ships code so you don't manage the pipeline yourself.","archived":false,"fork":false,"pushed_at":"2026-05-30T17:17:13.000Z","size":1707,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T18:14:06.749Z","etag":null,"topics":["agent-orchestration","agentic-workflow","ai","ai-agents","anthropic","automation","claude","claude-code","code-review","developer-tools","llm","multi-agent","plugin","swarm"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brenpike.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T03:03:22.000Z","updated_at":"2026-05-29T15:33:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/brenpike/hivemind","commit_stats":null,"previous_names":["brenpike/agent-framework","brenpike/hivemind"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/brenpike/hivemind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brenpike%2Fhivemind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brenpike%2Fhivemind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brenpike%2Fhivemind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brenpike%2Fhivemind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brenpike","download_url":"https://codeload.github.com/brenpike/hivemind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brenpike%2Fhivemind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33800675,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agentic-workflow","ai","ai-agents","anthropic","automation","claude","claude-code","code-review","developer-tools","llm","multi-agent","plugin","swarm"],"created_at":"2026-06-02T00:30:58.109Z","updated_at":"2026-06-02T00:30:58.206Z","avatar_url":"https://github.com/brenpike.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hivemind\n\nMulti-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.\n\n## Install\n\nInside Claude Code, add the marketplace then install the plugin:\n\n```text\n/plugin marketplace add https://github.com/brenpike/hivemind.git\n/plugin install hivemind@brenpike\n```\n\n## Requirements\n\n- **bash** (macOS, Linux, or WSL on Windows)\n- **git** and **gh** (GitHub CLI)\n- Claude Code CLI\n\nAs of v1.0.0, PowerShell and native Windows support have been removed. All toolchain scripts are bash-based.\n\n## Per-project setup\n\n1. Enable the plugin and set the overlord as the session default agent in `.claude/settings.json`:\n\n```json\n{\n  \"enabledPlugins\": {\n    \"hivemind@brenpike\": true\n  },\n  \"agent\": \"hivemind:overlord\"\n}\n```\n\nThe `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.\n\nOr run the setup skill once to apply the required keys automatically:\n\n```text\n/hivemind:seed-hive\n```\n\nThe 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.\n\n`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).\n\n**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:\n\n```text\n/hivemind:seed-hive seed_allowlist=no\n```\n\nThe 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 `\u003e /dev/null` is exempt) and splits compound commands (`\u0026\u0026`/`||`/`;`/`|`/newline), requiring each subcommand to match a rule independently — so granting them does not create an arbitrary-file-write vector (`echo evil \u003e /etc/passwd`, `printf x \u003e ~/.bashrc`, `cmd \u0026\u0026 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.\n\nFor 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`):\n\n```json\n\"Bash(node /path/to/.claude/plugins/cache/openai-codex/codex/*)\"\n```\n\nReplace `/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.\n\n2. Create `CLAUDE.md` with project-specific details:\n   - Build/test commands\n   - Package names and version file paths\n   - Versioning configuration (bump triggers, changelogs, tag prefixes)\n   - Architecture and code style notes\n\n3. Create `AGENTS.md` at the project root with project-specific Codex review guidance. Include:\n   - Review focus areas\n   - Severity definitions\n   - Project-specific conventions for reviewers\n\nOnce configured, the overlord is the session default agent. All skills are available namespaced as `hivemind:\u003cskill-name\u003e`.\n\n## Recommended companion plugins\n\n- [`claude-mem`](https://github.com/thedotmack/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`](https://astral.sh/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).\n\n- [`codex`](https://github.com/openai/codex-plugin-cc) — provides local and GitHub-integrated Codex code review. Install and configure with:\n  ```text\n  /plugin marketplace add https://github.com/openai/codex-plugin-cc.git\n  /plugin install codex@openai-codex\n  /reload-plugins\n  /codex:setup\n  ```\n  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.\n\n- [`caveman`](https://github.com/juliusbrussee/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`:\n  ```json\n  \"enabledPlugins\": { \"caveman@caveman\": true },\n  \"pluginConfigs\": { \"caveman@caveman\": { \"options\": { \"defaultLevel\": \"ultra\" } } }\n  ```\n\n## Dev container\n\nThis 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).\n\n**Auto-provisioned** by `.devcontainer/postCreate.sh`:\n\n- 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.\n- CLI tools via npm global — Claude Code CLI (`@anthropic-ai/claude-code`), Codex CLI (`@openai/codex`), `claude-mem`.\n- `uv` / `uvx` (Astral) via the official install script — claude-mem's optional vector-search backend.\n- `tmux` via apt — terminal multiplexer used by the `hivemind:spawn-brood` / `hivemind:brood-status` skills.\n- `bun` via the official installer (`bun.sh/install`) — fast JS runtime required by `claude-mem`.\n- 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.\n\n**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:\n\n```text\nclaude plugin install hivemind@brenpike\nclaude plugin install codex@openai-codex\nclaude plugin install claude-mem@thedotmack\nclaude plugin install caveman@caveman\n/codex:setup\n```\n\n**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.\n\nThe 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.\n\nThe 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.\n\nSee `.devcontainer/README.md` for full launch instructions (Codespaces and local Dev Containers), the complete list of what is auto-provisioned, and troubleshooting.\n\n## After cloning a project that uses this plugin\n\n```text\n/plugin marketplace add https://github.com/brenpike/hivemind.git\n/plugin install hivemind@brenpike\n```\n\n## The Swarm\n\nHivemind coordinates specialized bioforms to plan, build, review, and ship code — so you don't have to manage the pipeline yourself.\n\n### Know Your Bioforms\n\n| Bioform | Role | What it does |\n|---|---|---|\n| :eye: **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. |\n| :brain: **Cerebrate** | Strategist | Originates the plan. Scans the territory and produces the **directive** — the intelligence the swarm executes. Read-only; thinks, never writes. |\n| :hammer: **Drone** | Builder | Builds code within its assigned scope. The workhorse of the swarm. |\n| :performing_arts: **Changeling** | Shaper | Handles UI, styling, and visual presentation. Reshapes how things look and feel. |\n\n### The Lifecycle\n\n```\nYou --\u003e Overlord --\u003e Cerebrate (plan) --\u003e Directive\n                 --\u003e Drone/Changeling (build) --\u003e Essence\n                 --\u003e Adaptation Cycle (review) --\u003e PR\n```\n\n1. You give the **overlord** a task\n2. The **cerebrate** scans the territory and returns a **directive**\n3. The overlord **spawns** specialists (**drones** / **changelings**) phase by phase\n4. Each phase produces **essence** — knowledge carried forward\n5. An **adaptation cycle** reviews the work before shipping\n6. A PR is opened when the swarm stabilizes\n\n### Brood Mode — Parallel Execution\n\nWhen 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.\n\n```\nYou --\u003e Overlord --\u003e Cerebrate (decompose)\n                 --\u003e \"3 independent strains detected. Deploy brood?\"\n                 --\u003e Yes --\u003e Hatchery mode\n                           --\u003e Strain A (tmux tab) --\u003e own branch, own PR\n                           --\u003e Strain B (tmux tab) --\u003e own branch, own PR\n                           --\u003e Strain C (tmux tab) --\u003e own branch, own PR\n```\n\nThe overlord enters **hatchery** mode — monitoring the brood from home base while each strain evolves independently.\n\n### Signals\n\n| Signal | Meaning |\n|---|---|\n| :fire: **Flare** | Urgent — agent hit something it can't resolve alone. Overlord stops and asks you. |\n| :zap: **Reflex** | Simple task — overlord skips the cerebrate and spawns a drone directly. |\n| :dna: **Mutation Decay** | Two fixes are fighting each other. Swarm stops. You decide. |\n| :arrows_counterclockwise: **Adaptation Cycle** | Review in progress — the swarm is stabilizing before shipping. |\n\n### Plain English Still Works\n\nEvery themed term maps to a plain concept. You don't need to learn the language to use the framework:\n\n| You can say... | Or say... | Same thing |\n|---|---|---|\n| \"checkpoint commit\" | \"molt\" | Save progress at a phase boundary |\n| \"spawn a brood\" | \"dispatch a fleet\" | Run parallel sessions |\n| \"what's the status\" | \"brood status\" | Check progress across sessions |\n| \"plan this\" | \"send the cerebrate\" | Get a plan before building |\n\nThe theme is for fun. The framework works with or without it.\n\n## Repository layout\n\n```\n.claude-plugin/\n  marketplace.json          # marketplace manifest (lives at repo root; points to ./plugin)\nplugin/                     # plugin root — everything Claude Code loads lives here\n  .claude-plugin/\n    plugin.json             # plugin manifest\n  agents/                   # agent definitions (overlord, cerebrate, drone, changeling, local-reviewer, github-reviewer)\n  skills/                   # skill definitions (incl. _shared/ helpers)\n  governance/               # runtime governance docs loaded via ${CLAUDE_PLUGIN_ROOT}/governance/\ndocs/\ntools/                      # dev-only validation scripts (policy linter, report validator)\ntests/                      # dev-only test fixtures and checks (policy, reports, plugin compatibility)\nAGENTS.md                   # project-specific Codex reviewer guidance\nCHANGELOG.md                # project changelog (Keep a Changelog format)\nCLAUDE.md                   # project instructions for Claude Code\nREADME.md\n```\n\n`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.\n\n`tools/` and `tests/` contain development-time validation scripts and test fixtures. They live outside `plugin/` and are not distributed as plugin runtime data.\n\n`${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.\n\n## Agents\n\n| Agent | Role |\n|---|---|\n| `hivemind:overlord` | Default agent. Coordinates all work, owns git workflow, branch/PR decisions, versioning decisions, and external review routing. |\n| `hivemind:cerebrate` | Research and implementation planning. Read-only — no file writes. |\n| `hivemind:drone` | Implementation within explicitly assigned file scope. |\n| `hivemind:changeling` | Presentational UI/UX work within explicitly assigned file scope. |\n| `hivemind:local-reviewer` | Pre-PR iterative Codex review with self-owning fix delegation at sonnet tier. |\n| `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. |\n\n## Skills\n\nAll skills are invoked using the namespaced form:\n\n| Skill | Purpose |\n|---|---|\n| `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 |\n| `hivemind:molt` | Commit a completed phase, milestone, version bump, or review-remediation item |\n| `hivemind:create-working-branch` | Create or confirm a compliant working branch before implementation |\n| `hivemind:adaptation-cycle` | Run a pre-PR local Codex review on the current branch diff — invocable directly by users or via `hivemind:local-reviewer` |\n| `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 |\n| `hivemind:open-plan-pr` | Open a pull request after completion, validation, and versioning gates pass |\n| `hivemind:push-branch` | Push the current working branch to its remote (no PR creation) — used to land remediation commits before resuming a review loop |\n| `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 |\n| `hivemind:create-handoff` | Generate an optional session-resumption handoff doc from a plan |\n| `hivemind:plan-to-prd` | Turn an interrogated plan into a committed WHAT-only PRD |\n| `hivemind:prd-to-issues` | Slice a PRD into vertically-sliced, brood-ready GitHub issues |\n| `hivemind:seed-hive` | One-time project setup: write required `.claude/settings.json` keys (enabledPlugins + default agent) and add `.hivemind/` to `.gitignore` |\n| `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 |\n| `hivemind:spawn-brood` | Dispatch parallel overlord sessions — spawns N Claude Code instances in separate git worktrees via tmux |\n| `hivemind:brood-status` | Check status of all active brood sessions — reports per-strain tmux session state, branch existence, and PR status |\n| `hivemind:route-workflow` | Sole workflow classifier — selects which workflow handles a non-Reflex request by judgment (never a keyword table); emits selected / ambiguous / exploratory / blocked |\n| `hivemind:init-run-ledger` | Initialize the run ledger for the current overlord instance — creates `.hivemind/runs/\u003crun-id\u003e/` and writes the initial `state.json` via the committed engine script |\n| `hivemind:record-state-result` | Record the outcome of the current workflow state into the run ledger and advance `state.current` to the legal next state, validated against the workflow definition |\n| `hivemind:zoom-out` | Zoom out for broader context — maps relevant modules and callers using the project's domain glossary vocabulary |\n| `hivemind:improving-architecture` | Read-only architecture analysis — emits a ranked refactoring blueprint of deepening opportunities (shallow → deep modules) for testability and AI-navigability |\n| `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 |\n| `hivemind:setup-project` | DEPRECATED — renamed to `hivemind:seed-hive`. Stub forwards to the new skill; will be removed in a future MAJOR release. |\n| `hivemind:bootstrap-context` | DEPRECATED — renamed to `hivemind:creep-spread`. Stub forwards to the new skill; will be removed in a future MAJOR release. |\n\n## Governance\n\nReference documentation in `plugin/governance/`:\n\n| File | Contents |\n|---|---|\n| `definitions.md` | Canonical vocabulary, authority matrix, agent roles, and cross-agent constraints |\n| `workflow.md` | Branch taxonomy, naming rules, commit and PR policy, overlord workflow |\n| `safety-rails.md` | Hard-stop rules, security constraints, secret-handling, and escalation triggers |\n| `report-format.md` | Phase-closing report schemas, handoff formats, and step-delta structure |\n| `versioning.md` | SemVer rules, bump triggers, changelog and tag policy |\n| `security-policy.md` | External content boundaries, destructive-fix confirmation gate, injection classification |\n\nGovernance 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.\n\n## Plugin limitations\n\nThe following agent frontmatter fields are not supported by the Claude Code plugin system and are omitted from plugin agent definitions:\n\n- `mcpServers` — configure MCP servers at the project or global level instead\n- `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`\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrenpike%2Fhivemind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrenpike%2Fhivemind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrenpike%2Fhivemind/lists"}