✓ Verified 🛒 E-commerce ✓ Enhanced Data

Beads

Git-backed issue tracker for AI agents.

Rating: 4.2 (66 reviews)
Downloads: 11,443 downloads
Version: 1.0.0

Overview

Git-backed issue tracker for AI agents.

Complete Documentation

View Source →

Beads

Distributed, git-backed graph issue tracker for AI agents. Replaces markdown plans with a dependency-aware task graph stored as JSONL in .beads/.

Quick Start

bash

# Initialize (non-interactive for agents)
bd init --quiet

# Check ready work
bd ready --json

# Create a task
bd create "Complete task X" -p 1 --json

# View task
bd show bd-a1b2 --json

Core Workflow

bd ready --json — Find unblocked work
bd update --status in_progress — Claim task
Do the work
bd close --reason "Done" — Complete task
bd sync — Force sync before ending session

Agent-Critical Rules

Always use --json for machine-readable output
Never use bd edit — opens $EDITOR, unusable by agents
Use bd update instead: bd update --title "New title" --description "New desc"
Run bd sync at end of session to flush changes to git

Commands

Initialize

bash

bd init --quiet              # Non-interactive, auto-installs hooks
bd init --prefix myproj      # Custom ID prefix
bd init --stealth            # Local only, don't commit .beads/
bd init --contributor        # Fork workflow (separate planning repo)

Create Issues

bash

bd create "Title" -p 1 --json                    # Priority 1 (0=critical, 3=low)
bd create "Title" -t epic -p 0 --json            # Create epic
bd create "Subtask" -p 1 --json                  # Under epic: bd-a3f8.1, .2, .3
bd create "Found issue" --deps discovered-from:bd-a1b2 --json

Types: task, bug, feature, epic Priorities: 0 (P0/critical) to 3 (P3/low)

Query Issues

bash

bd ready --json                    # Unblocked tasks (the work queue)
bd ready --priority 0 --json       # Only P0s
bd ready --assignee agent-1 --json # Assigned to specific agent

bd list --json                     # All issues
bd list --status open --json       # Open issues
bd list --priority 1 --json        # P1 issues

bd show bd-a1b2 --json             # Issue details + audit trail
bd blocked --json                  # Issues waiting on dependencies
bd stats --json                    # Statistics

Update Issues

bash

bd update bd-a1b2 --status in_progress --json
bd update bd-a1b2 --title "New title" --json
bd update bd-a1b2 --description "Details" --json
bd update bd-a1b2 --priority 0 --json
bd update bd-a1b2 --assignee agent-1 --json
bd update bd-a1b2 --design "Design notes" --json
bd update bd-a1b2 --notes "Additional notes" --json

Status values: open, in_progress, blocked, closed

Close Issues

bash

bd close bd-a1b2 --reason "Completed" --json
bd close bd-a1b2 bd-b2c3 --reason "Batch close" --json

Dependencies

bash

bd dep add bd-child bd-parent      # child blocked by parent
bd dep add bd-a1b2 bd-b2c3 --type related    # Related link
bd dep add bd-a1b2 bd-epic --type parent     # Parent-child

bd dep tree bd-a1b2                # Visualize dependency tree
bd dep remove bd-child bd-parent   # Remove dependency
bd dep cycles                      # Detect circular deps

Dependency types: blocks (default), related, parent, discovered-from

Git Sync

bash

bd sync                    # Export → commit → pull → import → push
bd hooks install           # Install git hooks for auto-sync

The daemon auto-syncs with 30s debounce. Use bd sync to force immediate sync.

Maintenance

bash

bd admin compact --dry-run --json   # Preview compaction
bd admin compact --days 90          # Compact issues closed >90 days
bd doctor                           # Check database health

Hierarchical IDs (Epics)

bash

bd create "Project Alpha" -t epic -p 1 --json   # Returns: bd-a3f8
bd create "Phase 1" -p 1 --json                 # Returns: bd-a3f8.1
bd create "Research" -p 1 --json                # Returns: bd-a3f8.2
bd create "Review" -p 1 --json                  # Returns: bd-a3f8.3

Up to 3 levels: bd-a3f8 → bd-a3f8.1 → bd-a3f8.1.1

Multi-Agent Coordination

bash

# Agent claims work
bd update bd-a1b2 --status in_progress --assignee agent-1 --json

# Query assigned work
bd ready --assignee agent-1 --json

# Track discovered work
bd create "Found issue" --deps discovered-from:bd-a1b2 --json

Commit Convention (Optional)

For git-tracked projects, include issue ID in commit messages for traceability:

bash

git commit -m "Complete research phase (bd-a1b2)"

Session End Checklist

Before ending a session:

bash

bd sync                    # Flush all changes
bd ready --json            # Show next work for handoff

Installation

Terminal bash


openclaw install beads

Copied!

💻Code Examples

bd show bd-a1b2 --json

bd-show-bd-a1b2---json.txt

## Core Workflow

1. `bd ready --json` — Find unblocked work
2. `bd update <id> --status in_progress` — Claim task
3. Do the work
4. `bd close <id> --reason "Done"` — Complete task
5. `bd sync` — Force sync before ending session

## Agent-Critical Rules

- **Always use `--json`** for machine-readable output
- **Never use `bd edit`** — opens $EDITOR, unusable by agents
- **Use `bd update`** instead: `bd update <id> --title "New title" --description "New desc"`
- **Run `bd sync`** at end of session to flush changes to git

## Commands

### Initialize

bd create "Found issue" --deps discovered-from:bd-a1b2 --json

bd-create-found-issue---deps-discovered-frombd-a1b2---json.txt

Types: `task`, `bug`, `feature`, `epic`
Priorities: `0` (P0/critical) to `3` (P3/low)

### Query Issues

bd update bd-a1b2 --notes "Additional notes" --json

bd-update-bd-a1b2---notes-additional-notes---json.txt

Status values: `open`, `in_progress`, `blocked`, `closed`

### Close Issues

bd dep cycles # Detect circular deps

bd-dep-cycles--detect-circular-deps.txt

Dependency types: `blocks` (default), `related`, `parent`, `discovered-from`

### Git Sync

bd hooks install # Install git hooks for auto-sync

bd-hooks-install--install-git-hooks-for-auto-sync.txt

The daemon auto-syncs with 30s debounce. Use `bd sync` to force immediate sync.

### Maintenance

bd create "Review" -p 1 --json # Returns: bd-a3f8.3

bd-create-review--p-1---json--returns-bd-a3f83.txt

Up to 3 levels: `bd-a3f8` → `bd-a3f8.1` → `bd-a3f8.1.1`

## Multi-Agent Coordination

bd create "Found issue" --deps discovered-from:bd-a1b2 --json

bd-create-found-issue---deps-discovered-frombd-a1b2---json.txt

## Commit Convention (Optional)

For git-tracked projects, include issue ID in commit messages for traceability:

git commit -m "Complete research phase (bd-a1b2)"

git-commit--m-complete-research-phase-bd-a1b2.txt

## Session End Checklist

Before ending a session:

example.sh

# Initialize (non-interactive for agents)
bd init --quiet

# Check ready work
bd ready --json

# Create a task
bd create "Complete task X" -p 1 --json

# View task
bd show bd-a1b2 --json

example.sh

bd init --quiet              # Non-interactive, auto-installs hooks
bd init --prefix myproj      # Custom ID prefix
bd init --stealth            # Local only, don't commit .beads/
bd init --contributor        # Fork workflow (separate planning repo)