Skip to main content

​
What is Beads?

Beads (bd) is a distributed, git-backed issue tracker designed specifically for AI-supervised coding workflows. It replaces messy markdown TODO lists with a dependency-aware graph database, allowing AI agents to handle long-horizon tasks without losing context.

​
The Problem

AI coding agents struggle with long-running projects because they:
  • Lose context between sessions
  • Can’t track dependencies between tasks
  • Create messy markdown TODO lists that become outdated
  • Have no way to coordinate work across multiple agents or branches

​
The Solution

Beads provides persistent, structured memory for coding agents:

Dependency-Aware

Track blockers and relationships between issues. Only show work that’s ready to be done.

Git-Friendly

Dolt-powered version control with cell-level merge and native sync. Works seamlessly with branches and forks.

Zero Conflicts

Hash-based IDs (bd-a1b2) prevent collisions when multiple agents or branches work concurrently.

Agent-Optimized

JSON output, ready work detection, and automatic dependency tracking designed for AI workflows.

​
Key Features

​
Dolt-Powered Storage

Beads uses Dolt as its storage backend - a version-controlled SQL database:
  • Version control built-in: Every write auto-commits to Dolt history
  • Cell-level merge: Smarter conflict resolution than file-based systems
  • Native sync: Push/pull to Dolt remotes (DoltHub, S3, GCS, etc.)
  • SQL queries: Full SQL access for custom reporting and analysis

​
Hash-Based IDs

Issue IDs are content-based hashes (e.g., bd-a1b2, bd-f14c) that prevent collisions: 
# Multiple agents can create issues simultaneously
Agent 1: bd create "Add auth" -p 1  # → bd-a3f8
Agent 2: bd create "Fix bug" -p 0   # → bd-b9d2
# No conflicts - different hashes!

​
Hierarchical Organization

Organize large features with epic/task/subtask hierarchies: 
# Create epic
bd create "Auth System" -t epic -p 1  # → bd-a3f8

# Create child tasks
bd create "Login UI" --parent bd-a3f8      # → bd-a3f8.1
bd create "Backend validation" --parent bd-a3f8  # → bd-a3f8.2
bd create "Integration tests" --parent bd-a3f8   # → bd-a3f8.3

​
Dependency Tracking

Four types of relationships:
  • blocks: Task B can’t start until A is done
  • parent-child: Hierarchical organization (epics → tasks → subtasks)
  • relates_to: General association between issues
  • discovered-from: Track work discovered during implementation
# Add blocker dependency
bd dep add bd-f14c bd-a1b2  # bd-f14c blocked by bd-a1b2

# Find ready work (no blockers)
bd ready

​
Ready Work Detection

Beads automatically identifies which tasks are ready to work on: 
$ bd ready
📋 Ready work (2 issues with no blockers):

1. [P0] bd-a1b2: Fix critical auth bug
2. [P1] bd-f14c: Set up database schema
Blocked issues won’t appear until their dependencies are resolved.

​
Architecture

1

Storage Layer

Dolt database in .beads/dolt/ provides version-controlled SQL storage with automatic commits and native sync.
2

CLI Layer

The bd command provides a rich CLI interface with JSON output for programmatic access.
3

Git Integration

Optional git hooks auto-sync the database on git operations (pull, push, checkout, merge).

​
How It Works

  1. Initialize in your project: bd init
  2. Create issues with dependencies: bd create "Task" --deps bd-123
  3. Find ready work: bd ready shows unblocked tasks
  4. Claim and work: bd update bd-456 --claim
  5. Complete: bd close bd-456 --reason "Done"
  6. Sync: bd dolt push sends to remote (or use git hooks for auto-sync)

​
Use Cases

​
AI Agent Workflows

# Agent checks for work
bd ready --json

# Agent claims a task atomically
bd update bd-a1b2 --claim --json

# Agent discovers new work during implementation
bd create "Found edge case" --deps discovered-from:bd-a1b2 --json

# Agent completes work
bd close bd-a1b2 --reason "Implemented with tests" --json

​
Multi-Branch Development

Hash-based IDs prevent merge conflicts: 
# Branch 1
git checkout -b feature-auth
bd create "Add OAuth" -p 1  # → bd-a3f8

# Branch 2
git checkout -b feature-api
bd create "API endpoints" -p 1  # → bd-f14c

# Merge both - no ID conflicts!
git merge feature-auth feature-api

​
Contributor vs Maintainer Modes

Maintainers (with push access):
  • Issues stored in-repo at .beads/
  • Shared with team via git
Contributors (fork workflow):
  • Issues routed to separate planning repo
  • Keeps experimental work out of PRs
  • Set via bd init --contributor

​
Platforms

Beads works on:
  • macOS
  • Linux
  • Windows
  • FreeBSD

​
Next Steps

Quickstart

Get up and running in 2 minutes

Installation

Install via Homebrew, npm, Go, or shell script

Build docs developers (and LLMs) love

Get started for freeTalk to us