Beadhive MCP server

Beadhive (bh)

<!-- mcp-name: io.github.beadhive/beadhive -->

<!-- markdownlint-disable-next-line MD013 -->

bh is a single CLI for managing beads issue tracking across many repositories. Each repo is its own beads database (a hive) with a short, stable prefix; bh onboards them, keeps their labels consistent, runs bd/git across one or all of them, and aggregates every hive into one cross-repo view — even hives whose code isn't checked out.

It's a thin orchestrator over bd, git, git-workspace, dolt, and docker: bh encodes the conventions, the registry, validation, and routing. Config and runtime state live under ~/.beadhive/; no issue data lives there — each hive's issues live in its own Dolt DB under refs/dolt/data on that repo's own git remote.

bh is the CLI of Beadhive, a bead-machine — a software factory that uses beads. The process it drives is documented in docs/AGF.md.

This repo is the CLI's source (Python package beadhive on PyPI, command bh). For what Beadhive is conceptually, rather than how to drive it, see beadhive.ai.

Install

Agents: point your agent at INSTALL.md — the preferred install path. It carries a structured install: frontmatter block (the agent reads it, discloses the plan, and asks before each command) plus a prose fallback any agent or human can follow.

Doing it by hand? There are two routes, in this order.

Managed path (recommended)

bh doesn't work alone — it drives bd, dolt, gh and git-workspace. This is the only route that installs and version-pins all of them with it, from flake.lock:

nix profile add github:beadhive/beadhive/latest#default       # bd, dolt, gh, git-workspace, git, uv, just
uv tool install --force 'beadhive[otel]'                      # bh itself (uv came from the line above)
bh --version                                                  # must print the released version

--force and that third line are both load-bearing, not decoration: unforced, uv tool install no-ops on a machine that already has bh and still exits 0. Measured on macOS with 0.7.1 installed, it reported "Installed 2 executables: bh, bh-mcp" and bh --version still said 0.7.1. This step is done when the version is right, not when the install exits 0.

latest is a release channel branch, not a version: CI moves it onto each release's commit once that release publishes, so this line never carries a version and never needs a release-day edit. Don't shorten it to github:beadhive/beadhive#default — that resolves the default branch, which is not the latest release.

The one precondition is nix, which needs root — a system daemon, and an APFS volume on macOS. INSTALL.md carries the one-time installer, the ~130s / 2–3 GB cold cost, the platform limits (macOS: Apple Silicon only) and the nix ≥ 2.30 that nix profile add needs.

PyPI route (fallback, not recommended)

Shortened. The full README is on GitHub.