Beadhive

Beadhive（bh）

bh 是一个 CLI，可用于管理多个仓库中的 beads 问题跟踪。每个仓库都有自己的 beads 数据库（一个 蜂巢），并带有简短、稳定的前缀；bh 会为它们完成接入、 保持标签一致、跨一个或全部仓库运行 bd/git，并将每个蜂巢汇总到一个跨仓库视图中——即使这些蜂巢对应的代码未检出也一样。

它是对 bd、git、git-workspace、dolt 和 docker 的轻量级编排层：bh 编码了约定、注册表、验证和路由。配置和运行时状态存放在 ~/.beadhive/ 下；此处不存放任何问题数据——每个蜂巢的问题都存放在该仓库 自己的 git 远程上的 refs/dolt/data 中的独立 Dolt DB 里。

bh 是 Beadhive 的 CLI。Beadhive 是一台 bead-machine——一个使用 beads 的软件工厂。 它所驱动的流程记录在 docs/AGF.md 中。

此仓库是该 CLI 的源代码（PyPI 上的 Python 包 beadhive，命令 bh）。若想了解 Beadhive 的概念，而非如何操作它，请参阅 beadhive.ai。

安装

Agent： 请让你的 Agent 参照 INSTALL.md——这是首选安装方式。它 包含结构化的 install: frontmatter 块（Agent 会读取它、说明计划，并在执行每条命令前征求同意），以及任何 Agent 或人都能遵循的文字说明。

想手动操作？有两种方式，按以下顺序排列。

托管方式（推荐）

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 和第三行命令都不可或缺，绝非装饰：不加 --force 时，如果机器上已经有 bh，uv tool install 就会跳过操作，但仍以 0 退出。在已安装 0.7.1 的 macOS 上测得，它报告“已安装 2 个可执行文件：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 的机器。它确实可用，而且真的只需一条命令——但它只安装 bh，其余四个工具则取决于机器上碰巧已有的版本，其中也可能包括一个之后还得手动从 HEAD 安装的 bd：

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 阶段

一台笔记本电脑，仅限本地。从全新安装到就绪的列表：

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 完成设置——通过引导式、探测优先的流程，从空白安装逐步配置工作区。它涵盖上述步骤，以及无法用一条命令完成的部分（组织、提供方、git-workspace），并在执行前检查每一步的状态，因此在已经完成一半配置的机器上也能安全使用。如果你通过 brew、pip 或复制粘贴命令安装，却从未看过 INSTALL.md，就可以使用它。

代价： HQ 位于本地——没有备份，也还没有第二台机器。这是当前的部署方式，并非遗漏；接入远程服务是第 2 阶段。请参阅 docs/ADOPTION.md，了解四个阶段、每个阶段能带来的好处，以及停留在当前阶段的代价。

Agent 框架

bh 为 Claude Code（--claude）和 OpenCode（--opencode）提供席位——将其中一个参数传给 bh hive onboard <provider>/<org>/<repo>。docs/AGF.md 包含各框架支持矩阵，包括适用于和不适用于 codex 的内容。在 Claude Code 上，bh claude-plugin 提供席位 Agent 定义和角色技能：

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

深入了解

每项用一句话介绍，并说明适合谁：

• docs/MCP-PUBLISHING.md — 维护 MCP 注册表和目录。

• Context7 — 为 Agent 提供库文档。

• docs/ADOPTION.md — 已经能用了；下一阶段是什么？ 四个阶段、每个阶段能带来的好处，以及停留在当前阶段的代价。

• INSTALL.md — 选择安装方式。 托管方式、PyPI 和 Docker，以及它们之间的权衡。

• docs/ONBOARDING.md — 新机器，逐步配置。 从零开始，构建已配置并注册了各个 Hive 的 AGF 工作区。

• docs/UPGRADING.md — 在不同版本或安装方式之间迁移。

• docs/HQ.md — Factory HQ。 介绍它是什么，以及它存储什么。

• docs/OPERATOR-UI.md — 第一个本地运维界面。 启动并排查仅限环回地址、未进行身份验证且只读的配置。

• docs/COMPLEXITY-ROUTING.md — 以能力为优先的调度。 复杂度标签、延迟绑定的模型选择、可用性和迁移恢复。

• docs/HIVES.md 和多主机 ADR — 多台主机。 Hive 类型、租约和主机角色。

• beadhive.ai — 如果你想先了解整体概念，再看命令，这里介绍 Beadhive 的概念和形态。

• docs/OVERVIEW.md — 其他所有内容。 设计与原理、配置、完整命令列表，以及逐个组件的介绍。

问题 / 反馈

一般问题、反馈和 Bug 报告请通过 GitHub Issues 提交。有关安全漏洞，请参阅 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)