hermes-hive-v4 4.1.1

HIVE — Multi-Agent Orchestration for Hermes Agent

HIVE v4.1

Multi-Agent Build Orchestrator

One sentence → automated build → iterable artifact.

---

✦ 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

1. Install Hermes Agent

Choose your platform:

Platform	Command
🐧 Linux / macOS / WSL2	curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
🪟 Windows (PowerShell)	iex (irm https://hermes-agent.nousresearch.com/install.ps1)
📦 pip (any OS)	pip install hermes-agent

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

2. Install & Start HIVE

pip install -e ".[dev]"
python start.py
# → Dashboard:  http://127.0.0.1:8421/dashboard
# → MCP:        http://127.0.0.1:8421/mcp

💡 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}

_{↑ Full install guide}

---

✦ 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": [...], ...}

What you can change	How
LLM provider	Swap Hermes for OpenAI, Anthropic, Ollama, or your own endpoint — just implement the MCP bridge interface
Agent roles	Override any role class; change prompts, validation, or output schema
State machine	Add or remove states and transitions in machine.py — the transitions library makes it declarative
Tech stacks	Add new entries in toolman.py under DELIVERY_TEMPLATES
MCP tools	Register new @mcp.tool() decorators in mcp_server.py
Dashboard	Replace dashboard.html or add custom WebSocket event handlers
Persistence	Swap SQLite for Postgres by re-implementing session_manager.py
CI/CD	All MCP tools speak JSON-RPC over HTTP — integrate with any pipeline

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

---

✦ Features

	Feature
🛠️	15 MCP Tools — Build, iterate, diff, rollback, status, file ops, SDK install, memory, and more	hive_build · hive_iterate · hive_rollback
🌐	Cross-platform — Windows · macOS · Linux	Same codebase, zero platform hacks
🌍	i18n — English + Chinese UI & LLM prompts	?lang=zh or LANG=zh_CN to switch
📊	Dashboard — Real-time WebSocket console with file browser, artifact viewer, live logs	Built with FastAPI + uvicorn
📦	Auto SDK Install — hive_install_sdk("flutter") downloads missing toolchains on demand	Supports Python, Flutter, Rust, Go, Node
🔖	Versioning — Snapshot-based with diff & rollback	hive_diff(sid, v1, v2)
💰	Cost Tracking — Per-build and daily budget limits with warning thresholds	Configurable via hive.json
🛡️	Sandbox — Isolated execution with timeout and cross-platform process tree kill	start_new_session + killpg fallback
🧠	Cross-project Memory — Learns preferences and extracts skills across builds	hive_memory(action="stats")
📎	File Upload — .txt / .md / .json / .yaml / .py as build requirements	Drag-and-drop on Dashboard

Supported Tech Stacks

Stack	Test Runner	Build	Artifact
Python + tkinter	pytest	PyInstaller	.exe
Python + FastAPI	pytest	Docker	.tar
Flutter / Dart	flutter test	flutter build apk	.apk
Rust	cargo test	cargo build --release	binary
Go	go test	go build	binary
Node.js / React	vitest	vite build	static

---

✦ MCP Tools

Tool	Purpose
hive_build(description)	Start a new build
hive_iterate(session_id, request)	Iterate on existing project
hive_rollback(session_id, version)	Rollback to a previous version
hive_versions(session_id)	List all versions
hive_diff(session_id, v1, v2)	Diff two versions
hive_status(session_id)	Query build status (state, progress, ETA)
hive_cancel(session_id)	Cancel a running build
hive_ls(path)	Browse workspace files
hive_read(path)	Read file content
hive_artifact(session_id)	List build artifacts
hive_list_projects()	List all projects
hive_delete_project(name)	Delete a project
hive_dashboard_url()	Get the dashboard URL
hive_memory(action)	Cross-project memory (stats / preferences)
hive_install_sdk(tech_stack)	Download a missing SDK

---

✦ 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/ — 6 roles · 7 infrastructure modules · dashboard · versioning

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

Test suite	Count	Depends on Hermes
tests/test_unit.py	21	❌
tests/test_edge.py	18	❌
tests/test_mock.py	77	❌
tests/test_phase1_acceptance.py	36	⚠️ partial
tests/test_phase2_acceptance.py	—	⚠️ partial
tests/test_phase3_acceptance.py	—	⚠️ partial

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.