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
# On a NEW machine you do not have `just` yet — it is pinned in .mise.toml, not the Brewfile:
brew bundle --file=Brewfile # provides mise
mise exec -- just bootstrap # mise installs the pinned just, then runs bootstrap
just bootstrap # brew bundle + mise install + uv sync (once per machine; needs just)
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.8.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.8.1.tar.gz | 2.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| beadhive-0.8.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.8 MB
Release files / beadhive-0.8.1.tar.gz
| Download URL | beadhive-0.8.1.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3590ac95680f443953801a1db73bbf1e0550cca724c12c945a288c9ae416948
|
|
BLAKE2b-256 checksum How to use checksums |
3178a60fe8ae03daed7d3122f08de80a288e88c49359def9f4e487f1da017a08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.2 {"installer":{"name":"uv","version":"0.12.2","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.8.1-py3-none-any.whl
| Download URL | beadhive-0.8.1-py3-none-any.whl |
|---|---|
| Size | 739.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6cf7da3e2d36e327d03417c963461f040fcfb086716c20c87adad66260e4a0d3
|
|
BLAKE2b-256 checksum How to use checksums |
7ba977bc9b09cbe66ae83161fc82d15e0c2dea9a64085754163accb131c879b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.2 {"installer":{"name":"uv","version":"0.12.2","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}
|
