beads

Original：🇺🇸 English

Translated

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.

2installs

Sourcegastownhall/beads

Added on2026-08-23

NPX Install

npx skill4agent add gastownhall/beads beads

SKILL.md Content

View Translation Comparison →

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

bash

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:

bash

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 (live reference pointers), 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

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