Beads Architecture Map — Architecture Guide

01

System Overview

Beads provides a persistent, structured memory for AI coding agents. Instead of losing context between sessions or relying on fragile markdown todo lists, agents get a real issue tracker with dependency graphs, priority queues, semantic compaction, and multi-agent coordination -- all backed by a version-controlled SQL database that syncs through Git.

130k+

Lines of Go

6

Days to Build

29

Internal Packages

308

CLI Source Files

18k+

GitHub Stars

Design Philosophy

Zero-conflict multi-agent workflows. Hash-based IDs prevent merge collisions. JSON output for agent consumption. Git-backed persistence with Dolt's cell-level merge resolution. No central server required -- every clone is a full database.

02

High-Level Architecture

Beads implements a two-layer data model: a CLI command layer built with Cobra on top, and a version-controlled Dolt SQL database underneath. Agents and humans interact through the same bd CLI, with optional MCP server integration for tool-calling environments.

System Architecture

graph TB subgraph Consumers["Consumers"] H["Human Developer"] A1["AI Agent (Claude)"] A2["AI Agent (Copilot)"] A3["AI Agent (Aider)"] end subgraph Interface["Interface Layer"] CLI["bd CLI
(Cobra Framework)"] MCP["MCP Server
(beads-mcp)"] JSON["--json Output
(Agent-optimized)"] end subgraph Core["Core Engine"] BEADS["internal/beads
Main Logic"] QUERY["internal/query
SQL Query Builder"] VALID["internal/validation
Input Validation"] TYPES["internal/types
Type Definitions"] IDGEN["internal/idgen
Hash ID Generator"] end subgraph Storage["Storage Layer"] DOLT["Dolt Database
(.beads/dolt/)"] GIT["Git Worktrees
(.git/beads-worktrees/)"] CONFIG["Config Files
(config.yaml + metadata.json)"] end subgraph Sync["Sync & Distribution"] DOLTHUB["DoltHub Remote"] S3["S3 / GCS"] GITREMOTE["Git Remote
(GitHub, GitLab)"] end H --> CLI A1 --> CLI A1 --> MCP A2 --> CLI A3 --> CLI CLI --> JSON MCP --> CLI CLI --> BEADS BEADS --> QUERY BEADS --> VALID BEADS --> TYPES BEADS --> IDGEN BEADS --> DOLT BEADS --> GIT BEADS --> CONFIG DOLT --> DOLTHUB DOLT --> S3 GIT --> GITREMOTE style Consumers fill:#1a2233,stroke:#484f58 style Interface fill:#1c2636,stroke:#f0a030 style Core fill:#1a2838,stroke:#00add8 style Storage fill:#1a2333,stroke:#4c8eda style Sync fill:#1a2030,stroke:#3fb950

Operational Modes

Embedded Mode

Direct database access for single-writer configurations. Default for solo agent work. Dolt runs in-process -- no separate server needed.

Dolt Embedded

Server Mode

Connects to dolt sql-server for multi-writer, high-concurrency scenarios. Multiple agents can write simultaneously without conflicts.

SQL Server

Stealth Mode

Local-only usage with bd init --stealth. No repository commits -- suitable for personal task tracking on shared projects without polluting Git history.

Local Only

03

Data Model

The core data model centers on Issues as the atomic unit of work, connected by typed Dependencies that form a directed acyclic graph. Every entity lives in Dolt tables with full SQL queryability and cell-level version control.

Entity Relationship Model

erDiagram ISSUES { string id PK "Hash-based (bd-a1b2)" string title "Work item title" string description "Detailed description" string status "open | in_progress | closed" int priority "P0 (critical) to P4" string assignee "Agent or human" string parent_id FK "Epic parent" timestamp created_at timestamp updated_at } DEPENDENCIES { string id PK string source_id FK "Blocking issue" string target_id FK "Blocked issue" string dep_type "blocks | parent-child | related | discovered-from | conditional-blocks | waits-for" } LABELS { string id PK string issue_id FK string name "Tag or category" } COMMENTS { string id PK string issue_id FK string author string body string thread_id "Threading support" timestamp created_at } EVENTS { string id PK string issue_id FK string event_type "status_change | assignment | etc" string old_value string new_value timestamp created_at } BLOCKED_ISSUES_CACHE { string issue_id PK "Materialized view" } ISSUES ||--o{ DEPENDENCIES : "source" ISSUES ||--o{ DEPENDENCIES : "target" ISSUES ||--o{ LABELS : "has" ISSUES ||--o{ COMMENTS : "has" ISSUES ||--o{ EVENTS : "tracks" ISSUES ||--o| ISSUES : "parent-child"

Dependency Types

Type	Semantics	Blocks Execution?
`blocks`	Sequential work -- B cannot start until A closes	Yes
`parent-child`	Hierarchical containment; parent blocking cascades to children	Yes (cascading)
`conditional-blocks`	B executes only upon A's failure	Conditional
`waits-for`	B waits for all of A's children to complete (fanout gate)	Yes
`relates_to`	Informational link without execution semantics	No
`discovered-from`	Provenance tracking -- discovered during other work	No
`duplicates`	Marks issue as duplicate of another	No
`supersedes`	Replacement relationship	No

04

Dolt Database Engine

Dolt is the heart of Beads' persistence layer -- a version-controlled SQL database that combines MySQL compatibility with Git-like branching, diffing, and merging. Every write automatically creates a Dolt commit, building a complete audit trail.

Dolt Data Flow

flowchart LR subgraph Write["Write Path"] W1["bd create / update / close"] W2["Dolt SQL INSERT/UPDATE"] W3["Auto-Commit
(audit trail)"] end subgraph Read["Read Path"] R1["bd ready / list / show"] R2["SQL Query
(with cache)"] R3["JSON Output"] end subgraph Sync["Sync Path"] S1["bd dolt push"] S2["Dolt Remote
(DoltHub / S3 / GCS)"] S3["bd dolt pull"] end subgraph Resolve["Conflict Resolution"] C1["Cell-Level Merge"] C2["Hash ID = No Collisions"] C3["Automatic Resolution"] end W1 --> W2 --> W3 R1 --> R2 --> R3 W3 --> S1 --> S2 S2 --> S3 --> R2 S3 --> C1 --> C2 --> C3 style Write fill:#1a2838,stroke:#f0a030 style Read fill:#1a2838,stroke:#00add8 style Sync fill:#1a2838,stroke:#3fb950 style Resolve fill:#1a2838,stroke:#bc8cff

Why Dolt?

Traditional databases lose history. Git tracks files but cannot merge structured data. Dolt gives Beads both: SQL queries for fast lookups plus cell-level merge that resolves concurrent writes from multiple agents on different branches without manual intervention. The .beads/dolt/ directory is the entire database -- portable and self-contained.

Performance: Blocked Issues Cache

The blocked_issues_cache table is a materialized view that tracks which issues are currently blocked. Instead of running an expensive recursive CTE on every bd ready call, the cache rebuilds atomically within the same transaction as any blocking-state change.

752ms

Before (Recursive CTE)

29ms

After (Cache Lookup)

25x

Speedup

05

CLI Command Layer

The bd binary is the primary interface for both humans and agents. Built with Go's Cobra framework, every command supports --json output for programmatic consumption by AI agents.

Core Command Tree

graph TD BD["bd"] BD --> READY["ready
Show unblocked tasks"] BD --> CREATE["create
New issue with priority"] BD --> UPDATE["update
Modify issue fields"] BD --> CLOSE["close
Resolve issue"] BD --> SHOW["show
Full issue detail"] BD --> LIST["list
Query issues"] BD --> DEP["dep
Manage dependencies"] BD --> INIT["init
Initialize workspace"] BD --> DOLTCMD["dolt
Database ops"] BD --> SYNC["sync
Push/pull changes"] BD --> MOL["mol
Molecule operations"] BD --> DOCTOR["doctor
Diagnose issues"] BD --> PRIME["prime
Inject agent context"] BD --> SETUP["setup
Agent integration"] DEP --> DEP_ADD["dep add
Create dependency"] DEP --> DEP_RM["dep rm
Remove dependency"] UPDATE --> CLAIM["--claim
Atomic claim + in_progress"] UPDATE --> NOTES["--notes
Add retro notes"] MOL --> POUR["pour
Instantiate template"] MOL --> WISP["wisp
Create ephemeral"] MOL --> BOND["bond
Link molecules"] MOL --> SQUASH["squash
Compact wisps"] style BD fill:#f0a030,stroke:#f0a030,color:#0d1117 style READY fill:#1a2838,stroke:#3fb950 style CREATE fill:#1a2838,stroke:#3fb950 style UPDATE fill:#1a2838,stroke:#3fb950 style CLOSE fill:#1a2838,stroke:#3fb950 style SHOW fill:#1a2838,stroke:#00add8 style LIST fill:#1a2838,stroke:#00add8 style DEP fill:#1a2838,stroke:#bc8cff style MOL fill:#1a2838,stroke:#bc8cff

Essential Commands

# Check what's ready to work on $ bd ready --json # Create a priority-0 task $ bd create "Fix auth regression" -p 0 # Claim a task atomically (assign + set in_progress) $ bd update bd-a3f8 --claim # Add a blocking dependency $ bd dep add bd-c2e1 bd-a3f8 # Close with notes $ bd close bd-a3f8 --reason "Fixed in commit abc123" # Inject agent context (1-2k tokens) $ bd prime

06

Molecules, Wisps, and Protos

Molecules are epics with explicit workflow semantics. They represent executable work graphs where children execute in parallel by default, and only explicit dependencies create sequential ordering. The phase lifecycle (Solid, Liquid, Vapor) controls persistence and synchronization behavior.

Phase Lifecycle

stateDiagram-v2 [*] --> Proto: bd mol create --proto Proto --> Molecule: pour (instantiate) Molecule --> Wisp: wisp (ephemeral) Wisp --> Molecule: squash (compact) Molecule --> [*]: burn (destroy) Wisp --> [*]: burn (destroy) state Proto { [*] --> Frozen Frozen: Reusable template Frozen: Stored in .beads/ Frozen: Synced via Dolt } state Molecule { [*] --> Active Active: Persistent work graph Active: Full audit trail Active: Synced via Dolt } state Wisp { [*] --> Ephemeral Ephemeral: Local-only operations Ephemeral: Never exported Ephemeral: Fast iteration }

Proto (Solid Phase)

Frozen reusable templates. Think of them as "recipes" -- parameterized work graphs you pour into active molecules when needed.

Synced Reusable

Molecule (Liquid Phase)

Active persistent work with full audit trails. Children are parallel by default. Agents find ready children, execute them, close them, and repeat.

Synced Persistent

Wisp (Vapor Phase)

Ephemeral operations that never sync. Perfect for scratch work, experiments, or throwaway subtasks. Squash them back into molecules when done.

Local Only Ephemeral

Bonding: Compound Execution

bd mol bond A B connects separate molecules into compound workflows. Agents can traverse bonded molecules as a unified execution graph, enabling complex multi-phase projects where each molecule maintains its own lifecycle but execution respects cross-molecule dependencies.

07

Adaptive Hash IDs

Sequential IDs (issue #1, #2, #3) collide when multiple agents create issues on different branches simultaneously. Beads solves this with hash-based IDs that adaptively grow in length as the database scales, using the birthday paradox formula to maintain collision probability under a configurable threshold.

Adaptive ID Scaling

graph LR subgraph Small["0-500 Issues"] S1["4-char IDs
bd-a1b2"] S2["~7% collision risk"] end subgraph Medium["501-1,500 Issues"] M1["5-char IDs
bd-a1b2c"] M2["~2% collision risk"] end subgraph Large["1,501+ Issues"] L1["6-char IDs
bd-a1b2c3"] L2["<0.5% collision risk"] end Small --> Medium --> Large subgraph Collision["Collision Resolution"] C1["Try 10 nonces at current length"] C2["Escalate to next length"] C3["30 total attempts across 3 tiers"] end style Small fill:#1a2838,stroke:#3fb950 style Medium fill:#1a2838,stroke:#f0a030 style Large fill:#1a2838,stroke:#f85149 style Collision fill:#1a2233,stroke:#bc8cff

Hierarchical ID System

Issues support hierarchical addressing for epics and subtasks:

# Epic bd-a3f8 # First subtask of epic bd-a3f8.1 # Sub-subtask bd-a3f8.1.1 # Formula: P(collision) = 1 - e^(-n^2 / 2N) # where n = issue count, N = total possible IDs

08

Git Integration

Beads auto-commits issue updates to Git using lightweight worktrees, keeping the developer's working directory untouched. The system supports protected branch workflows, fork-based contributor patterns, and team-based maintainer modes.

Git Workflow Modes

flowchart TB subgraph Maintainer["Maintainer Mode"] MA["bd init --team"] MB["Commits to main
(or beads-sync branch)"] MC["Shared .beads/ in repo"] end subgraph Contributor["Contributor Mode"] CA["bd init --contributor"] CB["Routes to separate repo
(~/.beads-planning)"] CC["Upstream stays clean"] end subgraph Stealth["Stealth Mode"] SA["bd init --stealth"] SB["No Git commits at all"] SC["Local Dolt only"] end subgraph Worktree["Git Worktree Architecture"] WT1[".git/beads-worktrees/"] WT2["Lightweight checkout"] WT3["Same .beads/dolt/ database"] WT4["Auto-commit on write"] WT5["Post-merge hooks
for sync"] end MA --> MB --> MC CA --> CB --> CC SA --> SB --> SC Maintainer --> Worktree Contributor --> Worktree style Maintainer fill:#1a2838,stroke:#3fb950 style Contributor fill:#1a2838,stroke:#00add8 style Stealth fill:#1a2838,stroke:#f0a030 style Worktree fill:#1a2233,stroke:#bc8cff

Protected Branch Support

When repositories enforce branch protection on main, Beads automatically routes commits to a beads-sync branch. Agent workflows remain unchanged -- changes merge back via pull request, preserving code review policies. Configure with bd config set sync.branch beads-sync.

09

Agent Workflow

Beads was designed from the ground up for AI coding agents. The workflow loop is simple: check what's ready, claim a task, do the work, close it. Context injection via bd prime keeps agent overhead to 1-2k tokens versus 10-50k for full MCP tool schemas.

Agent Execution Loop

flowchart TD START["Session Start"] --> PRIME["bd prime
(inject 1-2k tokens context)"] PRIME --> READY["bd ready --json
(find unblocked tasks)"] READY --> PICK{"Tasks available?"} PICK -->|Yes| CLAIM["bd update ID --claim
(atomic assign + in_progress)"] PICK -->|No| CREATE["bd create 'New task' -p 1
(discover new work)"] CREATE --> CLAIM CLAIM --> WORK["Do the work
(code, test, commit)"] WORK --> DISCOVER{"Discovered
new issues?"} DISCOVER -->|Yes| LINK["bd create 'Sub-issue'
bd dep add new parent
(discovered-from link)"] DISCOVER -->|No| CLOSE["bd close ID
--reason 'summary'"] LINK --> CLOSE CLOSE --> COMPACT{"Context
pressure?"} COMPACT -->|Yes| DECAY["Semantic Decay
(summarize old closed tasks)"] COMPACT -->|No| READY DECAY --> READY style START fill:#f0a030,stroke:#f0a030,color:#0d1117 style PRIME fill:#1a2838,stroke:#bc8cff style READY fill:#1a2838,stroke:#3fb950 style CLAIM fill:#1a2838,stroke:#00add8 style WORK fill:#1a2838,stroke:#f0a030 style CLOSE fill:#1a2838,stroke:#3fb950 style DECAY fill:#1a2838,stroke:#f85149

Integration Methods

CLI + Hooks (Recommended)

bd setup claude installs SessionStart and PreCompact hooks that auto-inject context. Only 1-2k tokens overhead. Works with any agent that can run shell commands.

1-2k tokens

MCP Server (Alternative)

The beads-mcp integration exposes bd commands as MCP tools for environments without shell access (Claude Desktop). Higher context overhead from tool schemas.

10-50k tokens

Semantic Memory Decay

Automatically summarizes old closed tasks to save context window. Compacts detailed task histories into concise summaries, preserving essential information while freeing tokens.

Token Efficient

Supported Agents

Agent	Integration	Setup Command
Claude Code	CLI + Hooks (SessionStart, PreCompact)	`bd setup claude`
GitHub Copilot	CLI with JSON output	`bd setup copilot`
Aider	CLI integration	`bd setup aider`
JetBrains Junie	Plugin integration	Via integrations/junie
Custom Agent	MCP Server or CLI --json	`bd prime`

10

Internal Architecture

Under the hood, Beads uses a single-owner goroutine pattern for flush management, debounced writes for performance, and a modular package structure that cleanly separates concerns across 29 internal packages.

FlushManager Architecture

flowchart LR subgraph Channels["Buffered Channels"] DIRTY["markDirtyCh
(buffer: 10)"] TIMER["timerFiredCh
(buffer: 1)"] FLUSH["flushNowCh"] SHUTDOWN["shutdownCh"] end subgraph RunLoop["run() Goroutine
(Single Owner)"] SELECT["select { }"] STATE["isDirty
needsFullExport
debounceTimer"] end subgraph Output["Side Effects"] DOLTW["Dolt Write"] EXPORT["File Export"] GITC["Git Commit"] end DIRTY --> SELECT TIMER --> SELECT FLUSH --> SELECT SHUTDOWN --> SELECT SELECT --> STATE STATE --> DOLTW STATE --> EXPORT STATE --> GITC style Channels fill:#1a2838,stroke:#00add8 style RunLoop fill:#1a2838,stroke:#f0a030 style Output fill:#1a2838,stroke:#3fb950

Single-Owner Pattern

The FlushManager uses Go's channel-based concurrency model. One background goroutine exclusively owns the mutable state (isDirty, debounceTimer). All other goroutines communicate via buffered channels. Timer callbacks send events to timerFiredCh instead of directly modifying state, preventing races. Debounce resets on each mark; flush occurs after the last modification settles.

External Integrations

Jira Import

Bidirectional sync with Jira via internal/jira. Import existing issues, map priorities, and maintain links between Beads and Jira issue IDs.

internal/jira

GitLab Integration

Import and sync with GitLab issue trackers via internal/gitlab. Supports project-level and group-level issue mapping.

internal/gitlab

Linear Integration

Connect with Linear's modern issue tracking. Import issues, teams, and project structures via internal/linear.

internal/linear

11

Codebase Structure

The repository is organized as a standard Go project with cmd/bd as the binary entrypoint and internal/ containing 29 private packages. The codebase also includes integration plugins, an npm distribution package, and comprehensive test suites.

Repository Layout

graph TD ROOT["github.com/steveyegge/beads"] ROOT --> CMD["cmd/bd/
(308 files)"] ROOT --> INTERNAL["internal/
(29 packages)"] ROOT --> INTEGRATIONS["integrations/"] ROOT --> DOCS["docs/"] ROOT --> SCRIPTS["scripts/"] CMD --> CLI_CORE["Core: create, update,
close, list, show, ready"] CMD --> CLI_ADV["Advanced: doctor, dolt,
graph, migrate, federation"] CMD --> CLI_AGENT["Agent: prime, setup,
onboard, config, context"] CMD --> CLI_TEST["Tests: 100+ test files"] INTERNAL --> PKG_CORE["Core: beads, types,
validation, query, formula"] INTERNAL --> PKG_STORAGE["Storage: storage,
lockfile, compact, config"] INTERNAL --> PKG_INTEG["Integration: git, gitlab,
jira, linear, doltserver"] INTERNAL --> PKG_UTIL["Utils: idgen, routing,
timeparsing, templates, ui"] INTERNAL --> PKG_OPS["Ops: audit, debug,
telemetry, hooks, tracker"] INTEGRATIONS --> INT_MCP["beads-mcp
(MCP Server)"] INTEGRATIONS --> INT_CLAUDE["claude-code
(Claude Plugin)"] INTEGRATIONS --> INT_JUNIE["junie
(JetBrains)"] style ROOT fill:#f0a030,stroke:#f0a030,color:#0d1117 style CMD fill:#1a2838,stroke:#00add8 style INTERNAL fill:#1a2838,stroke:#3fb950 style INTEGRATIONS fill:#1a2838,stroke:#bc8cff style DOCS fill:#1a2233,stroke:#484f58 style SCRIPTS fill:#1a2233,stroke:#484f58

Internal Packages

Package	Purpose	Category
`beads`	Main application logic and orchestration	Core
`types`	Shared type definitions (Issue, Dependency, Event)	Core
`query`	SQL query builder for Dolt	Query
`formula`	Formula evaluation for advanced workflows	Core
`molecules`	Molecule/Proto/Wisp lifecycle management	Core
`storage`	Data persistence layer abstraction	Storage
`doltserver`	Dolt database server integration	Storage
`idgen`	Adaptive hash ID generation (birthday paradox)	Core
`git`	Git operations, worktrees, auto-commit	Integration
`routing`	Request routing and middleware	Infra
`compact`	Semantic memory decay / compaction	Memory
`audit`	Audit logging for all mutations	Ops
`telemetry`	Usage metrics and observability	Ops
`hooks`	Git and session hook management	Integration

Distribution Channels

npm

npm install -g @beads/bd -- platform-specific binary via the npm-package/ wrapper.

npm

Homebrew

brew install beads -- macOS and Linux via Homebrew tap.

brew

Go Install

go install github.com/steveyegge/beads/cmd/bd@latest -- direct from source.

go install