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 update_plan

Decision test: "Will I need this context in 2 weeks?" → YES = bd

When to use bd:

• •Work spans multiple sessions or days
• •Tasks have dependencies or blockers
• •Need to survive conversation compaction
• •Exploratory/research work with fuzzy boundaries
• •Collaboration with team (git sync)

When to use update_plan:

• •Single-session linear tasks
• •Simple checklist for immediate work
• •All context is in current conversation
• •Will complete within current session

Prerequisites

bd --version  # Requires v0.34.0+

• •bd CLI installed and in PATH
• •Git repository (bd requires git for sync)
• •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 sync

Session Protocol

1. •bd ready — Find unblocked work
2. •bd show <id> — Get full context
3. •bd update <id> --status in_progress — Start work
4. •Add notes as you work (critical for compaction survival)
5. •bd close <id> --reason "..." — Complete task
6. •bd sync — Persist to git (always run at session end)

Parallel agent workflow (PRs / Coder Tasks)

When multiple agents are working in parallel, treat .beads/* as a serialized, shared write surface.

• •One writer: only the orchestrator updates/closes issues and commits .beads/issues.jsonl.
• •Workers: do not edit .beads/*; produce code changes only (branch/PR name includes the bead id).
• •After merge: orchestrator closes the bead(s), runs bd sync, and pushes the beads commit.
• •Conflicts: if .beads/issues.jsonl conflicts, resolve it, then re-run bd sync to ensure the DB and JSONL match.

Sync Branch (Protected main, worktrees)

If your repo uses protected branches or git worktree, configure a dedicated sync branch so bd can commit/push beads data without touching your current branch.

Recommended (team/shared, version-controlled): add to .beads/config.yaml:

sync-branch: beads-sync

Other options:

• •Per-user default for all repos: ~/.config/bd/config.yaml (sync-branch: ...)
• •Temporary override: BEADS_SYNC_BRANCH=...
• •Legacy/DB-backed: bd config set sync.branch <branch> (also updates sync-branch in config.yaml when possible)

Advanced Features

Resources

Full Documentation

• •bd prime: AI-optimized workflow context
• •GitHub: github.com/steveyegge/beads