Back to Details

beads

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Beads (bd)

Beads (bd)

Distributed, git-backed graph issue tracker for AI coding agents. Persistent memory with dependency-aware task tracking.
一款面向AI编码Agent的分布式、基于Git的图谱化问题追踪工具，具备依赖感知型任务追踪的持久化记忆功能。

Quick Start

快速开始

bash
undefined
bash
undefined

Install

Install

brew install steveyegge/beads/bd
brew install steveyegge/beads/bd

or

or

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

Initialize in repo (humans run once)

Initialize in repo (humans run once)

bd init
bd init

Tell your agent

Tell your agent

echo "Use 'bd' for task tracking" >> AGENTS.md
undefined
echo "Use 'bd' for task tracking" >> AGENTS.md
undefined

When to Use

适用场景

  • AI agent needs persistent task memory across sessions
  • Tracking dependencies between tasks (
    blocks:
    , 
    depends_on:
    )
  • Multi-agent/multi-branch workflows (hash-based IDs prevent conflicts)
  • Incremental delivery with molecules/gates
  • Sync issues with GitLab, Linear, Jira, GitHub
  • AI Agent需要跨会话的持久化任务记忆
  • 追踪任务间的依赖关系（
    blocks:
    、
    depends_on:
    ）
  • 多Agent/多分支工作流（基于哈希的ID可避免冲突）
  • 借助分子任务/交付门实现增量交付
  • 与GitLab、Linear、Jira、GitHub同步问题

Essential Commands

核心命令

CommandAction
bd ready
List tasks with no open blockers
bd ready --gated
Tasks waiting at gate checkpoints
bd create "Title" -p 0
Create P0 task
bd show <id>
View task details and audit trail
bd update <id> --status=X
Update status (open/in_progress/done)
bd close <id>
Close task
bd dep add <child> <parent>
Link tasks (blocks, related, parent)
bd list
List issues (default: 50, non-closed)
bd sync
Sync with git/remote
bd kv set <key> <value>
Store key-value pair
bd kv get <key>
Retrieve stored value
bd backend
Show/configure storage backend
bd gitlab sync
Sync with GitLab
命令作用
bd ready
列出无未解决阻塞的任务
bd ready --gated
列出等待交付门检查的任务
bd create "Title" -p 0
创建P0优先级任务
bd show <id>
查看任务详情与审计追踪记录
bd update <id> --status=X
更新任务状态（open/in_progress/done）
bd close <id>
关闭任务
bd dep add <child> <parent>
关联任务（阻塞、相关、父子关系）
bd list
列出问题（默认显示50条未关闭任务）
bd sync
与Git/远程仓库同步
bd kv set <key> <value>
存储键值对
bd kv get <key>
检索存储的键值对
bd backend
查看/配置存储后端
bd gitlab sync
与GitLab同步

Hash-Based IDs

基于哈希的ID

Issues use hash-based IDs like 
bd-a1b2
to prevent merge conflicts:
bash
bd create "Fix login bug" -p 1
问题采用类似
bd-a1b2
的哈希式ID，避免合并冲突：
bash
bd create "Fix login bug" -p 1

Created: bd-x7k3

Created: bd-x7k3

bd show bd-x7k3
undefined
bd show bd-x7k3
undefined

Hierarchical IDs

层级化ID

bd-a3f8      (Epic)
bd-a3f8.1    (Task)
bd-a3f8.1.1  (Sub-task)
Use 
bd children <id>
to view hierarchy.
bd-a3f8      (Epic)
bd-a3f8.1    (Task)
bd-a3f8.1.1  (Sub-task)
使用
bd children <id>
查看层级结构。

References

参考文档

FilePurpose
workflow.mdDaily operations, status flow, sync
authoring.mdWriting quality issues, EARS patterns
molecules.mdMolecules, gates, formulas, compounds
sync.mdGit sync, sync-branch, Linear/Jira import
文件用途
workflow.md日常操作、状态流转、同步机制
authoring.md编写高质量问题、EARS模式
molecules.md分子任务、交付门、规则、组合任务
sync.mdGit同步、同步分支、Linear/Jira导入

Key Concepts

核心概念

Git as Database

以Git为数据库

Issues stored as JSONL in 
.beads/
. Versioned, branched, merged like code.
问题以JSONL格式存储在
.beads/
目录下，像代码一样支持版本控制、分支、合并。

Dependency Graph

依赖图谱

bash
bd dep add bd-child bd-parent --blocks   # child blocks parent
bd dep add bd-a bd-b --related           # related items
bd ready                                 # only shows unblocked work
bash
bd dep add bd-child bd-parent --blocks   # 子任务阻塞父任务
bd dep add bd-a bd-b --related           # 关联相关项
bd ready                                 # 仅显示未被阻塞的任务

Molecules (Advanced)

分子任务（进阶功能）

Molecules group related issues with gates for incremental delivery:
bash
bd mol create "Feature X" --steps=3      # Create 3-step molecule
bd mol progress bd-xyz                   # Check progress
bd mol burn bd-xyz                       # Complete molecule
分子任务可将相关问题分组，并通过交付门实现增量交付：
bash
bd mol create "Feature X" --steps=3      # 创建包含3个步骤的分子任务
bd mol progress bd-xyz                   # 查看进度
bd mol burn bd-xyz                       # 完成分子任务

Stealth Mode

隐身模式

Use Beads locally without committing to repo:
bash
bd init --stealth
可在本地使用Beads，无需提交到仓库：
bash
bd init --stealth

Contributor vs Maintainer

贡献者与维护者模式

bash
undefined
bash
undefined

Contributor (forked repos) — separate planning repo

贡献者（复刻仓库）—— 使用独立的规划仓库

bd init --contributor
bd init --contributor

Maintainer auto-detected via SSH/HTTPS credentials

维护者模式会通过SSH/HTTPS凭据自动识别

undefined
undefined

Configuration

配置

Config stored in 
.beads/config.yaml
:
yaml
sync:
  branch: beads-sync # Sync to separate branch
  remote: origin
daemon:
  auto_start: true
  auto_sync: true
types:
  custom:
    - name: spike
      statuses: [open, in_progress, done]
配置存储在
.beads/config.yaml
中：
yaml
sync:
  branch: beads-sync # Sync to separate branch
  remote: origin
daemon:
  auto_start: true
  auto_sync: true
types:
  custom:
    - name: spike
      statuses: [open, in_progress, done]

Storage Backend (Dolt Default)

存储后端（默认使用Dolt）

Beads now defaults to the embedded Dolt backend. Server mode is opt-in for multi-client access. Use 
bd backend
to inspect or configure backend settings, and see the sync reference for server-mode notes.
Beads现在默认使用嵌入式Dolt后端。多客户端访问需手动开启服务器模式。使用
bd backend
命令可查看或配置后端设置，同步相关说明请参考同步文档中的服务器模式部分。

Agent Integration

Agent集成

Tell Agent About Beads

告知Agent使用Beads

Add to 
AGENTS.md
:
markdown
undefined
将以下内容添加到
AGENTS.md
：
markdown
undefined

Task Tracking

Task Tracking

Use 
bd
for task tracking. Run 
bd ready
to find work.
undefined
Use 
bd
for task tracking. Run 
bd ready
to find work.
undefined

Agent-Optimized Output

面向Agent优化的输出

bash
BD_AGENT_MODE=1 bd list --json  # Ultra-compact JSON output
bd list --json                   # Standard JSON output
bash
BD_AGENT_MODE=1 bd list --json  # 超紧凑JSON输出
bd list --json                   # 标准JSON输出

MCP Plugin

MCP插件

Beads includes Claude Code MCP plugin for direct integration.
Beads内置Claude Code MCP插件，支持直接集成。

Critical Commands

关键命令

bash
undefined
bash
undefined

What to work on

查看可处理的任务

bd ready # Unblocked tasks bd ready --pretty # Formatted output
bd ready # 未被阻塞的任务 bd ready --pretty # 格式化输出

Create with dependencies

创建带依赖的任务

bd create "Task B" --blocks bd-a1b2
bd create "Task B" --blocks bd-a1b2

Doctor (fix issues)

诊断（修复问题）

bd doctor # Check health bd doctor --fix # Auto-fix problems
bd doctor # 检查健康状态 bd doctor --fix # 自动修复问题

Sync

同步

bd sync # Full sync bd sync --import-only # Import only
undefined
bd sync # 全量同步 bd sync --import-only # 仅导入
undefined

Anti-patterns

反模式

❌ Wrong✅ Correct
priority: high
-p 1
(P0-P4 numeric)
Manual JSON editingUse 
bd
commands
Ignoring 
bd ready
Always check blockers first
Skipping 
bd sync
Sync regularly
Creating without depsDeclare 
--blocks
upfront
❌ 错误做法✅ 正确做法
priority: high
-p 1
（使用P0-P4数字优先级）
手动编辑JSON文件使用
bd
命令进行操作
忽略
bd ready
命令		始终先检查阻塞任务
跳过
bd sync
操作		定期同步
创建任务时不声明依赖提前使用
--blocks
声明依赖

Links

相关链接