Beads (bd): Using Git as a Distributed Database for AI Agent Task Tracking

Problem and Motivation

AI coding agents such as Claude Code or Gemini CLI have limited context windows and cannot retain long‑term state. Traditional issue trackers (e.g., Jira) are heavyweight for agents, while plain Markdown files lack structure and version control.

Beads Overview

Beads ( bd) is a lightweight, Git‑backed task engine designed for AI agents. It stores tasks as JSONL files under .beads/, enabling versioned, collaborative, dependency‑aware workflows without external services.

Core Architecture – Git as a Database

CLI Layer : Built with spf13/cobra, parses commands and prefers RPC calls to the daemon; falls back to direct DB access.

Daemon Process : One daemon per workspace, handles RPC over Unix domain sockets (named pipes on Windows), performs automatic sync and holds a database connection.

Storage Layer : Implements a Storage interface; pluggable back‑ends include SQLite, Dolt, or in‑memory stores.

Dual‑Storage Write Barrier

Writes are first persisted to SQLite for millisecond‑level feedback, then flushed to JSONL files. A debounced flush manager batches changes within a configurable 30‑second window, reducing disk I/O and Git commit frequency.

Concurrency and Locking

Process‑level mutex using flock (Unix) or LockFileEx (Windows) protects daemon.lock and .sync.lock.

SQLite connection pool: SetMaxOpenConns(1) for in‑memory DB; SetMaxOpenConns(runtime.NumCPU()+1) for file‑backed DB, leveraging WAL’s “1 writer + N readers”.

All storage operations require a context.Context for timeout and graceful shutdown.

Adaptive Hash IDs

Issue IDs are generated from a SHA‑256 hash of title, description, creator, timestamp and a nonce, encoded in base‑36. Length adapts to database size using birthday‑paradox calculations (e.g., 4‑character IDs for < 1 K issues, up to 8 characters for > 100 K). Collisions trigger up to ten nonce attempts before increasing length.

Issue State Machine

Eight core states: open, in_progress, blocked, deferred, closed, tombstone, pinned, hooked. Transitions are defined to guarantee data consistency and safe merges.

Blocked‑Issues Cache

Computing blocked issues for a 10 K‑issue database with a recursive CTE takes ~752 ms. Materialising the result into a blocked_issues_cache table reduces query time to ~29 ms (≈25× speed‑up). The cache is rebuilt (<50 ms) only when dependencies or statuses change.

Dependency Management

Beads supports multiple dependency types: blocks: hard block; child cannot start until parent is closed. parent‑child: hierarchical relationship; blocking propagates. related: soft link, does not affect execution order. discovered‑from: records issues discovered during execution.

Recursive CTE detection prevents cycles, ensuring the graph remains a DAG.

Practical Workflow Example

Typical AI‑coding scenario – refactoring a legacy authentication module:

# Create an Epic
$ bd create "Refactor user authentication module"
Created: bd-auth01

# Create sub‑tasks
$ bd create "Design new User table"
Created: bd-db002
$ bd create "Migrate old data"
Created: bd-migr03
$ bd create "Switch API logic"
Created: bd-api004

# Add dependencies (child depends on parent)
$ bd dep add bd-migr03 bd-db002
$ bd dep add bd-api004 bd-migr03

# Query ready work
$ bd ready --json
{
  "issues": [
    {
      "id": "bd-db002",
      "title": "Design new User table",
      "status": "open",
      "blocks": ["bd-migr03"]
    }
  ]
}

# Close a completed issue
$ bd close bd-db002

Closing bd-db002 automatically rebuilds the blocked‑issues cache, making bd-migr03 ready.

Integration with Claude Code (Two‑Way Interaction)

Place a CLAUDE.md (or AGENTS.md) file at the repository root describing the tool usage. After git init and bd init, Claude Code can create features, set complex dependencies, and query the graph with bd graph --all. The agent repeatedly fetches ready tasks, implements them, and updates issue status, allowing interruption and later resumption without losing context.

Performance and Tooling

Beads provides bd doctor --fix to detect missing Git hooks, sync divergence, and other setup issues. Community‑maintained viewers such as beads_viewer can display issue lists and dependency graphs in TUI or web UI.

Project Repository

https://github.com/steveyegge/beads