Skip to main content
Beads uses a two-layer architecture that combines the speed of a local database with the reliability of version control, enabling distributed, git-backed issue tracking that feels like a centralized system.

​
The Two-Layer Data Model

Beads’ core design provides a distributed, git-backed issue tracker with two synchronized layers:

​
CLI Layer

All commands (bd create, bd list, bd update, bd close, etc.) interface directly with the database:
  • Built with Cobra framework in cmd/bd/
  • All commands support --json for programmatic use
  • Direct database access (server mode or embedded mode)
  • No special sync commands needed

​
Dolt Database

Storage backend at .beads/dolt/:
  • Version-controlled SQL database with cell-level merge
  • Server mode (multi-writer) or embedded mode (single-writer)
  • Fast queries with indexes and foreign keys
  • Stores issues, dependencies, labels, comments, events
  • Automatic Dolt commits on every write
  • Native push/pull to Dolt remotes

​
Remote Sync

Dolt remotes (DoltHub, S3, GCS, filesystem):
  • All collaborators share the same issue database
  • Cell-level merge for automatic conflict resolution
  • Protected branch support via separate sync branch
  • No special sync server needed

​
Why This Design?

​
Dolt for Versioned SQL

Queries complete in milliseconds with full SQL support. Dolt adds native version control:
  • Every write automatically committed to Dolt history
  • Complete audit trail
  • Cell-level merge resolves conflicts automatically

​
Dolt for Distribution

  • Native push/pull to Dolt remotes
  • Issues travel with your code
  • Offline work just works
  • No special sync server needed

​
Import/Export for Portability

bd import and bd export support JSONL format for:
  • Data migration
  • Bootstrapping new clones
  • Interoperability with other systems

​
Write Path

When you create or modify an issue:
  1. Command executes: bd create "New feature" writes to Dolt immediately
  2. Dolt commit: Every write is automatically committed to Dolt history
  3. Sync: Use bd dolt push to share changes with Dolt remotes
bd create "Add OAuth support" -p 1
# Auto-committed to Dolt history

bd dolt push
# Pushed to remote

​
Read Path

All queries run directly against the local Dolt database:
  1. Query: Commands read from fast local Dolt database via SQL
  2. Sync: Use bd dolt pull to fetch updates from Dolt remotes
bd ready
bd list --status open
bd show bd-a1b2
# All queries hit local database

​
Hash-Based Collision Prevention

The key insight enabling distributed operation: content-based hashing for deduplication.

​
The Problem

Sequential IDs (bd-1, bd-2, bd-3) cause collisions when multiple agents create issues concurrently: 
Branch A: bd create "Add OAuth"   → bd-10  ❌
Branch B: bd create "Add Stripe"  → bd-10  ❌ collision!

​
The Solution

Hash-based IDs derived from random UUIDs ensure uniqueness: 
Branch A: bd create "Add OAuth"   → bd-a1b2  ✓
Branch B: bd create "Add Stripe"  → bd-f14c  ✓ no collision

​
How It Works

1

Issue creation

Generate random UUID, derive short hash as ID
2

Progressive scaling

IDs start at 4 chars, grow to 5-6 chars as database grows
3

Content hashing

Each issue has a content hash for change detection
4

Import merge

Same ID + different content = update, same ID + same content = skip
This eliminates the need for central coordination while ensuring all machines converge to the same state.
See COLLISION_MATH.md for birthday paradox calculations on hash length vs collision probability.

​
Server Architecture

Each workspace can run its own Dolt server for multi-writer access:
Connects to dolt sql-server for multi-writer, high-concurrency access:
  • PID file at .beads/dolt/sql-server.pid
  • Logs at .beads/dolt/sql-server.log
  • Protocol defined in internal/rpc/protocol.go
# Start server (Gas Town)
gt dolt start

# Or manually
cd ~/.dolt-data/beads && dolt sql-server --port 3307

​
Data Types

Core types defined in internal/types/types.go:
TypeDescriptionKey Fields
IssueWork itemID, Title, Description, Status, Priority, Type
DependencyRelationship between issuesFromID, ToID, Type (blocks/related/parent-child/discovered-from)
LabelTag/categoryName, Color, Description
CommentDiscussion threadIssueID, Author, Content, Timestamp
EventAudit trail entryIssueID, Type, Data, Timestamp

​
Issue Status Flow

  • open: Ready to work on
  • in_progress: Actively being worked on
  • closed: Completed
  • blocked: Has open blocking dependencies
  • deferred: Postponed for later

​
Directory Structure

.beads/
├── dolt/             # Dolt database, sql-server.pid, sql-server.log (gitignored)
├── metadata.json     # Backend config (local, gitignored)
└── config.yaml       # Project config (optional, committed)
The .beads/dolt/ directory is gitignored. Only sync via Dolt push/pull, not git.

​
Key Code Paths

AreaFiles
CLI entrycmd/bd/main.go
Storage interfaceinternal/storage/storage.go
Dolt implementationinternal/storage/dolt/
RPC protocolinternal/rpc/protocol.go, server_*.go
Export logiccmd/bd/export.go
Import logiccmd/bd/import.go

Dependencies

Learn about dependency types and how they affect workflow

Workflows

Understand contributor, stealth, and maintainer modes

Memory

Persistent agent knowledge across sessions

Dolt Backend

Deep dive into Dolt configuration and features

Build docs developers (and LLMs) love

Get started for freeTalk to us