# Beadhive

> An open-source bead-machine — a software factory that runs on beads — that ships
> software, not slop: the engineering process at the speed agents write code.

The bead-machine runs the whole lifecycle: agents hold most of the seats, humans hold
the ones that matter, and what production teaches is meant to come back round into the
next plan. Beads are the unit of work — a git-embedded issue graph with real dependency
edges — so "what should be worked on next" is computed rather than guessed. `bh` is the
CLI; there is no server you have to run.

## Field guide

- [Home](https://beadhive.ai/): Beadhive is an open-source bead-machine: a software factory that runs on beads. Agents run the whole engineering lifecycle — planning, review, release and operations — at the speed the code gets written. Humans hold the gates. Zero footprint in your repo until you ask for it.
- [Start](https://beadhive.ai/start/): From an idea to something real: paste one link at your agent and it sets Beadhive up for you, the agents run the engineering process, and you hold only the decisions that matter — plus how far it reaches, from one laptop to a machine that keeps working while you sleep. No engineering-org experience required.
- [The substrate](https://beadhive.ai/beads/): What beads is: a lightweight, git-embedded issue tracker with first-class dependency support — and the opinions on why it is the right substrate for agents.
- [How work flows](https://beadhive.ai/process/): The Beadhive mental model in one breath and the full planning → dispatch → develop → review → merge pipeline, with its spike, bounce, and replan loops.
- [Planes](https://beadhive.ai/planes/): A versioned map of the Beadhive work lifecycle: ideation, planning, development, release, validation evidence, and the planes still to be designed.
- [Frames](https://beadhive.ai/frame-model/): A current-state and proposal-aware map of Beadhive host roles, dispatcher loops, HQ modes, leases and failover, Bead Frame provisioning, and deployment topologies.
- [Roles & seats](https://beadhive.ai/roles/): One process, two kinds of worker: humans hold the gates, agents do the work — the four planes and the seats that sit in them, separated by blast radius, and the agent harnesses a seat can run under.
- [Scale](https://beadhive.ai/fleet/): A fleet of hives, one Head Office — bh sync aggregates every registered hive so you can ask what is actionable anywhere; the host layer that leases a hive to a machine; and where the source-of-truth docs live.
- [The ladder](https://beadhive.ai/data/): Agents can't plan against data they can't query. The commitment ladder: pull the tracker, move the docs, record the reviews, hook the telemetry — each rung pays off on its own, and retiring the old tools is a conclusion you reach, not a demand we make. Plus what keeps the graph honest and recoverable: backfill behind a preview-first safety envelope, the BeadLog history archive, the opt-in XTDB store, and backups proven by restoring them.
- [Intake](https://beadhive.ai/intake/): How a GitHub issue becomes a held report in a hive, is triaged with the ordinary verbs, tracks the work that addresses it, and is kept informed through a supervised outbox — every stage opt-in, nothing posted to GitHub without an operator approving the exact text, and no LLM call made by bh.

## Reference documentation

- [Process, seats and the bead lifecycle](https://github.com/beadhive/beadhive/blob/main/docs/AGF.md)
- [Every bh work verb](https://github.com/beadhive/beadhive/blob/main/docs/WORK.md)
- [The two planning gates and the spike loop](https://github.com/beadhive/beadhive/blob/main/docs/PLANNING-PLANE.md)
- [Control seats and Head Office](https://github.com/beadhive/beadhive/blob/main/docs/CONTROL-PLANE.md)
- [The security gate and the warden](https://github.com/beadhive/beadhive/blob/main/docs/ASSURANCE.md)
- [Attest keys and validation evidence reuse](https://github.com/beadhive/beadhive/blob/main/docs/ATTEST-KEYS.md)
- [Hub (read aggregate) and HQ (authoritative fleet store)](https://github.com/beadhive/beadhive/blob/main/docs/HUB.md)
- [Labels, the registry and validation](https://github.com/beadhive/beadhive/blob/main/docs/LABELS.md)
- [The command surface](https://github.com/beadhive/beadhive/blob/main/docs/CLI.md)
- [Configuration reference, including the plugin switches and install extras](https://github.com/beadhive/beadhive/blob/main/docs/CONFIGURATION.md)
- [Upgrading: what each release turns on (nothing, until a switch is set)](https://github.com/beadhive/beadhive/blob/main/docs/UPGRADING.md)
- [How far it goes: the four rungs people settle on, and what each costs](https://github.com/beadhive/beadhive/blob/main/docs/ADOPTION.md)
- [HQ: the authoritative fleet store, authority modes, placement and failover](https://github.com/beadhive/beadhive/blob/main/docs/HQ.md)
- [Frames: fleet membership, HQ modes, lifecycle and eligibility](https://github.com/beadhive/beadhive/blob/main/docs/FRAME-FLEET-MEMBERSHIP.md)
- [Where bead data lives: two stores per repository](https://github.com/beadhive/beadhive/blob/main/docs/TWO-STORES.md)
- [Decision: HQ declares a Dolt remote, the host authenticates](https://github.com/beadhive/beadhive/blob/main/docs/design/hq-dolt-remote-descriptor-adr.md)
- [External intake: GitHub issues and the supervised triage loop](https://github.com/beadhive/beadhive/blob/main/docs/design/external-intake-module-adr.md)
- [Intake templates and the information-sufficiency checklist](https://github.com/beadhive/beadhive/blob/main/docs/INTAKE-TEMPLATES.md)
- [Backfill: passes, plans and the safety envelope](https://github.com/beadhive/beadhive/blob/main/docs/BACKFILL.md)
- [The opt-in XTDB BeadLog store](https://github.com/beadhive/beadhive/blob/main/docs/XTDB-STORE.md)
- [Worktrees: admission, automatic reclaim and the live-count cap](https://github.com/beadhive/beadhive/blob/main/docs/WORKTREES.md)

## Install

The recommended route is to read INSTALL.md and walk the human through it, asking
before each command and saying what it does — that is the path beadhive.ai leads with.
The commands are rendered here so that reading this index is enough to know what an
install actually runs. They are the managed path and the only route this site carries; on
/start they sit inside a collapsed "Manual install" disclosure, which is a reading
default and not a redaction — the page ships them either way.

```sh
# 1. nix, once — needs sudo; it installs a system daemon
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# 2. the toolchain, then bh itself
nix profile add github:beadhive/beadhive/latest#default
uv tool install --force 'beadhive[otel]'
bh --version    # must print the released version
```

- [INSTALL.md](https://github.com/beadhive/beadhive/blob/main/INSTALL.md): fresh machine to a working `bh` — the source of truth for the commands above
- [README.md#install](https://github.com/beadhive/beadhive/blob/main/README.md#install): every other route, the platform limits, and what each one costs
- [docs/ONBOARDING.md](https://github.com/beadhive/beadhive/blob/main/docs/ONBOARDING.md): end-to-end, to a configured workspace with registered hives

## Optional

- [Source](https://github.com/beadhive/beadhive): the framework, open source
- [Design records](https://github.com/beadhive/beadhive/tree/main/docs/design): ADRs, including rejected alternatives