convez.ai
AgenteAutomaçãoAvançado
brenpike

Hivemind

brenpike/hivemind

Orquestração multi-agent autônoma para pipelines de código

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de orquestração multi-agent para Claude Code que coordena agentes especializados para planejar, construir, revisar e entregar código de forma autônoma. Elimina a necessidade de gerenciar manualmente o pipeline de desenvolvimento, funcionando como um enxame auto-coordenado de bioformas.

Instalação

$npx convez-ai brenpike/hivemind

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 dia
Versão
—
Issues abertas
67
Contribuidores
1

Casos de uso

  • Automação completa de ciclos de desenvolvimento (plan-build-review-ship)
  • Gestão de projetos Git com múltiplos agentes especializados
  • Redução de overhead gerencial em fluxos de codificação complexos

Veredito

Solução sofisticada de orquestração que automatiza pipelines de desenvolvimento via agentes especializados, mas requer setup complexo (bash, git, gh, integração com Claude Code) e conhecimento técnico profundo. Promissor para equipes que buscam eliminar gargalos gerenciais, mas ainda em estágio de maturação (v1.0.0 com suporte limitado a Windows).

README

A tradução para o português deste README ainda está na fila.

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.

  1. 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
  2. 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

BioformRoleWhat it does
:eye: OverlordOrchestratorThe control plane. Routes the Overmind's directives, distributes the cerebrate's plan, owns the git lifecycle, spawns specialists. Never writes code. Your main interface.
:brain: CerebrateStrategistOriginates the plan. Scans the territory and produces the directive — the intelligence the swarm executes. Read-only; thinks, never writes.
:hammer: DroneBuilderBuilds code within its assigned scope. The workhorse of the swarm.
:performing_arts: ChangelingShaperHandles 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

SignalMeaning
:fire: FlareUrgent — agent hit something it can't resolve alone. Overlord stops and asks you.
:zap: ReflexSimple task — overlord skips the cerebrate and spawns a drone directly.
:dna: Mutation DecayTwo fixes are fighting each other. Swarm stops. You decide.
:arrows_counterclockwise: Adaptation CycleReview 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

AgentRole
hivemind:overlordDefault agent. Coordinates all work, owns git workflow, branch/PR decisions, versioning decisions, and external review routing.
hivemind:cerebrateResearch and implementation planning. Read-only — no file writes.
hivemind:droneImplementation within explicitly assigned file scope.
hivemind:changelingPresentational UI/UX work within explicitly assigned file scope.
hivemind:local-reviewerPre-PR iterative Codex review with self-owning fix delegation at sonnet tier.
hivemind:github-reviewerStateless 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:

SkillPurpose
hivemind:creep-spreadAnalyze 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:moltCommit a completed phase, milestone, version bump, or review-remediation item
hivemind:create-working-branchCreate or confirm a compliant working branch before implementation
hivemind:adaptation-cycleRun a pre-PR local Codex review on the current branch diff — invocable directly by users or via hivemind:local-reviewer
hivemind:github-review-loopWatch a PR in the main session and dispatch the fix-mode github-reviewer per actionable event — owns the post-PR review loop
hivemind:detect-remediation-signalsShared root-cluster / break-fix / diminishing-returns / stop-and-merge detector over a fix-ledger — emits one verdict both reviewers map to their own exit_reason
hivemind:injection-scanScan external-content items for prompt-injection / instruction-override attempts against the security-policy taxonomy — shared judgment skill used by both reviewer agents
hivemind:open-plan-prOpen a pull request after completion, validation, and versioning gates pass
hivemind:push-branchPush the current working branch to its remote (no PR creation) — used to land remediation commits before resuming a review loop
hivemind:plan-interrogationInteractive plan interview — challenges a plan against the project's domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) as decisions crystallise
hivemind:create-handoffGenerate an optional session-resumption handoff doc from a plan
hivemind:plan-to-prdTurn an interrogated plan into a committed WHAT-only PRD
hivemind:prd-to-issuesSlice a PRD into vertically-sliced, brood-ready GitHub issues
hivemind:triage-backlogJudgment-driven triage of the entire open GitHub issue backlog across 7 mutually-exclusive label families (readiness/type/effort/moscow/priority/risk/difficulty) plus native GitHub issue dependencies; renders a delta table and applies labels behind a confirm gate; honors the human-only triage:locked control label
hivemind:seed-hiveOne-time project setup: write required .claude/settings.json keys (enabledPlugins + default agent) and add .hivemind/ to .gitignore
hivemind:tddImplement 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-broodDispatch parallel overlord sessions — spawns N Claude Code instances in separate git worktrees via tmux
hivemind:brood-statusCheck status of broods under the current checkout, with per-strain status — reports per-strain tmux session state, branch existence, and PR status
hivemind:route-workflowSole workflow classifier — selects which workflow handles a non-Reflex request by judgment (never a keyword table); emits selected / ambiguous / exploratory / blocked
hivemind:init-run-ledgerInitialize the run ledger for the current overlord instance — creates .hivemind/runs/<run-id>/ and writes the initial state.json via the committed engine script
hivemind:record-state-resultRecord 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
hivemind:mark-intent-fallbackSanctioned engine write-path for the version-skew intent-fallback resume door and start-fresh stale-run closeout — sets run.mode:intent_fallback, appends a fallback event, and optionally closes a stale run via run.status
hivemind:zoom-outZoom out for broader context — maps relevant modules and callers using the project's domain glossary vocabulary
hivemind:improving-architectureRead-only architecture analysis — emits a ranked refactoring blueprint of deepening opportunities (shallow → deep modules) for testability and AI-navigability
hivemind:refactor-to-depthExecution 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-projectDEPRECATED — renamed to hivemind:seed-hive. Stub forwards to the new skill; will be removed in a future MAJOR release.
hivemind:bootstrap-contextDEPRECATED — 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/:

FileContents
definitions.mdCanonical vocabulary, authority matrix, agent roles, and cross-agent constraints
workflow.mdBranch taxonomy, naming rules, commit and PR policy, overlord workflow
safety-rails.mdHard-stop rules, security constraints, secret-handling, and escalation triggers
report-format.mdPhase-closing report schemas, handoff formats, and step-delta structure
versioning.mdSemVer rules, bump triggers, changelog and tag policy
security-policy.mdExternal content boundaries, destructive-fix confirmation gate, injection classification
remediation-doctrine.mdShared root-cause remediation vocabulary and policy — root-cluster, same-framing test, closed-by-construction, bounded-impact gating, stop-and-merge

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

Ver o original no GitHub

Bom para

Relacionados