This skill teaches effective use of beads (bd), a distributed git-backed issue tracker designed for AI agents. Use beads to track tasks, manage dependencies, and coordinate work across sessions.
Getting Started
First, check if beads is available and initialized:
# Check if bd is installed
bd version
# Check if current project has beads initialized
bd statusIf bd is not installed, ask the user which installation method they prefer:
- npm:
npm install -g @beads/bd - Homebrew:
brew install beads(macOS) - Go:
go install github.com/steveyegge/beads/cmd/bd@latest
Do not install without user confirmation, as these are global system packages.
If not initialized in the project, run:
bd initFor personal use on shared projects (won't commit to repo):
bd init --stealthFor contributors on forked repos (routes to separate planning repo):
bd init --contributorEssential Commands
| Command | Purpose |
|---|---|
bd ready | List tasks with no open blockers (what to work on next) |
bd create "Title" -p 1 | Create a task (priority 0-3, lower = higher priority) |
bd show <id> | View task details and dependencies |
bd list | List all open issues |
bd close <id> | Mark task as complete |
bd update <id> --status in_progress | Update task status |
bd dep add <child> <parent> | Create dependency (child blocked by parent) |
bd sync | Force immediate sync to git |
Always use --json flag for machine-readable output when parsing results.
Task Hierarchy
Beads supports hierarchical IDs for organizing work:
bd-a3f8— Epic (large feature)bd-a3f8.1— Task under epicbd-a3f8.1.1— Sub-task
Create hierarchical tasks:
bd create "Epic: User Authentication" -t epic -p 1
bd create "Implement login flow" -p 1 --parent bd-a3f8Session Workflow
Starting a Session
# See what's ready to work on
bd ready --json
# Pick a task and mark it in progress
bd update <id> --status in_progress
# View full details
bd show <id> --jsonDuring Work
# Create new tasks as you discover them
bd create "Fix edge case in validation" -p 2
# Add dependencies
bd dep add <new-task> <blocking-task>
# Update task with notes
bd update <id> --notes "Found issue with timezone handling"Ending a Session ("Land the Plane")
When finishing work, complete ALL these steps:
# 1. File issues for remaining work
bd create "TODO: Add integration tests" -p 2
# 2. Close completed tasks
bd close <id> --reason "Completed"
# 3. Sync and push (MANDATORY)
git pull --rebase
bd sync
git push
# 4. Verify push succeeded
git status # Must show "up to date with origin"
# 5. Identify next task for follow-up
bd ready --jsonCRITICAL: Always push before ending a session. Unpushed work causes coordination problems in multi-agent workflows.
Important Rules
DO use bd update with flags
bd update <id> --description "new description"
bd update <id> --title "new title"
bd update <id> --design "design notes"
bd update <id> --notes "additional notes"
bd update <id> --acceptance "acceptance criteria"
bd update <id> --status in_progressDO NOT use bd edit
The edit command opens an interactive editor ($EDITOR) which AI agents cannot use. Always use bd update with flags instead.
DO sync before ending sessions
bd sync # Forces immediate export, commit, and pushWithout bd sync, changes sit in a 30-second debounce window and may not be committed.
DO include issue IDs in commit messages
git commit -m "Fix auth validation bug (bd-abc)"This enables bd doctor to detect orphaned issues.
Dependency Types
# Hard blocker - child cannot start until parent is done
bd dep add <child> <parent> --type blocks
# Soft link - related but not blocking
bd dep add <issue1> <issue2> --type related
# Parent-child - hierarchical relationship
bd dep add <child> <parent> --type parent-childHandling Merge Conflicts
If conflicts occur in .beads/issues.jsonl:
# Accept remote version
git checkout --theirs .beads/issues.jsonl
# Re-import to database
bd import -i .beads/issues.jsonl
# Continue with your workGit Hooks (Recommended)
Install hooks for automatic sync:
bd hooks installThis prevents stale JSONL problems by auto-syncing on commit, merge, push, and checkout.
MCP Server Alternative
For tighter integration, beads also offers an MCP server (beads-mcp) that provides tools directly to your agent. Install via:
pip install beads-mcpThe CLI (bd) and MCP server work with the same underlying database.
Quick Reference
# What should I work on?
bd ready
# Create a task
bd create "Fix bug in login" -p 1
# Start working
bd update bd-xyz --status in_progress
# Done working
bd close bd-xyz --reason "Completed"
bd sync
git push