HiveClaude

Coordina múltiples instancias de Claude Code para que trabajen juntas en un mismo proyecto.

HiveClaude es un broker MCP local que conecta varios agentes Claude Code entre sí. Cada agente tiene un rol (orquestador, coder, reviewer, etc.), comparte estado en una pizarra común, se coordina con tareas, bloqueos de archivos y mensajes directos — todo sin salir del terminal.

┌─────────────────────────────────────────────────────────┐
│                    Tu proyecto                          │
│                                                         │
│  agents/orchestrator/   agents/coder-backend/   ...    │
│  ┌─────────────────┐    ┌─────────────────┐            │
│  │  Claude Code    │    │  Claude Code    │            │
│  │  CLAUDE.md      │    │  CLAUDE.md      │            │
│  │  .mcp.json ─────┼────┼─── .mcp.json   │            │
│  │  hooks/         │    │  hooks/         │            │
│  └────────┬────────┘    └────────┬────────┘            │
│           │                      │                      │
│           └──────────┬───────────┘                      │
│                      ▼                                  │
│              ┌───────────────┐                          │
│              │  hive broker  │  :7432                  │
│              │  /mcp  /ping  │                          │
│              │  SQLite + BB  │                          │
│              └───────────────┘                          │
└─────────────────────────────────────────────────────────┘

Por qué usar HiveClaude

Mejor calidad de código — el reviewer realmente funciona

Un solo agente que implementa y luego "revisa" su propio código es el mismo modelo con el mismo sesgo. El reviewer de HiveClaude es una instancia separada que llega al código sin saber cómo fue construido — igual que un code review real. Detecta cosas distintas porque no cargó la historia de implementación.

Contexto enfocado — menos degradación en proyectos largos

Un agente único que trabaja en un proyecto grande acumula contexto de todo: frontend, backend, tests, errores pasados, caminos descartados. La calidad baja conforme el contexto crece. Con agentes especializados, cada uno carga solo lo que necesita. El coder-backend no sabe nada de CSS. El reviewer no sabe cómo se implementó la función. Eso mantiene la calidad estable.

Paralelismo real en trabajo delimitado

Mientras coder-backend implementa la API, coder-frontend ya construye los componentes. El broker gestiona las dependencias — frontend no empieza hasta que backend pasa QA, pero si son independientes corren al mismo tiempo. Para proyectos con partes bien separadas, el tiempo total se reduce.

Para quién tiene sentido

Related MCP server: Symphony of One MCP

⚠️ Aviso

• Beta: v0.6 — coordinación adaptativa completa + QA verificación activa + self-review imposible. Tests estables. Úsalo en proyectos reales con precaución.

• Costo: cada agente consume tokens de forma independiente — 4 agentes activos equivale a 4x el consumo normal de Claude Code

• Permisos: el flag --yolo elimina las confirmaciones de Claude Code — revisa bien el plan antes de aprobarlo

Prerequisitos

• Node.js 22+ (usa node:sqlite built-in)

• Claude Code instalado (npm install -g @anthropic-ai/claude-code)

• npm 10+

Instalación

Opción A — Desde el repositorio (desarrollo local)

git clone https://github.com/andrewcorpdesing-coder/hiveclaude
cd hiveclaude
npm install
npm run build
npm run link:local      # registra 'hiveclaude' globalmente via npm link

Opción B — Desde npm

npm install -g hiveclaude

Quick Start

Forma rápida — un solo comando

cd mi-proyecto
hiveclaude init
hiveclaude run "implementa autenticación JWT"

hiveclaude run arranca el broker, abre terminales para los agentes principales (orchestrator, coder-backend, coder-frontend, reviewer) y encola la tarea en un solo paso. Cada agente empieza solo al presionar Enter en su terminal.

Forma manual — control total

# 1. Inicializar en tu proyecto
cd mi-proyecto
hiveclaude init

# 2. Arrancar el broker en background
hiveclaude start

# 3. Crear directorios de agentes con prompts, hooks MCP y ramas git
hiveclaude scaffold

# 4. Abrir terminales por rol
hiveclaude exec --launch orchestrator coder-backend reviewer

# 5. El orquestador presentará un plan en su terminal.
#    Cuando esté listo, apruébalo desde cualquier terminal:
hiveclaude approve

Flujo de trabajo

1. Planning Protocol

El orquestador nunca ejecuta sin plan aprobado. El flujo es siempre:

orquestador recibe tarea
       ↓
hace preguntas al usuario si necesita claridad
       ↓
presenta plan estructurado en su terminal:
  - SCOPE / OUT OF SCOPE
  - FILES que se tocarán
  - TASKS con rol y dependencias
  - ASSUMPTIONS
       ↓
espera aprobación (hive_wait)
       ↓
  hiveclaude approve  ←── tú desde la CLI
       ↓
crea tareas y notifica a los workers

Puedes ver el plan en cualquier momento:

hiveclaude plan            # muestra el plan actual (draft o aprobado)
hiveclaude approve         # aprueba el plan — el orquestador empieza a crear tareas
hiveclaude reject "texto"  # rechaza con feedback — el orquestador revisa y re-presenta

2. Ejecución y QA

Los workers toman tareas via hive_get_next_task. El DAG de dependencias es automático — cuando una tarea es aprobada por QA, el broker desbloquea las dependientes y notifica a los agentes del rol correcto con un evento task_available. No hace falta coordinación manual.

El reviewer opera solo a través del pipeline QA:

• Recibe evento task_submitted_for_qa

• Llama hive_get_pending_reviews para ver la cola

• Aprueba o rechaza con hive_submit_review

• Nunca reclama tareas normales — solo revisa

3. Fin de sesión

Cuando todas las tareas están completadas, el broker emite automáticamente sprint_complete a todos los agentes. Cada uno llama hive_end_session y para. El orquestador guarda el contexto en knowledge.session_log para que la próxima sesión retome sin re-explorar el proyecto.

Comandos CLI

Roles disponibles

No necesitas usar todos los roles — arranca con orchestrator + 1-2 coders.

Selección de modelo por rol

hiveclaude exec                                                        # imprime comandos (no abre nada)
hiveclaude exec orchestrator:opus coder-backend:sonnet reviewer:haiku  # override por rol
hiveclaude exec --launch orchestrator coder-backend reviewer           # abre todos en una sola ventana (tabs)
hiveclaude exec --launch --yolo orchestrator coder-backend reviewer    # sin prompts de permisos

--launch abre una sola ventana de Windows Terminal con paneles divididos y --dangerously-skip-permissions activado para que los agentes corran sin prompts. Layout adaptativo:

• 3 agentes (el caso típico): orquestador a la izquierda (altura completa), workers apilados a la derecha

• 2 agentes: lado a lado

• 4+ agentes: apilados horizontalmente

En macOS abre tabs en Terminal.app. En Linux abre una ventana por agente como fallback.

Cómo funciona

Conexión MCP

Cada directorio agents/<rol>/ contiene un .mcp.json que apunta al broker:

{
  "mcpServers": {
    "hivemind": {
      "type": "http",
      "url": "http://localhost:7432/mcp"
    }
  }
}

Claude Code lo detecta automáticamente al abrir ese directorio.

Herramientas MCP disponibles para los agentes

Eventos del broker (recibidos via hive_wait)

Pizarra compartida (Blackboard)

Estado compartido persistido en SQLite (.hive/tasks.db, tabla blackboard) con dual-write a .hive/blackboard.json para compatibilidad. Estructura:

project.meta            — metadatos del proyecto
project.architecture    — decisiones de arquitectura
project.conventions     — convenciones de código
knowledge.discoveries   — hallazgos relevantes
knowledge.warnings      — problemas conocidos
knowledge.external_apis — contratos de APIs externas
knowledge.session_log   — historial de sesiones del orquestador
state.current_plan      — plan activo (draft → approved → executing → completed)
state.sprint            — sprint actual
state.blockers          — bloqueos activos
state.milestones        — hitos del proyecto
state.pending_input     — tarea encolada esperando al orquestador
agents.<id>             — estado por agente
qa.findings             — resultados de QA
qa.metrics              — métricas de calidad
qa.pending_review       — cola de revisiones pendientes

Bloqueos de archivos

Antes de editar un archivo, el agente declara qué archivos toca. Si otro agente tiene el archivo bloqueado, espera en cola y recibe lock_granted cuando queda libre. Tipos de lock: EXCLUSIVE (escritura), READ (lectura compartida), SOFT (referencia sin bloqueo).

Pipeline de QA

Las tareas completadas por workers pasan a qa_pending. El reviewer las inspecciona con hive_get_pending_reviews y antes de aprobar o rechazar ejecuta hive_verify_task — checks automáticos (tsc, file_exists, http shape validation, exec) que convierten el review de razonamiento en verificación determinista.

Al aprobar:

• La tarea pasa a completed

• El broker desbloquea automáticamente las tareas dependientes

• Los agentes del rol correcto reciben task_available y retoman trabajo sin intervención del orquestador

• Si todas las tareas están completadas, el broker emite sprint_complete a todos los agentes

Si son rechazadas, vuelven al agente original (needs_revision) con feedback específico y accionable.

Self-review imposible: el broker rechaza con SELF_REVIEW_FORBIDDEN cualquier intento de un agente de aprobar su propia tarea — independientemente del prompt. Un agente que actúa solo nunca puede completar el ciclo completo.

El orquestador nunca crea tareas con assigned_role: reviewer. El reviewer solo opera a través del pipeline QA, no como worker normal.

Auto-heartbeat

hive scaffold genera un hook PostToolUse en cada directorio de agente. Cada vez que el agente ejecuta Write, Edit o MultiEdit, el hook dispara automáticamente un heartbeat al broker — manteniendo la sesión y los file locks vivos sin que el agente tenga que recordarlo.

Workflow de ramas git

Si el proyecto es un repositorio git, hive scaffold crea la rama hive/<rol> para cada agente. El orquestador mergea el trabajo aprobado a main:

coder trabaja en hive/coder-backend
    ↓
QA aprueba
    ↓
orchestrator → hive_merge_branch("hive/coder-backend", task_id)
    ↓
main siempre tiene solo código aprobado

Si hay conflictos de merge, el tool aborta limpiamente y devuelve la lista de archivos en conflicto.

Persistencia de sesión

Antes de parar, el orquestador guarda el contexto de la sesión con hive_end_session:

{
  "key_decisions": ["Elegimos JWT con 1h expiry"],
  "next_actions": ["Implementar DELETE /users/:id"],
  "warnings": ["Migración falla si DB_URL no está en el entorno"],
  "tasks_completed": ["task-1", "task-2"],
  "tasks_blocked": ["task-3"]
}

Al arrancar la próxima sesión, el orquestador lee knowledge.session_log y retoma el trabajo sin re-explorar el proyecto desde cero.

Coordinación adaptativa (v0.2–v0.5)

El broker no es solo un router — es un coordinador activo que aprende y actúa.

Thompson Sampling — routing por calidad con decay temporal (v0.3)

hive_get_next_task no devuelve tareas en orden FIFO. Usa Thompson Sampling Beta(α,β) combinado con decay temporal para priorizar la siguiente tarea:

composite = θ×0.5 + decayScore×timeFactor×0.5
timeFactor = 0.2 + 0.8×e^(-age/τ)

τ varía por tipo de tarea: bugfix=12h (urgente), feature=48h, architecture=72h. Tareas antiguas salen de la cola antes de que expiren sus ventanas de relevancia. El historial persiste en .hive/tasks.db.

HeterosynapticCapture — propagación de señales de calidad (v0.2–v0.3)

Cuando el reviewer rechaza con severity: "critical", la señal se propaga hacia adelante:

• La tarea rechazada recibe quality_floor = 0.85 (Tier 1)

• Todas las tareas pendientes que tocan los mismos archivos reciben quality_floor = 0.70 (Tier 2)

• El floor decae con cada aprobación: floor × e^(-1/5) — ~5 aprobaciones para reducirlo a la mitad

Esto significa que un error crítico eleva el estándar para ese módulo sin intervención manual, y que la señal de error desaparece orgánicamente si el módulo luego funciona bien.

DAG de dependencias + Critical Path Method (v0.4–v0.6)

Las dependencias entre tareas son un grafo real persistido en SQLite. hive_add_dependency añade aristas con detección de ciclos (Kahn's BFS). El broker ejecuta CPM (ES/EF/LS/LF, Float=0 = crítico) en dos lugares:

• Scheduler (getNextAvailable): ordena tareas disponibles por is_critical_path DESC, float_minutes ASC — las tareas en la ruta crítica salen primero de la cola, reduciendo makespan. El campo estimated_duration_minutes en hive_create_task alimenta este cálculo (default: 60 min). CPM se recalcula automáticamente al crear tareas y al aprobar revisiones.

• FEP health probe (critical_path_health): solo alerta cuando tareas en estado blocked tienen Float≈0. Bloqueos fuera de la ruta crítica no degradan el probe.

HiveCriticalityEngine — κ (salud sistémica)

El broker mide κ ∈ [0,1] sobre 3 probes (routing entropy, completion variance, review score variance). κ indica si el equipo está en la zona óptima de coordinación (borde del caos, κ ∈ [0.40, 0.60]) o drifteando hacia rigidez o caos.

Disponible en GET /admin/health. El monitor lo muestra en tiempo real.

FreeEnergyCoordinator — F con loop de aprendizaje (v0.2–v0.3)

El coordinator calcula F = Σwᵢ·Uᵢ sobre 6 probes cada N minutos (adaptativo según modo):

Cada intervención queda registrada en coordinator_interventions (SQLite). El F real 30 minutos después retroalimenta si la intervención funcionó. Con ≥30 outcomes, calibrateWeights() ajusta los pesos por gradient descent — los probes que más reducen F reciben más peso.

Cuando F ≥ 0.55 el coordinator envía eventos a los agentes relevantes. Cuando F ≥ 0.80 envía coordinator_critical_alert a todos y el orquestador detiene nuevas asignaciones.

Verificación activa del reviewer — hive_verify_task (v0.6)

El reviewer no es solo un agente de razonamiento — tiene acceso a hive_verify_task para ejecutar checks concretos antes de aprobar cualquier tarea:

Esto cierra el gap entre "el código razonablemente parece correcto" y "el código funciona". Los bugs de contrato de API — que pasan tsc --noEmit pero fallan en runtime por shape mismatches — son detectables directamente.

Auto-ejecución del orquestador (v0.5)

Cuando el proyecto tiene historial, el sistema está en modo flowing (F < 0.30), y el objetivo es de bajo riesgo (más archivos nuevos que modificados, sin tareas de arquitectura, < 4h estimado), el orquestador puede llamar hive_auto_plan con risk="low" y recibir auto_approved=true — crea las tareas sin esperar aprobación humana.

Monitor en tiempo real

Con el broker corriendo, abre en el navegador:

http://localhost:7432/monitor

Dashboard con auto-refresh cada 3 segundos.

Franja de coordinación (parte superior):

Los colores son intuitivos: verde = bien, amarillo = atención, naranja = problemas, rojo = crítico.

Tareas: el badge floor 0.85 aparece en cualquier tarea con quality_floor elevado — visible de un vistazo cuáles están marcadas por rechazos críticos anteriores.

Admin API

El broker expone endpoints REST para monitoreo externo y control desde la CLI:

GET  /ping                                — health check
GET  /admin/agents[?status=online]        — listar agentes
DEL  /admin/agents/:id                    — forzar agente offline
POST /admin/agents/:id/heartbeat          — heartbeat externo (usado por hooks)
GET  /admin/tasks[?status=...]            — listar tareas
GET  /admin/tasks/:id                     — detalle de tarea
POST /admin/tasks/:id/force-complete      — completar tarea sin QA
GET  /admin/locks                         — bloqueos activos y en cola
GET  /admin/blackboard                    — snapshot completo de la pizarra
GET  /admin/audit[?agent_id=&action=&result=&since=&limit=]
POST /admin/input                         — encolar tarea para el orquestador (usado por hiveclaude task / hiveclaude run)
GET  /admin/plan                          — plan actual del orquestador
POST /admin/plan/approve                  — aprobar plan (usado por hiveclaude approve)
POST /admin/plan/reject                   — rechazar plan con feedback (usado por hive reject)
GET  /admin/health                              — CriticalityReport: κ, zona, trend, 3 probes (persiste snapshot)
GET  /admin/health/history[?limit=N]            — histórico de snapshots de κ + calibración PCA si ≥30
GET  /admin/coordinator                         — FepReport: F, modo, 6 probes (dispara tick, actualiza blackboard)
GET  /admin/coordinator/interventions[?limit=N] — historial de intervenciones + calibración si ≥30 outcomes

Estructura de archivos generada

mi-proyecto/
├── .mcp.json                      ← Claude Code lo lee en la raíz
├── .hive/
│   ├── hive.config.json           ← config del broker (port, models por rol)
│   ├── tasks.db                   ← SQLite (tareas, mensajes, locks, audit)
│   ├── blackboard.json            ← pizarra compartida
│   ├── broker.pid                 ← PID del daemon
│   └── broker.log                 ← logs del broker
└── agents/
    ├── orchestrator/
    │   ├── CLAUDE.md              ← system prompt completo del rol
    │   ├── .mcp.json              ← apunta a http://localhost:7432/mcp
    │   ├── .hive-agent-id         ← ID del agente (orchestrator-1)
    │   └── .claude/
    │       ├── settings.json      ← hook PostToolUse configurado
    │       └── hooks/
    │           └── post-write-heartbeat.js
    ├── coder-backend/
    │   └── ... (misma estructura)
    └── ...

# Si el proyecto es un git repo, hive scaffold también crea:
git branch hive/orchestrator
git branch hive/coder-backend
git branch hive/coder-frontend
... etc.

Cuántos agentes usar

Por encima de 4-5 agentes simultáneos activos, el overhead de coordinación empieza a superar el beneficio del paralelismo.

Publicar en npm

npm login                  # autenticarse con npmjs.org (una sola vez)
npm run release            # build + publish hiveclaude

Desarrollo

npm install                # instalar dependencias de todos los packages
npm run build              # compilar broker + cli
npm test                   # correr todos los tests
npm run dev:broker         # modo watch del broker

Licencia

MIT