claude-hive-agents

A drop-in Claude Code plugin that turns Claude into a multi-agent development team. A PM agent decomposes features into task graphs, dev agents implement in isolated worktrees, a reviewer validates code, and QA checks integration — all coordinated automatically.

How It Works

You: /claude-hive-agents:orchestrate "Add user authentication with JWT"
                              |
                         PM Agent (opus)
                    Complexity assessment → routing
                              |
              ┌───────────────┼───────────────┐
         Simple Path     Full Path        Full Path
         (score 0-1)    (score 2-4)      (score 2-4)
              |               |                |
         Single task     Epic → Features → Tasks
              |               |                |
         dev → reviewer   dev agents (parallel, worktrees)
              |               |                |
         PM closes        reviewer → PM closes tasks
                              |
                         QA validates features
                              |
                         PM epilogue (merge → close epic)

The Agents

| Agent | Role | Model | |-------|------|-------| | pm-agent | Decomposes features, manages task graphs, runs epilogue | opus | | backend-dev | Implements backend tasks in isolated worktrees | sonnet | | frontend-dev | Implements frontend/UI tasks, consumes API contracts | sonnet | | reviewer | Reviews diffs, approves or rejects, merges branches | opus | | qa-agent | Validates integrated features across tasks | sonnet |

Key Features

• Complexity-based routing — Simple requests get one task (fast). Complex requests get a full epic/feature/task hierarchy with QA.
• Worktree isolation — Each dev agent works in its own git worktree. No conflicts.
• Contract-driven handoff — Backend agents publish output contracts; frontend agents consume them. No guessing.
• Memory system — Captures patterns, decisions, and lessons from every task. PM queries memory before planning. Local embeddings via Nomic Embed v2 (no API keys needed).
• Real-time dashboard — Kanban board at http://localhost:3827 with drag-drop, agent status, and WebSocket updates.
• Checkpoint/resume — Orchestration state is saved at every phase. Crashed sessions resume where they left off.

Prerequisites

| Tool | Purpose | Install | |------|---------|---------| | Node.js ≥ 18 | Scripts, dashboard, embedding | nodejs.org | | Dolt | Git-for-data database (task storage) | dolthub.com/docs | | Beads (bd) | Task management CLI | github.com/steveyegge/beads | | Claude Code | AI coding assistant with plugin support | docs.anthropic.com | | Git | Version control | git-scm.com |

Installation

From GitHub (recommended)

# In Claude Code
/plugin install https://github.com/mdondavid/claude-hive-agents.git

From local clone

# Clone the repo
git clone https://github.com/mdondavid/claude-hive-agents.git

# In Claude Code — add as local plugin
claude --plugin-dir /path/to/claude-hive-agents

Quick Start

1. Setup (one-time per project)

/claude-hive-agents:setup

This interactive wizard:

• Verifies all dependencies are installed
• Initializes Beads (bd init) and Dolt database
• Creates .hive/config.json with service configuration
• Starts background services (Dolt, dashboard, watcher)
• Creates agent wisps for task dispatch

2. Orchestrate a feature

/claude-hive-agents:orchestrate "Add user authentication with JWT login and session management"

Or pass a plan file (see examples):

/claude-hive-agents:orchestrate docs/plans/example-full-user-auth.md

The PM agent assesses complexity, creates a task graph, and the pipeline runs automatically.

Example plans included:

• example-simple-add-health-endpoint.md — Single task, triggers simple path
• example-full-user-auth.md — 4 tasks across backend + frontend, triggers full path with QA

3. Monitor progress

/claude-hive-agents:task-status

Opens the real-time dashboard at http://localhost:3827.

Commands

| Command | Description | |---------|-------------| | /claude-hive-agents:orchestrate <description\|plan.md> | Full multi-agent workflow | | /claude-hive-agents:plan-feature <description> | Plan only (no execution) | | /claude-hive-agents:claim-task [agent\|task-id] | Dispatch agent to claim work | | /claude-hive-agents:review-task [task-id] | Show/dispatch pending reviews | | /claude-hive-agents:setup | One-time project setup | | /claude-hive-agents:services start\|stop\|status | Manage background services | | /claude-hive-agents:task-status | Open real-time dashboard |

Architecture

Task Hierarchy

Epic (container — full path only)
├── Feature (QA validates at this level)
│   ├── Task → dev claims → worktree → implements → commits
│   │        → ready_for_review → reviewer reviews
│   │        → approved → merge → PM closes → captures memory
│   └── Task (parallel)
└── Feature 2
    └── Tasks...

Coordination Modes

• Team Mode (default) — Uses Claude Code Agent Teams with real-time messaging between agents
• Signal Mode (fallback) — Dolt-polling watcher dispatches agents via bd ready --assignee

Memory Pipeline

1. Capture — On bd close, extracts outputs, designs, and review findings from task comments
2. Process — Normalizes and scores entries (novelty, usefulness, reusability, confidence)
3. Embed — Generates 768-dim vectors using local Nomic Embed v2 (~500MB, auto-downloaded)
4. Query — PM searches memory before planning; dev agents read memory_context from task metadata

Configuration

After setup, .hive/config.json controls:

{
  "project": "my-project",
  "database": "beads_my-project",
  "auto_start": true,
  "coordination": { "mode": "teams" },
  "services": {
    "dolt": { "host": "127.0.0.1", "port": 3307 },
    "dashboard": { "port": 3827 },
    "watcher": { "poll_ms": 5000, "agents": ["pm-agent", "backend-dev", "frontend-dev", "reviewer", "qa-agent"] }
  },
  "models": {
    "default": "sonnet",
    "pm-agent": "opus",
    "simple": { "dev": "haiku", "reviewer": "haiku", "epilogue": "haiku" }
  }
}

Cost Optimization

The plugin uses model tiering to minimize costs:

• PM planning: Always opus (needs reasoning for decomposition)
• Full path devs/reviewer: sonnet (balanced quality/cost)
• Simple path: haiku for dev, reviewer, and epilogue (fast, cheap for small tasks)
• QA: haiku (validation is lightweight)

Override models via .hive/config.json models section.

Contributing

See CONTRIBUTING.md.

License

MIT