Beadhive (bh)
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 Beadhive umbrella's workspace CLI — the integration-plane driver for AGF
(Agentic Git Flow), the abstract, tracker-independent process. Beadflow is that process
implemented on beads: this repo's concrete implementation, unchanged behavior under a naming
layer. See docs/AGF.md for the process and
docs/design/limn-naming-strategy-adr.md for the
naming decision record.
This repo is the CLI's source (Python package beadhive on PyPI, command bh).
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.
Manual (pick one):
uv tool install 'beadhive[otel]' # PyPI (recommended — prebuilt wheels, seconds)
pipx install 'beadhive[otel]' # PyPI alternative
brew install beadhive/tap/beadhive # Homebrew (slower — builds native deps from source)
Then scaffold the config home:
bh config init # writes config.yaml + templates into ~/.beadhive/
Optional (Claude Code): the bh claude-plugin vends the AGF seat agent defs and role
skills; bh mcp install wires the MCP server at user scope:
claude plugin marketplace add beadhive/claude-plugin
claude plugin install bh@beadhive
bh mcp install
Docs
New to bh? Start at **docs/ONBOARDING.md** — the end-to-end guide
from fresh Mac to a configured AGF workspace with registered hives.
Everything else — the design and reasoning, configuration, the full command surface, and each
component — starts at **docs/OVERVIEW.md**.
Questions / feedback
General questions, feedback, and bug reports go through
GitHub Issues. For security vulnerabilities,
see SECURITY.md instead of filing a public issue.
Develop
just bootstrap # brew bundle + mise install + uv sync (once per machine)
just install # uv tool install --force '.[otel]' → ~/.local/bin/bh
just lint # ruff check
just fmt # ruff format
just test # pytest
just build # uv build
See CONTRIBUTING.md for the plain-git contributor path — setup, tests,
and how to submit a change.
1 maintainer
Release files for beadhive 0.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| beadhive-0.7.1.tar.gz | 1.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| beadhive-0.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.2 MB
Release files / beadhive-0.7.1.tar.gz
| Download URL | beadhive-0.7.1.tar.gz |
|---|---|
| Size | 1.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b8fd7d6d8c21e0821af4b37a4c99f0a8cb298c338a437fe67fb7be61fd5fd3bc
|
|
BLAKE2b-256 checksum How to use checksums |
ae9b12a1b660984f9faf079df4a82d63cb8e356fdaad5812356704a85a51a05c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / beadhive-0.7.1-py3-none-any.whl
| Download URL | beadhive-0.7.1-py3-none-any.whl |
|---|---|
| Size | 612.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2139672b1e9a479b31f4fe1af51deb2a8863f621e0d0e71672aee152650aed0b
|
|
BLAKE2b-256 checksum How to use checksums |
7f73234f65b1ff0cbdd9d82d00077c562d663ee948fd628b576a6d559e73f262
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
