beads 精选

Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or recovering context.

写作 Claude Code Codex CLI Gemini CLI MCP 客户端 v0.60.0 MIT 2.8 万

在 GitHub 打开

安装方式

cp -r plugins/beads/skills/beads ~/.claude/skills/beads-2

把该 skill 目录放进客户端 skills 目录。不同客户端的目录可能不同，Claude Code 默认是 ~/.claude/skills/

整仓一次性获取：git clone --depth 1 https://github.com/gastownhall/beads.git

依赖与权限

无需 API Key
无需联网
依赖外部命令：git make
以上为按正文与 frontmatter 自动推断的信号，仅供参考；安装前建议先阅读原文。

触发场景

work spans sessionshas blockers

allowed-tools: Read,Bash(bd:*)

SKILL.md 正文

来源 gastownhall/beads@85464f5 · 许可 MIT · 内容未修改

Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

bd vs TodoWrite

Decision test: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.

bd (persistent)	TodoWrite (ephemeral)
Multi-session, dependencies, compaction survival	Single-session linear tasks
Dolt-backed team sync	Conversation-scoped

See [BOUNDARIES.md](resources/BOUNDARIES.md) for detailed comparison.

Prerequisites

bd --version  # Requires v0.60.0+

bd CLI installed and in PATH
Git repository (optional — use BEADS_DIR + --stealth for git-free operation)
Initialization: bd init run once (humans do this, not agents)

CLI Reference

Run bd prime for AI-optimized workflow context (auto-loaded by hooks).

Run bd <command> --help for specific command usage.

Essential commands: bd ready, bd create, bd show, bd update, bd close, bd dolt push

Session Protocol

bd ready — Find unblocked work
bd show <id> — Get full context
bd update <id> --claim — Claim and start work atomically
Add notes as you work (critical for compaction survival)
bd close <id> --reason "..." — Complete task
bd dolt push — Push to Dolt remote (if configured)

Output

Append --json to any command for structured output. Use bd show <id> --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred.

Error Handling

Error	Fix
`database not found`	`bd init <prefix>` in project root
`not in a git repository`	`git init` first
`disk I/O error (522)`	Move `.beads/` off cloud-synced filesystem
Status updates lag	Use server mode: `bd dolt start`

See [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) for full details.

Examples

Track a multi-session feature:

bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json                    # Shows unblocked work
bd update <id> --claim --json      # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json

Recover after compaction: bd list --status in_progress --json then bd show <id> --long

Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json

Advanced Features

Feature	CLI	Resource
Molecules (templates)	`bd mol --help`	[MOLECULES.md](resources/MOLECULES.md)
Chemistry (pour/wisp)	`bd pour`, `bd wisp`	[CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md)
Agent beads	`bd agent --help`	[AGENTS.md](resources/AGENTS.md)
Async gates	`bd gate --help`	[ASYNC_GATES.md](resources/ASYNC_GATES.md)
Worktrees	`bd worktree --help`	[WORKTREES.md](resources/WORKTREES.md)

Resources

Category	Files
Getting Started	[BOUNDARIES.md](resources/BOUNDARIES.md), [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) (live reference pointers), [WORKFLOWS.md](resources/WORKFLOWS.md)
Core Concepts	[DEPENDENCIES.md](resources/DEPENDENCIES.md), [ISSUE_CREATION.md](resources/ISSUE_CREATION.md), [PATTERNS.md](resources/PATTERNS.md)
Resilience	[RESUMABILITY.md](resources/RESUMABILITY.md), [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md)
Advanced	[MOLECULES.md](resources/MOLECULES.md), [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md), [AGENTS.md](resources/AGENTS.md), [ASYNC_GATES.md](resources/ASYNC_GATES.md), [WORKTREES.md](resources/WORKTREES.md)
Reference	[STATIC_DATA.md](resources/STATIC_DATA.md), [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md)

Validation

If bd --version reports newer than 0.60.0, this skill may be stale. Run bd prime for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth ([ADR-0001](adr/0001-bd-prime-as-source-of-truth.md)).