Beads - AI代理持久化任务记忆工具，基于Git的图结构问题跟踪器

beads by boshu2/agentops

250 周安装量

222 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/boshu2/agentops --skill beads

AI/机器学习项目管理自动化

🇨🇳中文介绍

Beads - AI 代理的持久化任务记忆

基于图结构的问题跟踪器，可在对话压缩后持续存在。

概述

bd (beads) 使用存储在 git 中的依赖感知图来替代 Markdown 任务列表。

关键区别：

bd : 多会话工作，依赖关系，可经受压缩，基于 git
任务工具 (TaskCreate/TaskUpdate/TaskList) : 单会话任务，状态跟踪，会话作用域内

决策规则 : 如果两周后恢复工作没有 bd 会很困难，则使用 bd。

操作规则

将实时 bd 读取视为权威。使用 bd show、bd ready、bd list 和 bd export 来检查当前跟踪器状态。当有实时 bd 数据可用时，不要将作为主要决策来源。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

从 /vibe 加载技能

用户说: /vibe

发生的情况:

代理通过依赖关系自动加载 beads 技能
代理调用 bd show <id> 读取问题元数据
代理将验证结果链接到正在检查的问题
输出在验证报告中引用问题 ID

结果: 验证报告包含问题上下文，无需手动进行 bd 查找。

从 /implement 加载技能

用户说: /implement ag-xyz-123

发生的情况:

代理加载 beads 技能以理解问题结构
代理调用 bd show ag-xyz-123 读取问题正文
代理使用 bd 输出检查依赖关系
代理在完成后使用 bd close ag-xyz-123 关闭问题

结果: 在实现过程中自动管理问题生命周期。

问题	原因	解决方案
找不到 bd 命令	bd CLI 未安装或不在 PATH 中	安装 bd: `brew install bd` 或检查 PATH
"not a git repository" 错误	bd 需要 git 仓库，当前目录未初始化	运行 `git init` 或导航到 git 仓库根目录
"beads not initialized" 错误	.beads/ 目录缺失	人类运行一次 `bd init --prefix <prefix>`
问题 ID 格式错误	前缀错误或 ID 格式错误	检查 rigs.json 获取正确前缀，遵循 `<prefix>-<tag>-<num>` 格式

🇺🇸English

Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction.

Overview

bd (beads) replaces markdown task lists with a dependency-aware graph stored in git.

Key Distinction :

bd : Multi-session work, dependencies, survives compaction, git-backed
Task tools (TaskCreate/TaskUpdate/TaskList) : Single-session tasks, status tracking, conversation-scoped

Decision Rule : If resuming in 2 weeks would be hard without bd, use bd.

Operating Rules

Treat live bd reads as authoritative. Use bd show, bd ready, bd list, and bd export to inspect current tracker state. Do not treat .beads/issues.jsonl as the primary decision source when live bd data is available.
Treat .beads/issues.jsonl as a git-friendly export artifact. If the repo tracks .beads/issues.jsonl and you mutate tracker state, refresh it explicitly with bd export -o .beads/issues.jsonl.
After closing or materially updating a child issue, reconcile the open parent in the same session. Update stale "remaining gap" notes immediately, and close the parent when the child resolved the parent's last real gap.
If bd ready returns a broad umbrella issue, do not implement directly against vague parent wording. First narrow the remaining gap into an execution-ready child issue, then land the child and reconcile the parent.
Normalize stale queue items instead of silently skipping them. Rewrite broad or partially absorbed beads to the actual remaining gap.
Use this post-mutation sequence when tracker state changed:

bd ... # mutate tracker state bd export -o .beads/issues.jsonl # if tracked in git bd vc status bd dolt commit -m "..." # if tracker changes are pending bd dolt push # only if a Dolt remote is configured

Prerequisites

bd CLI : Version 0.34.0+ installed and in PATH
Git Repository : Current directory must be a git repo
Initialization : bd init run once (humans do this, not agents)

Examples

Skill Loading from /vibe

User says: /vibe

What happens:

Agent loads beads skill automatically via dependency
Agent calls bd show <id> to read issue metadata
Agent links validation findings to the issue being checked
Output references issue ID in validation report

Result: Validation report includes issue context, no manual bd lookups needed.

Skill Loading from /implement

User says: /implement ag-xyz-123

What happens:

Agent loads beads skill to understand issue structure
Agent calls bd show ag-xyz-123 to read issue body
Agent checks dependencies with bd output
Agent closes issue with bd close ag-xyz-123 after completion

Result: Issue lifecycle managed automatically during implementation.

Troubleshooting

Problem	Cause	Solution
bd command not found	bd CLI not installed or not in PATH	Install bd: `brew install bd` or check PATH
"not a git repository" error	bd requires git repo, current dir not initialized	Run `git init` or navigate to git repo root
"beads not initialized" error	.beads/ directory missing	Human runs `bd init --prefix <prefix>` once
Issue ID format errors	Wrong prefix or malformed ID	Check rigs.json for correct prefix, follow `<prefix>-<tag>-<num>` format

Reference Documents

Weekly Installs

200

Repository

boshu2/agentops

GitHub Stars

198

First Seen

Feb 2, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex197

opencode196

github-copilot196

amp196

kimi-cli196

gemini-cli196

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

56,200 周安装