Beads 全平台安装指南：bd CLI、Claude Code 插件与 MCP 服务器的完整安装与配置

Beads 全平台安装指南：bd CLI、Claude Code 插件与 MCP 服务器的完整安装与配置

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

Beads（命令行为bd）是一个为编码 Agent 提供「记忆升级」的轻量级问题追踪系统。本篇技术指南以仓库中的 docs/getting-started/installation.md 为主体，系统讲解其组件构成、macOS / Linux / Windows / FreeBSD 各平台的安装方式（Homebrew、npm、go install、安装脚本）、IDE 与编码 Agent 的集成配置，以及安装后的验证、升级与卸载流程。读完本文，你将能够在任意目标平台上正确选型并安装bd，并为 Claude Code、Cursor、GitHub Copilot 等工具完成开箱即用的集成。

组件概览：bd CLI、Claude Code 插件与 MCP 服务器

Beads 由多个组件组成，理解它们的定位是正确安装的第一步。

三者的关系：

• bd CLI 是核心，应首先通过 Homebrew、npm 或脚本安装；
• 插件为 Claude Code 增加 Slash 命令，但依赖CLI 已安装；
• MCP 服务器是 CLI 在无 Shell 访问环境中的替代方案。

重要概念：Beads 是系统级安装的，而不是克隆进你的项目。项目中的.beads/目录只存放问题数据库（issue database），不含任何可执行文件。

典型环境安装组合：

三者互斥吗？不。CLI + 插件 + MCP 可以同时安装，互不冲突；但绝大多数用户只需要 CLI 一个组件。

快速安装（推荐方式）

Homebrew（macOS / Linux）

brew install beads

Homebrew core 中的beadsformula 是官方支持的 Homebrew 包。如果你之前通过旧的 tap formula 以bd名义安装过，请参考 docs/getting-started/upgrading.md#homebrew 中的迁移说明切换到 core formula。

为什么选择 Homebrew？

• 一条命令完成安装；
• 通过brew upgrade自动更新；
• 无需安装 Go 工具链；
• 自动处理 PATH 配置。

Mise-en-place（macOS / Linux / Windows）

可以通过 mise 从最新 GitHub Release 安装 beads：

mise install github:gastownhall/beads mise use -g github:gastownhall/beads

-g标志将 beads 全局启用；如需为特定项目启用不同版本，省略该标志即可。

为什么选择 Mise？

• 与 Homebrew 一样简单：mise up更新、无需 Go、自动处理 PATH；
• 支持所有平台；
• 始终获取最新 Release；
• 可以为特定项目选择不同的 Release 版本。

需要注意的是，Mise 的 Go 后端与go install存在同样的限制；默认应优先使用其 Release 后端。

快速安装脚本（macOS / Linux / FreeBSD）

curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

安装脚本位于仓库根目录 scripts/install.sh，安装时会自动：

• 检测平台（macOS / Linux / FreeBSD，amd64 / arm64 / arm）；
• 对照 Release 的checksums.txt校验下载的归档文件；
• 若本机有 Go，回退到受支持的go install模式；
• 必要时回退到从源码构建；
• 如有需要，指导你完成 PATH 配置。

从源码看，脚本的安装优先级是「Release 预编译归档 → go install → 从源码构建」三级回退（scripts/install.sh 中的main()函数）：先尝试install_from_release，失败后若检测到 Go 1.24+ 则尝试install_with_go，最后才build_from_source。校验环节由verify_release_checksum完成——它会在 Release 元数据缺少checksums.txt时直接拒绝安装未经验证的二进制（refusing to install unverified binary），并从sha256sum/shasum/openssl中自动选择可用的 SHA-256 工具。

macOS 签名说明：在 macOS 上，脚本默认保留下载二进制的 Release 签名（Gatekeeper 行为）。只有当你明确需要本地临时重签名时，才需要显式开启：

BEADS_INSTALL_RESIGN_MACOS=1 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

安装方式对比

TL;DR：有 Homebrew 就用 Homebrew；身处 Node.js 环境就用 npm；一次性安装或 CI 场景用安装脚本。

go install 与构建依赖

如果你没有特别需求，优先使用 Homebrew、npm 或安装脚本，而不是go install。

go install有两种受支持的构建模式，对应不同能力：

• 仅服务器模式（nocgo，最简单）：

  CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest

  任何装有 Go 工具链的机器都能构建，无需 C 编译器。产出的是仅服务器模式的二进制——必须运行外部dolt sql-server，并使用bd init --server初始化。服务器模式的具体搭建参见 docs/architecture/dolt.md。

• 内嵌能力（cgo）：

  CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest

  需要 C 编译器（Unix 下为 gcc/clang，Windows 下为 MinGW）。产出的是带默认内嵌 Dolt 后端的二进制——bd init开箱即用。

关于 ICU：两种模式都不需要ICU 头文件。内嵌能力的命令使用gms_pure_go标签，让 go-mysql-server 使用 Go 标准库的regexp而非 ICU 正则。这一点在 engdocs/ICU-POLICY.md 中有完整说明，仓库的 Makefile 也通过BUILD_TAGS := gms_pure_go全程携带该标签，并在doctor-build目标中给出了诊断：裸执行CGO_ENABLED=1 go build ./cmd/bd（不带-tags=gms_pure_go）会因为 go-icu-regex 找不到unicode/uregex.h而链接失败。

关于模块路径：go install请使用github.com/steveyegge/beads路径。尽管仓库现已迁移到gastownhall/beads，已发布的 Go 模块仍声明github.com/steveyegge/beads以保证兼容——这一点在 go.mod 第 1 行（module github.com/steveyegge/beads）与安装脚本 scripts/install.sh 的注释中均有印证。

如果没有特殊偏好，brew install beads或安装脚本即可得到开箱即用的内嵌能力构建。

构建依赖（仅贡献者需要）

注意：这些依赖仅在从源码构建时需要。通过 Homebrew、npm 或安装脚本安装的用户可以完全跳过本节。

从源码构建需要一个 C 编译器（用于 CGO / 内嵌 Dolt）。ICU不是必需的——所有构建都使用gms_pure_go标签，选择 Go 标准库regexp而非 ICU 正则，详见 engdocs/ICU-POLICY.md。

macOS（Homebrew）：

brew install zstd

Linux（Debian/Ubuntu）：

sudo apt-get install -y libzstd-dev

Linux（Fedora/RHEL）：

sudo dnf install -y libzstd-devel

仅维护者需要：如果确实需要运行 scripts/test-icu-path.sh（该脚本演练遗留的 ICU 代码路径），才需要安装 ICU 头文件：macOS 用brew install icu4c，Linux 用sudo apt-get install -y libicu-dev。正常开发不需要。

平台特定安装

macOS

通过 Homebrew（推荐）：

brew install beads

通过 go install（仅服务器模式）：

CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest

通过 go install（内嵌能力，需要 Xcode CLI 工具）：

CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest

从源码构建：

git clone https://github.com/gastownhall/beads cd beads make build sudo mv bd /usr/local/bin/

Linux

通过 Homebrew（Linux 同样适用）：

brew install beads

Arch Linux（AUR）：

# 从 AUR 安装 yay -S beads-git # 或 paru -S beads-git

AUR 包由社区维护。

通过 go install（仅服务器模式）：

CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest

通过 go install（内嵌能力，需要 gcc）：

CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest

FreeBSD

通过快速安装脚本：

curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

通过 go install（仅服务器模式）：

CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest

Windows 11

Beads 提供原生 Windows 支持——无需 MSYS 或 MinGW即可完成基础安装。

前置条件：

• Go 1.24+ 已安装（将%USERPROFILE%\go\bin加入PATH）；
• Git for Windows。

通过 PowerShell 脚本安装：

irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex

该脚本位于仓库根目录 install.ps1，会优先安装预构建的 Windows Release（若存在）并对照 Release 的checksums.txt校验下载的 ZIP 校验和。从脚本源码看（install.ps1 中的Get-ExpectedReleaseChecksum），校验环节在 Release 缺少checksums.txt时会直接拒绝安装（refusing unverified install），并通过Get-FileHash -Algorithm SHA256与期望值比对，不一致则中止。Go 仅在go install或源码构建时才需要。

通过 go install（仅服务器模式）：

$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest

这会产出仅服务器模式的二进制，无 C 编译器要求——这是在 Windows 上获得可用bd的最快路径。

通过 go install（内嵌能力，需要 Windows CGO 工具链）：

$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest

需要在 PATH 上提供 GCC 兼容的 Windows CGO 编译器，例如 MinGW-w64/MSYS2 的gcc，或 MSYS2 LLVM 中面向windows-gnu的clang（clang64/clangarm64）。ICU不是必需的——gms_pure_go会选择 Go 标准库regexp。Visual Studio 的cl.exe单独是不够的，因为 Go 传递的是 GCC 风格的 CGO 标志；请使用 MinGW/MSYS2 工具链，或设置CC，或在源码构建时设置WINDOWS_CGO_BINS。Makefile 的build目标同样印证了这一约束：Windows 构建会依次探测CC、gcc、clang及WINDOWS_CGO_BINS列表中各工具链的 gcc/clang，找不到则报错退出。

从源码构建：

git clone https://github.com/gastownhall/beads cd beads make build Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\

Windows 注意事项：

• Dolt 服务器监听 loopback TCP 端点；
• 需要允许bd.exe的 loopback 流量通过主机防火墙；
• 通过 npm 安装时，bd是一个bd.cmdshim——Node 的execFile/spawn需要shell: true才能运行它（详见 docs/reference/troubleshooting.md#platform-specific-issues）。

另外，仓库根目录的 install.ps1 还支持两个环境变量：BEADS_INSTALL_SKIP_GOINSTALL=1跳过 go install 步骤，BEADS_INSTALL_SOURCE=<path|url>覆盖源码来源（本地目录或 git 仓库地址）。

IDE 与编辑器集成

CLI + Hooks（推荐方案）

这是 Claude Code、Cursor、Windsurf 及其他有 Shell 访问能力编辑器的最佳实践：

# 1. 安装 bd CLI（见上文"快速安装"） brew install beads # 2. 在项目中初始化 cd your-project bd init --quiet # 3. 设置编辑器集成（任选其一） bd setup claude # Claude Code - 安装 SessionStart hooks bd setup copilot # GitHub Copilot CLI - 创建 .copilot-plugin/plugin.json + .github/copilot-instructions.md bd setup cursor # Cursor IDE - 创建 .cursor/rules/beads.mdc bd setup aider # Aider - 创建 .aider.conf.yml bd setup codex # Codex CLI - 安装 Beads skill、AGENTS.md 指引与原生 hooks bd setup factory # Factory.ai Droid - 创建/更新 AGENTS.md bd setup mux # Mux - 创建/更新 AGENTS.md

工作原理：

• bd init默认会创建或更新AGENTS.md并安装项目的 Claude/Codex 集成，除非使用--skip-agents或--stealth；
• 编辑器 hooks/rules 会在会话启动时自动注入bd prime；
• Codex 0.129.0+ 使用原生/hooks：SessionStart 注入bd prime，compact hooks 将上下文标记为过期，压缩后的下一次提示会刷新一次 Beads 上下文；
• bd prime提供约 1-2k token 的工作流上下文；
• 你直接使用bdCLI 命令；
• Git hooks（由bd init安装）负责刷新导出与遗留回退；bd dolt push/pull负责数据库同步；
• bd onboard为不支持的 Agent 或自定义指令文件打印一段小型手动配置片段。

为什么推荐这种方式？

• 上下文高效——约 1-2k token，对比 MCP 工具 schema 的 10-50k token；
• 更低延迟——直接调用 CLI，无 MCP 协议开销；
• 通用——适用于任何有 Shell 访问能力的编辑器。

验证安装：每个 recipe 都支持检查标志，例如bd setup claude --check或bd setup copilot --check。

关于bd setup的 recipe 架构、--check/--remove/--global等标志以及full/minimal模板配置文件的详细说明，参见 docs/getting-started/ide-setup.md。

Claude Code 插件（可选）

需要 Slash 命令增强 UX 时：

# 在 Claude Code 中 /plugin marketplace add gastownhall/beads /plugin install beads # 重启 Claude Code

插件提供：

• Slash 命令：/beads:ready、/beads:create、/beads:show、/beads:update、/beads:close等；
• 用于自主执行的任务 Agent。

完整插件文档参见 docs/integrations/claude-code-plugin.md。

GitHub Copilot

VS Code 中的 GitHub Copilot：安装 MCP 服务器（uv tool install beads-mcp）并在项目中创建.vscode/mcp.json——或将其加入 VS Code 用户级 MCP 配置以对全部项目生效。完整设置指南（含各平台用户级配置路径）参见 docs/integrations/github-copilot.md。

GitHub Copilot CLI 终端集成：

bd setup copilot # 安装项目 Copilot 插件 + 仓库指令 bd setup copilot --check # 验证项目集成文件是否存在

该配置当前仅限项目级。它写入.copilot-plugin/plugin.json和.github/copilot-instructions.md；目前 Copilot 没有单独的--global或--project模式，也不会管理~/.copilot/...路径。完整指南参见 docs/integrations/copilot-cli.md。

MCP 服务器（替代方案）

仅在 CLI 不可用时（Claude Desktop、无 Shell 的 Sourcegraph Amp）使用 MCP：

# 使用 uv（推荐） uv tool install beads-mcp # 或使用 pip pip install beads-mcp

beads-mcp的 Python 包源码位于仓库 integrations/beads-mcp 目录。

Claude Desktop 配置（macOS）：

在~/Library/Application Support/Claude/claude_desktop_config.json中添加：

{ "mcpServers": { "beads": { "command": "beads-mcp" } } }

Sourcegraph Amp 配置及 MCP 服务器的详细文档参见 docs/integrations/mcp-server.md。

验证安装

安装完成后，验证bd是否工作：

bd version bd help

故障排查

更多排查内容参见 docs/reference/troubleshooting.md。

bd: command not found

说明bd不在 PATH 中：

# 检查是否已安装 go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # 将 Go bin 加入 PATH（添加到 ~/.bashrc 或 ~/.zshrc） export PATH="$PATH:$(go env GOPATH)/bin" # 或使用推荐的安装器重新安装 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

安装脚本自身也内置了 PATH 防护：若安装目录不在 PATH 中会打印提示（$install_dir is not in your PATH），并检测 PATH 上是否存在多个bd可执行文件（warn_if_multiple_bd）以避免旧版本遮蔽新版本——详见 scripts/install.sh 中的warn_if_multiple_bd实现。

zsh: killed bd或 macOS 上崩溃

这通常由 CGO/SQLite 兼容性问题引起：

# 安装内嵌能力构建 CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest

如果通过 Homebrew 安装，通常无需如此——formula 已启用 CGO。若 Homebrew 版本仍然崩溃，请提交 issue。

MCP 服务器启动失败（独立 beads-mcp）

Claude Code 插件本身并不捆绑 MCP 服务器。如果你配置了独立的beads-mcp服务器（见 docs/integrations/mcp-server.md）但它立即失败，很可能是uv未安装或不在 PATH 中。

症状：

• 插件 Slash 命令正常，但 MCP 工具不可用；
• 错误日志显示command not found: uv；
• 服务器启动时静默失败。

解决方案：

# 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 重启 Shell 或更新 PATH source ~/.local/bin/env # 验证 uv 可用 which uv # 重启 Claude Code

替代安装方法参见 docs/integrations/claude-code-plugin.md。

更新 bd

升级检查清单：

1. 用当前bd先同步远程后端数据库，再安装新二进制：bd dolt pushbd dolt pull
2. 迁移前备份：bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl
3. 按下表对应你安装方式的命令升级。
4. 升级后：bd info --whats-newbd hooks installbd version
5. 如果跨过远程后端数据库的 schema 迁移，只有指定迁移者执行：bd migratebd dolt push

其他克隆应安装新二进制后运行bd bootstrap，而不是独立迁移。完整流程参见 docs/getting-started/upgrading.md。

快速安装脚本（macOS / Linux / FreeBSD）

curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

PowerShell 安装器（Windows）

irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex

Homebrew

brew upgrade beads

npm

npm update -g @beads/bd

npm 包定义位于仓库 npm-package/package.json，包名为@beads/bd，通过postinstall脚本在安装时拉取对应平台的原生二进制。

bun

bun install -g --trust @beads/bd

go install

使用你最初安装时的对应模式：

# 仅服务器模式 CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest # 内嵌能力 CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest

从源码

cd beads git pull make build sudo mv bd /usr/local/bin/

预发布版本（如 release candidate）只作为 GitHub prerelease 发布，不会推送到稳定的 Homebrew/npm/PyPI 渠道，因此brew upgrade等不会升级到它们——需要显式获取预发布构建。

升级后的步骤（hooks、迁移）参见 docs/getting-started/upgrading.md。

卸载

完整地从仓库移除 Beads 的步骤参见 docs/recovery/uninstalling.md。

下一步

安装完成后：

1. 初始化项目：cd your-project && bd init
2. 学习基础用法：参见 docs/getting-started/quickstart.md
3. 配置你的 Agent：参见 docs/getting-started/ide-setup.md，或运行bd setup --list
4. 浏览示例：仓库 examples 目录提供了 bash-agent、python-agent、formulas、多阶段开发、团队工作流等丰富用例

关于 Dolt 后端的两种运行模式（内嵌模式 vs 服务器模式）及其迁移、备份、远程同步的完整说明，可进一步阅读 docs/architecture/dolt.md。

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads