Learn

# How Hive works

Hive is an open source AI agent orchestration system. A fleet of specialized agents autonomously maintains software repositories — open source or private — triaging issues, writing fixes, opening PRs, and merging on green CI. A governor dynamically adjusts agent pace based on issue queue depth, and a deterministic pipeline gates every change.

Request a Hive Read the ACMM paper

Autonomy framework

## The ACMM ladder

The AI-native Capability Maturity Model (ACMM) defines six levels of AI agent autonomy, from advisory-only to fully autonomous. Each level controls which agents are active and what actions they can take. Start conservative, climb when you’re ready — raising the level is always a human decision.

L1 — Inception (Assisted)

### Inception & advisory

An interactive brainstorm agent turns ideas into project scaffolding; a guide agent audits docs. Every action needs human approval. No feedback loops.

L2 — Advisory (Instructed)

### Observe & report

Agents produce advisory findings on the dashboard and a tracking issue. No GitHub issues or PRs. They observe and report; humans decide what to act on.

L3 — Quality-Gated (Measured)

### Quality & test coverage

The quality agent opens issues and hold-gated PRs about testing gaps, coverage, and CI health. Every PR keeps a `hold` label — no agent merges. This measurement foundation is what earns automation in the levels above.

L4 — Security-Aware (Adaptive)

### Closed-loop, issues

All agents now file issues — bugs, doc gaps, workflow failures, vulnerabilities. Security agent joins. Still no PRs; the loop is closing.

L5 — Semi-Autonomous (Semi-Automated)

### Hold-gated PRs

All agents open PRs, each auto-labeled `hold` for human batch-review. Architect (RFCs) and strategist join. The system proposes; it does not merge on its own.

L6 — Fully Autonomous

### Merge on green CI

Agents open PRs and auto-merge on green CI — no `hold` label. Outreach agent handles community engagement. Highest trust; governor at fastest cadence.

The governor

## Pace that follows your backlog

The governor senses queue depth and switches between four modes — `idle`, `quiet`, `busy`, and `surge` — each with its own per-agent cadences. A quiet repo costs almost nothing; a flooded queue gets the full fleet. Every change still passes the same deterministic gates.

idle

### Watchful

Empty queue. Agents sleep; sensing continues.

quiet

### Steady

A few open issues. Slow, deliberate cadences.

busy

### Working

Queue is filling. Agents tighten their loops.

surge

### All hands

Critical backlog. Maximum cadence until drained.

Reference architecture

## How the pieces fit

Hive ships as a single container: a Go binary is the brain, a Node proxy is the public front door, and `ttyd` exposes the agents’ terminals. Deterministic work (filtering, classification, merge-gating, permission enforcement) runs before any model sees a task — agents only make the judgment calls.

System context

    flowchart LR
        maintainer["Maintainer"] -->|dashboard| hive
        contributor["Contributor"] -->|donates compute| hive
        subgraph hive["Hive (one container)"]
          core["Orchestrator + agents"]
        end
        hive <-->|"REST / git via MITM proxy"| github["GitHub"]
        hive <-->|inference| models["Model backends"]
        hive -->|"heartbeat / 2 min"| hub["Hive Hub"]
        hive -->|alerts| notify["ntfy / Slack / Discord"]

The governor loop — queue depth to a kick

    flowchart TB
        enum["Enumerate actionable
    issues / PRs"] --> pipe["Deterministic pipeline
    classify · merge-gate · enforce"]
        pipe --> mode{"Mode by issue count"}
        mode -->|"> surge"| SURGE
        mode -->|"> busy"| BUSY
        mode -->|"> quiet"| QUIET
        mode -->|else| IDLE
        SURGE & BUSY & QUIET & IDLE --> cad["Per-agent cadence"]
        cad --> due["Agents due for a kick"]
        due --> kick["Type work order into tmux"]

Layered guardrails — defense in depth

    flowchart LR
        agent["AI agent"] --> l1["1 · CLI tool deny
    (gated by mode)"]
        l1 --> l2["2 · Scoped token
    (least privilege)"]
        l2 --> l3["3 · MITM proxy
    (method,path) → min mode
    + repo allowlist"]
        l3 --> gh["api.github.com"]
        traj["Trajectory review"] -.->|"drift → pause"| agent

3001

Dashboard (public front door)

3002

Internal Go API

7681

ttyd web terminal

18443

MITM GitHub proxy (loopback)

Read the full reference architecture →

The fleet

## Specialized agents, one mission

Each agent owns a lane. Together they cover the maintenance lifecycle end to end — without stepping on each other’s work.

Supervisor

Agent health monitoring, sweep analysis, stall detection.

Scanner

Triages issues, dispatches fixes, opens and merges PRs.

Guide

Documentation gaps, onboarding analysis, advisory reviews.

CI-Maintainer

CI/CD health, workflow fixes, build monitoring.

Quality

Test coverage, integration tests, quality gates.

Sec-Check

Security scanning, PR security gate.

Architect

Cross-cutting RFCs, refactors, new features.

Strategist

Experiment design, A/B testing, strategy lab.

Outreach

ADOPTERS outreach, community engagement.

Brainstorm

On-demand ideation via Inception.

Under the hood

## Built for trust

- GovernorDynamic mode switching (idle / quiet / busy / surge) with per-agent cadences.
- InceptionInteractive project scaffolding with llm-wiki and spec-kit.
- Knowledge BaseShared facts, wiki vaults, cross-agent priming.
- Audit LoggingAll state changes logged with who, when, and why.
- ACMM ProxyPer-agent HTTP proxy enforcing mode restrictions.
- ContributingCommunity agent contribution system with trust tiers.

Resources

## Go deeper

ACMM Paper

The autonomy framework on arXiv

Source code

Hive on GitHub

ACMM Leaderboard

How projects rank on AI-readiness

API Docs

Hub REST API reference

Get started

Request a hive in minutes

## Reading List

From the KubeStellar Medium — April 2026 onward.

View full list on Medium →