hive

AI agent orchestration for open source projects. container runs a team of AI agents that triage issues, write fixes, review PRs, and keep CI green — governed by queue depth and gated by maturity levels.

Hive is a single Go binary that enumerates GitHub issues and PRs, classifies them by complexity, and dispatches work to AI agents (Claude, Copilot, Gemini, Goose, or self-hosted inference backends) on adaptive cadences.

Hive separates decisions into two layers: a deterministic pipeline of shell scripts handles filtering, classification, merge-gating, and enforcement before any LLM sees the work. Agents handle judgment calls — reading code, reasoning about fixes, writing PRs.

Evaluating whether hive is safe to run against your repos and API keys? See the Security Model.

Quick Start (Docker Compose)

git clone -b v4 https://github.com/hivecommons/hive.git
cd hive/v2
 
cp hive.yaml.example hive.yaml
export HIVE_GITHUB_TOKEN=ghp_...
docker compose up -d

Dashboard at http://localhost:3001. The default docker-compose.yaml uses a pre-built image; run docker compose build first to build from source instead, or point it at the stable release channel image ghcr.io/hivecommons/hive:stable (see Release Channels).

Deployment options

Ports

Volumes

Web Dashboard

The embedded dashboard (port 3001) is the primary control surface:

• Live updates via SSE — agent states, governor mode, repo counts, and beads refresh continuously
• Getting Started dialog — a welcome checklist that auto-checks steps as setup completes and deep-links into the relevant configuration; minimizes into the ? button when dismissed
• Per-agent method + model dropdowns — each agent card shows its current backend and model as the button label; models are live-discovered per backend (see below)
• Model pinning — pin an agent’s model so automatic reconciliation never changes it out from under you; an explicit switch on a pinned agent retargets the pin instead of failing
• Test Connection — live probe of inference gateways that reports the gateway’s actual response (including auth errors) instead of masking failures behind fallback aliases
• Real token tracking — inference usage is captured from actual API responses per agent; totals surface on the dashboard and, for hub-registered hives, on the hub’s My Hives page
• Kick buttons —-click kick for any agent
• ACMM level control — apply a maturity level and the full agent roster that level defines is reconciled automatically
• Web terminal — ttyd access to agent tmux sessions

Model discovery

Model lists are discovered live per backend rather than hardcoded:

Discovery is best-effort with caching and fallbacks, so dropdowns never come up empty. An agent’s model is switched automatically in exactly case: live discovery shows the currently selected model is no longer available (and the model is not pinned) — the agent moves to an available model and the dashboard shows a notice.

How it works

The governor evaluates issue/PR queue depth across your repos on a configurable interval (default 300s) and switches between four modes — SURGE, BUSY, QUIET, IDLE — each with per-agent cadences (or pause). Thresholds and cadences are all set in hive.yaml:

governor:
  eval_interval_s: 300
  modes:
    surge:
      threshold: 20
      scanner: 15m
      reviewer: pause
    busy:
      threshold: 10
      scanner: 15m
      reviewer: 1h
    quiet:
      threshold: 2
      scanner: 15m
      reviewer: 45m
    idle:
      threshold: 0
      scanner: 15m
      reviewer: 15m

Agents run inside tmux sessions managed by the Go binary. The container runs three processes: the hive binary (agent orchestration, governor loop, dashboard API, health and token tracking), a Node.js proxy (dashboard frontend with SSE), and ttyd (web terminal).

ACMM levels

Hive uses an AI-native Capability Maturity Model (ACMM) with six levels that control what agents are allowed to do:

Each level defines per-agent policy modes: advisory (observe), measured (file issues), holdgated (PRs with hold label), or full (auto-merge). Applying a level reconciles the entire agent roster that level defines — at L5 that is 9 agents, including architect and strategist.

Deterministic pipeline

Hive separates work into two layers:

• Deterministic layer (shell scripts + JSON + config) — handles every decision where a human would give the same answer every time. Runs before agents wake up.
• Non-deterministic layer (LLM agents) — receives pre-computed data and focuses on judgment calls: reading code, reasoning about fixes, writing PRs.

The rule: if a human would give the same answer every time, it belongs in infrastructure, not in a prompt.

LLMs treat “NEVER” rules as suggestions. No amount of prompt engineering reliably prevents an agent from closing a hold-labeled issue or merging an untested PR. The deterministic pipeline removes those decisions from the agent entirely — enumerators fetch and filter the canonical work list, classifiers enrich items with metadata, gates pre-check eligibility, and enforcers block forbidden operations before any agent acts.

Backends

Each agent picks its backend in hive.yaml (agents.<name>.backend):

For inference backends, the gateway API key is entered in the dashboard (obfuscated after entry) and stored to a Kubernetes Secret and an owner-only file on the PVC — never written into hive.yaml. See the Security Model for how agents are kept away from real keys.

Configuration

All config lives in a single hive.yaml with ${ENV_VAR} interpolation for secrets. See v2/hive.yaml.example for the full reference.

project:
  org: your-org
  repos:
    - repo-one
    - repo-two
  primary_repo: repo-one
  ai_author: your-bot-user
 
agents:
  scanner:
    enabled: true
    backend: claude
    model: claude-sonnet-4-6
    beads_dir: /data/beads/scanner
    clear_on_kick: true
 
github:
  token: ${HIVE_GITHUB_TOKEN}
 
hub:
  enabled: true
  url: https://hive.hivecommons.dev

On Kubernetes the file is mounted read-only from a ConfigMap; changes made in the dashboard are persisted as an overlay on the /data PVC so they survive pod restarts.

GitHub auth

Use a personal access token, or a GitHub App (recommended for production — permissions are scoped to the repos you install it on):

github:
  app_id: 12345
  installation_id: 67890
  key_file: /secrets/gh-app-key.pem

Notifications

Configure any combination of channels in hive.yaml:

notifications:
  ntfy:
    server: https://ntfy.sh
    topic: my-hive-alerts
  # slack:
  #   webhook: ${SLACK_WEBHOOK_URL}
  # discord:
  #   webhook: ${DISCORD_WEBHOOK_URL}

An optional Discord bot (discord.bot_token) responds to !hive commands.

Contribute to a Hive

Community members can contribute compute to any registered hive:

brew install just gh
git clone -b v4 https://github.com/hivecommons/hive && cd hive
just contribute-setup claude
just contribute-hive

Supported CLIs: Claude Code, GitHub Copilot, Pi, Goose, Bob. Contributors start as newcomer (rate-limited) and auto-promote based on completed tasks. Your credentials never leave your machine. relay session can also subscribe to multiple hives (added by @hanthor in hivecommons/hive#2846): register with each hive, then use comma-separated HIVE_HUB URLs and matching comma-separated HIVE_REGISTRATION_TOKEN values in the same order. The relay shares CLI/tmux session, works on task at a time, keeps each hub connected, and rotates when the active hub reports no task is available.

See the Hive Hub to browse registered hives, view leaderboards, and find hives accepting contributions.

Apache 2.0 · Architecture · Security Model