✦ Overview

HIVE is an AI-native build orchestration engine. Feed it a sentence — "make a calculator with Python tkinter" — and six specialized agent roles (ARC, PLANNER, CODER, TESTER, REVIEWER, TOOLMAN) translate, decompose, generate, test, review, and package your project into a shippable artifact. With iteration loops, rollback, and cross-project memory.

Built on Hermes Agent by Nous Research — HIVE consumes Hermes via MCP tools (hermes_bridge.py), making every agent call a lightweight JSON-RPC exchange. The framework is fully open source (MIT): swap in any LLM backend, rewrite any role, wire it into your own CI/CD pipeline. The 6-agent pipeline is a reference architecture — not a cage.

🧩 HIVE is your starter kit for AI-driven builds. Fork it, gut the roles, plug in your own agents, point it at your stack. The MCP protocol keeps everything decoupled.

✦ Quick Start

Choose your platform:

hermes setup   # configure your LLM provider
hermes --version
# → Hermes Agent v0.16.0

2. Install HIVE

Choose the install method that fits your use case:

# After install — start the daemon (either method works):
python start.py
# → HIVE daemon started (PID 12345)
# → Dashboard:  http://127.0.0.1:8421/dashboard
# → MCP:        http://127.0.0.1:8421/mcp

# Check status
python start.py status
# → HIVE daemon: OK running (PID 12345)

# Stop daemon
python start.py stop

💡 Hermes stores its config at ~/.hermes/. HIVE stores sessions at ~/.hermes/hive-v4/.

_{HIVE Dashboard — real-time WebSocket console with file browser, artifact viewer, and live build log}

✦ Architecture

Six agents collaborate through a 7-state pipeline, coordinated by a central orchestrator.

                    ┌──────────────────────────────────────────────┐
                    │           H I V E   O r c h e s t r a t o r  │
                    └──────────┬───────────────────────┬───────────┘
                               │                       │
    ┌──────────┐    ┌──────────▼────────┐    ┌─────────▼──────────┐
    │  INPUT   │    │      ARC          │    │     PLANNER        │
    │  "Build  │───▶│  (Architect)      │───▶│  (Decomposition)   │
    │   calc"  │    │  → brief.json     │    │  → dag.json        │
    └──────────┘    └───────────────────┘    └─────────┬──────────┘
                                                        │
                    ┌───────────────────────────────────▼────────────┐
                    │     CODER POOL (×3 parallel)    +   TESTER    │
                    │     ┌──────────┐ ┌──────────┐ ┌──────────┐    │
                    │     │  coder 1 │ │  coder 2 │ │  coder 3 │    │
                    │     └──────────┘ └──────────┘ └──────────┘    │
                    └───────────────────────┬───────────────────────┘
                                            │
                    ┌───────────────────────▼───────────────────────┐
                    │            REVIEWER (4-layer)                │
                    │  L1 syntax  ·  L2 alignment  ·  L3 security  │
                    │  ·  L4 consistency                           │
                    └───────────────────────┬───────────────────────┘
                                            │
                    ┌───────────────────────▼───────────────────────┐
                    │  TOOLMAN  →  install deps  →  run tests      │
                    │           →  package artifact                │
                    └───────────────────────────────────────────────┘

States: idle → translating → planning → executing → testing → done
Loop: ↻ done → idle — iterate until satisfied.

✦ Customize & Extend

HIVE is designed to be forked, gutted, and rewired. The 6-agent pipeline is a reference architecture — not a cage.

# Example: swap in your own agent
from orchestrator.roles.arc import Architect

class MyCustomArchitect(Architect):
    """Your LLM, your prompt, your brief schema."""
    async def translate(self, description: str, lang: str = "en") -> dict:
        # Call your own API, a local model, or a different Hermes profile
        return {"project_name": "...", "features": [...], ...}

See CONTRIBUTING.md for development setup and the role contract interface.

✦ Features

Supported Tech Stacks

✦ MCP Tools

✦ Python SDK

from hive_client import HiveClient

client = HiveClient(url="http://127.0.0.1:8421")

# One-shot build
build = client.build("Make a calculator with Python tkinter")
result = build.wait()
print(result.artifacts)

# Iterate
v2 = build.iterate("Make the buttons bigger")
v2.wait()
print(v2.diff)

✦ Project Structure

orchestrator/
├── mcp_server.py          # HTTP server + 15 MCP tools + dashboard routes
├── orchestrator.py        # Build orchestration loop
├── machine.py             # 7-state state machine
├── daemon.py              # Daemon CLI (start / stop / status)
├── i18n.py                # Internationalization (zh / en)
├── roles/
│   ├── arc.py             # Architect (requirements → brief.json)
│   ├── planner.py         # Planner (brief → DAG)
│   ├── coder.py           # Coder pool (3 parallel workers)
│   ├── tester.py          # Independent test writer
│   ├── reviewer.py        # 4-layer review
│   └── toolman.py         # Delivery (install / test / package)
├── infrastructure/
│   ├── session_manager.py # SQLite persistence
│   ├── sandbox.py         # Isolated execution
│   ├── cost_tracker.py    # Budget management
│   ├── validator.py       # Schema validation
│   ├── dependency_manager.py # venv management
│   ├── errors.py          # Unified error codes
│   └── memory_store.py    # Cross-project memory
├── dashboard/
│   └── templates/dashboard.html  # Web console
├── versioning/
│   └── version_manager.py # Snapshot versioning
├── hermes_bridge.py       # Hermes CLI bridge
├── hermes_runner.py       # Isolated subprocess runner
├── hive_client.py         # Python SDK
└── hermes_wrapper.py      # (deprecated)

✦ Install Hermes Agent

Hermes Agent (by Nous Research) powers all LLM calls through MCP — HIVE speaks to it via JSON-RPC over the Hermes CLI bridge — ARC, PLANNER, CODER, TESTER, REVIEWER. HIVE invokes it through hermes_bridge.py.

Linux / macOS / WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes setup

Windows (native PowerShell)

iex (irm https://hermes-agent.nousresearch.com/install.ps1)
# Then restart terminal:
hermes setup

Via pip (any platform)

pip install hermes-agent
hermes setup

Verify: hermes --version → Hermes Agent v0.16.0

✦ Configuration

Adjust runtime behavior via hive.json in the project root:

{
  "version": "4.1.0",
  "mcp_port": 8421,
  "dashboard": true,
  "max_workers": 3,
  "cost": {
    "max_per_build_usd": 5.0,
    "max_daily_usd": 20.0,
    "warn_at_usd": 1.0
  }
}

See docs/hive-json.md for all fields and examples.

✦ Language / 语言

English is the default.  Append ?lang=zh to the Dashboard URL
or set LANG=zh_CN in your environment to switch to Chinese.

默认英文。 在 Dashboard URL 后加 ?lang=zh 或在终端设置
LANG=zh_CN 即可切换为中文。

LLM role prompts (ARC, PLANNER, CODER, TESTER) are available in both languages.

✦ Development

pip install -e ".[dev]"
pytest tests/ -v

See CONTRIBUTING.md for guidelines.

✦ Project Status

Beta — v4.1.0. Handles Python projects reliably; Flutter / Rust / Go / Node support requires the corresponding SDK on the host.

MIT — see LICENSE.