Beadhive

Beadhive（bh）

bh は、多数のリポジトリにまたがる beads イシュートラッキングを管理するための単一の CLI です。各リポジトリはそれぞれ独自の beads データベース（hive）で、短く安定したプレフィックスを持ちます。bh はそれらをオンボーディングし、ラベルを一貫した状態に保ち、1 つまたはすべてのリポジトリに対して bd/git を実行し、すべての hive を 1 つのクロスリポジトリビューに集約します — コードがチェックアウトされていない hive であっても同様です。

これは bd、git、git-workspace、dolt、docker の上に載る薄いオーケストレーターです。bh が規約、レジストリ、検証、ルーティングをエンコードします。設定と実行時状態は ~/.beadhive/ 配下に置かれますが、そこにイシューデータは存在しません — 各 hive のイシューは、そのリポジトリ自身の git リモート上の refs/dolt/data 配下にある独自の Dolt DB に存在します。

bh は Beadhive の CLI です。Beadhive は beads を使うソフトウェアファクトリーである bead-machine です。これが駆動するプロセスは docs/AGF.md に文書化されています。

このリポジトリは CLI のソースです（PyPI 上の Python パッケージ beadhive、コマンド bh）。Beadhive が概念的には何であるか、どのように駆動するかではなく、については beadhive.ai を参照してください。

インストール

エージェント向け: エージェントを INSTALL.md に向けてください — これが推奨のインストール経路です。構造化された install: frontmatter ブロック（エージェントがこれを読み、計画を開示し、各コマンドの前に確認する）と、あらゆるエージェントや人間が従える散文のフォールバックを備えています。

手動で行いますか？ この順序で 2 つの経路があります。

マネージド経路（推奨）

bh は単独では動作しません — bd、dolt、gh、git-workspace を駆動します。これがそれらすべてを 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 とその 3 行目はどちらも重要であり、飾りではありません。force を付けない場合、uv tool install はすでに bh があるマシンでは何も行わず、それでも終了コード 0 で終了します。macOS で 0.7.1 がインストールされた状態で計測したところ、「Installed 2 executables: bh, bh-mcp」と報告し、bh --version は依然として 0.7.1 を表示しました。このステップは、インストールが終了コード 0 で終わったときではなく、バージョンが正しいときに完了です。

latest はリリースチャネルのブランチであり、バージョンではありません。CI は各リリースが公開されるとそれをそのリリースのコミットへ移動させるため、この行はバージョンを一切含まず、リリース日の編集も一切不要です。これを github:beadhive/beadhive#default に短縮しないでください — それはデフォルトブランチを解決するものであり、最新リリースではありません。

唯一の前提条件は nix で、これは root を必要とします — システムデーモン、および macOS では APFS ボリュームです。INSTALL.md には、一度きりのインストーラー、約 130 秒 / 2～3 GB のコールドコスト、プラットフォームの制限（macOS: Apple Silicon のみ）、および nix profile add が必要とする nix ≥ 2.30 が記載されています。

PyPI 経路（フォールバック、推奨されません）

nix をインストールできない、またはインストールしないマシン向けです。動作しますし、本当に 1 コマンドです — しかし bh のみをインストールし、他の 4 つのツールはそのマシンがたまたま持っているものに委ねられます。その結果、bd を手動で HEAD からインストールすることにもなります。

uv tool install --force 'beadhive[otel]'   # or: pipx install --force 'beadhive[otel]'
brew install beadhive/tap/beadhive         # Homebrew — slower, builds native deps from source
bh --version                               # same check, and for the same reason
bh setup check                             # reports which of the four tools you're missing

手動で一致させ続ける必要があるもの、および Docker 経路については INSTALL.md を参照してください。

初回実行 — ラング 1

ノート PC 1 台、ローカルのみ。まっさらなインストールから、すぐ使える一覧まで:

bh config init                              # scaffold ~/.beadhive
bh mcp install                              # Claude Code: claude mcp add bh --scope user
bh hq init                                  # local-only HQ; no remote wired, deliberately
bh hive onboard <provider>/<org>/<repo>     # zero-footprint by default
bh work ready

bh setup guide を実行してセットアップを完了します — まっさらなインストールから設定済みのワークスペースまでを、ガイド付きでまず調査しながら進む道のりです。上記の手順に加えて、1 つのコマンドでは済まない部分（orgs、providers、git-workspace）もカバーし、各ステップの状態を確認してから実行するため、すでに半分設定済みのマシンでも安全です。brew、pip、またはコピー＆ペーストしたコマンドでインストールし、INSTALL.md を見なかった場合は、これを頼ってください。

そのコスト: HQ はローカルです — バックアップもなく、まだ 2 台目のマシンもありません。これは省略ではなく方針です。リモートの接続はラング 2 です。4 つのラング、それぞれが何をもたらすか、そしてこのラングにとどまるコストについては docs/ADOPTION.md を参照してください。

エージェントハーネス

bh は Claude Code（--claude）と OpenCode（--opencode）の席を用意します — どちらかを bh hive onboard <provider>/<org>/<repo> に渡してください。docs/AGF.md にはハーネスごとのサポートマトリクスがあり、codex に適用されるものとされないものを含みます。Claude Code では、bh claude-plugin が席のエージェント定義とロールスキルを提供します:

claude plugin marketplace add beadhive/claude-plugin
claude plugin install bh@beadhive

さらに進む

それぞれ 1 行で、誰向けかを示します:

• docs/MCP-PUBLISHING.md — MCP レジストリとディレクトリの維持。

• Context7 — エージェント向けのライブラリドキュメント。

• docs/ADOPTION.md — 動いた。次のラングは? 4 つのラング、それぞれが何をもたらすか、そして今のラングにとどまるコスト。

• INSTALL.md — ルートの選択。 マネージドな経路、PyPI と Docker、そしてそれらの間のトレードオフ。

• docs/ONBOARDING.md — 新しいマシンで、ステップバイステップ。 ゼロから、ハイブを登録済みの設定された AGF ワークスペースまで。

• docs/UPGRADING.md — バージョン間、またはルート間の移行。

• docs/HQ.md — Factory HQ。 それが何であり、何を保存するか。

• docs/OPERATOR-UI.md — 最初のローカルオペレーター UI。 ループバック専用で認証なし、読み取り専用のプロファイルを起動し、トラブルシューティングします。

• docs/COMPLEXITY-ROUTING.md — ケイパビリティ優先のディスパッチ。 複雑さのラベル、遅延バインディングのモデル選択、可用性、移行のリカバリ。

• docs/HIVES.md とマルチホスト ADR — 複数のホスト。 ハイブの種類、リース、ホストの役割。

• beadhive.ai — Beadhive とは概念的に何か、コマンドの前に全体像を知りたい場合に。

• docs/OVERVIEW.md — その他すべて。 設計と考え方、設定、コマンドサーフェス全体、コンポーネントごとに。

質問 / フィードバック

一般的な質問、フィードバック、バグ報告は GitHub Issues にお寄せください。セキュリティ脆弱性については、公開 Issue を立てる代わりに SECURITY.md を参照してください。

開発

# 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     # build + install this checkout → ~/.local/bin/bh
just lint        # ruff check
just fmt         # ruff format
just test        # pytest
just build       # wheel + sdist into dist/  (stamped local)