beads

install

source · Clone the upstream repo

git clone https://github.com/gastownhall/beads

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/gastownhall/beads "$T" && mkdir -p ~/.claude/skills && cp -r "$T/claude-plugin/skills/beads" ~/.claude/skills/gastownhall-beads-beads && rm -rf "$T"

manifest: claude-plugin/skills/beads/SKILL.md

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 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 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
Chemistry (pour/wisp)	`bd pour` , `bd wisp`	CHEMISTRY_PATTERNS.md
Agent beads	`bd agent --help`	AGENTS.md
Async gates	`bd gate --help`	ASYNC_GATES.md
Worktrees	`bd worktree --help`	WORKTREES.md

Resources

Category	Files
Getting Started	BOUNDARIES.md, CLI_REFERENCE.md, WORKFLOWS.md
Core Concepts	DEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md
Resilience	RESUMABILITY.md, TROUBLESHOOTING.md
Advanced	MOLECULES.md, CHEMISTRY_PATTERNS.md, AGENTS.md, ASYNC_GATES.md, WORKTREES.md
Reference	STATIC_DATA.md, INTEGRATION_PATTERNS.md

Validation

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).