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.3
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.3.tar.gz | 2.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| beadhive-0.8.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.8 MB
Release files / beadhive-0.8.3.tar.gz
| Download URL | beadhive-0.8.3.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e5c1fd28cc262685da888101f95589aca8cc3b1c41d8d95b1ccd0d6f876a347b
|
|
BLAKE2b-256 checksum How to use checksums |
86ffbaf8240dbc7bd2feaf8182186029d6a77b66c20b6ac1aa72985d7770070a
|
| 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.3-py3-none-any.whl
| Download URL | beadhive-0.8.3-py3-none-any.whl |
|---|---|
| Size | 742.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ee0ea1d0053c08a0562a62d2b4fe369a044185d2f101d611120187bdb4ecb884
|
|
BLAKE2b-256 checksum How to use checksums |
b54f69b4bb4cf8688f3d4bae277a33eb6113dab86828a62a60b43748ab4e69f6
|
| 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}
|
