# steveyegge/beads architecture

> Architecture diagram of the GitHub repository steveyegge/beads, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steveyegge/beads
- Repository: https://github.com/steveyegge/beads

## Overview

Beads is a distributed graph issue tracker and persistent memory for coding agents. The primary workflow creates issues, links dependencies, finds unblocked work, claims it, and closes it so newly unblocked work can become ready. The CLI is the main user entry point; storage is backed by Dolt, with an HTTP API and MCP server as additional interfaces. Other major capabilities include memory, messaging, compaction, remote sync, and external tracker integrations. Source excerpts show selected wiring; README-documented relationships are cited where implementation wiring was not sampled.

Main entry points: [`internal/storage/storage.go`](https://github.com/steveyegge/beads/blob/main/internal/storage/storage.go) (Storage contracts), [`cmd/bd/close.go`](https://github.com/steveyegge/beads/blob/main/cmd/bd/close.go) (Close issues), [`cmd/bd/main.go`](https://github.com/steveyegge/beads/blob/main/cmd/bd/main.go) (bd CLI), [`cmd/bd/create.go`](https://github.com/steveyegge/beads/blob/main/cmd/bd/create.go) (Create issues)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["bd CLI<br/>[main.go]"]
  node_create["Create issues<br/>[create.go]"]
  node_dependencies["Dependency graph<br/>[dep.go]"]
  node_ready["Ready work<br/>[ready.go]"]
  node_claim["Claim work"]
  node_close["Close issues<br/>[close.go]"]
  node_memory["Agent memory<br/>[memory.go]"]
  node_messaging["Messages<br/>[mail.go]"]
  node_compaction["Memory compaction<br/>[compact.go]"]
end

subgraph group_storage["Storage and API"]
  node_storage_interfaces["Storage contracts<br/>[storage.go]"]
  node_dolt[("Dolt database")]
  node_storage_chain["Storage decorators<br/>[storage_chain.go]"]
  node_http_api["HTTP API<br/>[server.go]"]
  node_http_routes["API routes<br/>[routes.go]"]
  node_telemetry["Storage telemetry<br/>[storage.go]"]
end

subgraph group_agent["Agent interfaces"]
  node_mcp["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools<br/>[tools.py]"]
  node_mcp_client["CLI client<br/>[bd_client.py]"]
end

subgraph group_extensions["Sync and extensions"]
  node_tracker_sync["Tracker synchronization<br/>[engine.go]"]
  node_linear["Linear integration<br/>[client.go]"]
  node_dolt_remote[("Dolt remotes")]
end

node_operator(("User or agent"))

node_operator -->|"runs"| node_cli
node_cli -.->|"routes commands"| node_create
node_operator -->|"creates issues"| node_create
node_operator -->|"links issues"| node_dependencies
node_operator -->|"lists ready"| node_ready
node_operator -->|"claims work"| node_claim
node_operator -->|"closes work"| node_close
node_close -->|"releases blockers"| node_ready
node_create -.->|"persists issues"| node_storage_interfaces
node_dependencies -.->|"stores links"| node_storage_interfaces
node_ready -.->|"queries work"| node_storage_interfaces
node_claim -.->|"claims atomically"| node_storage_interfaces
node_close -.->|"updates status"| node_storage_interfaces
node_storage_chain -->|"wraps storage"| node_telemetry
node_storage_chain -->|"decorates store"| node_storage_interfaces
node_storage_interfaces -->|"implemented by"| node_dolt
node_http_api -->|"registers routes"| node_http_routes
node_operator -.->|"calls API"| node_http_api
node_mcp -->|"exposes tools"| node_mcp_tools
node_mcp_tools -->|"uses client"| node_mcp_client
node_mcp_client -.->|"invokes CLI"| node_cli
node_operator -.->|"uses MCP"| node_mcp
node_operator -->|"stores memories"| node_memory
node_memory -.->|"persists memories"| node_storage_interfaces
node_operator -.->|"sends messages"| node_messaging
node_operator -->|"compacts history"| node_compaction
node_operator -.->|"synchronizes trackers"| node_tracker_sync
node_tracker_sync -.->|"uses integration"| node_linear
node_operator -->|"pushes or pulls"| node_dolt_remote

click node_cli "https://github.com/steveyegge/beads/blob/main/cmd/bd/main.go"
click node_create "https://github.com/steveyegge/beads/blob/main/cmd/bd/create.go"
click node_dependencies "https://github.com/steveyegge/beads/blob/main/cmd/bd/dep.go"
click node_ready "https://github.com/steveyegge/beads/blob/main/cmd/bd/ready.go"
click node_close "https://github.com/steveyegge/beads/blob/main/cmd/bd/close.go"
click node_memory "https://github.com/steveyegge/beads/blob/main/cmd/bd/memory.go"
click node_messaging "https://github.com/steveyegge/beads/blob/main/cmd/bd/mail.go"
click node_compaction "https://github.com/steveyegge/beads/blob/main/cmd/bd/compact.go"
click node_storage_interfaces "https://github.com/steveyegge/beads/blob/main/internal/storage/storage.go"
click node_dolt "https://github.com/steveyegge/beads/tree/main/internal/storage/dolt"
click node_storage_chain "https://github.com/steveyegge/beads/blob/main/cmd/bd/storage_chain.go"
click node_http_api "https://github.com/steveyegge/beads/blob/main/internal/httpapi/server.go"
click node_http_routes "https://github.com/steveyegge/beads/blob/main/internal/httpapi/routes.go"
click node_telemetry "https://github.com/steveyegge/beads/blob/main/internal/telemetry/storage.go"
click node_mcp "https://github.com/steveyegge/beads/blob/main/integrations/beads-mcp/src/beads_mcp/server.py"
click node_mcp_tools "https://github.com/steveyegge/beads/blob/main/integrations/beads-mcp/src/beads_mcp/tools.py"
click node_mcp_client "https://github.com/steveyegge/beads/blob/main/integrations/beads-mcp/src/beads_mcp/bd_client.py"
click node_tracker_sync "https://github.com/steveyegge/beads/blob/main/internal/tracker/engine.go"
click node_linear "https://github.com/steveyegge/beads/blob/main/internal/linear/client.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_create,node_dependencies,node_ready,node_claim,node_close,node_memory,node_messaging,node_compaction,node_operator toneBlue
class node_storage_interfaces,node_dolt,node_storage_chain,node_http_api,node_http_routes,node_telemetry toneAmber
class node_mcp,node_mcp_tools,node_mcp_client toneMint
class node_tracker_sync,node_linear,node_dolt_remote toneRose
```

## Components

### CLI workflow

- [bd CLI](https://github.com/steveyegge/beads/blob/main/cmd/bd/main.go): `cmd/bd/main.go`
- [Create issues](https://github.com/steveyegge/beads/blob/main/cmd/bd/create.go): `cmd/bd/create.go`
- [Dependency graph](https://github.com/steveyegge/beads/blob/main/cmd/bd/dep.go): `cmd/bd/dep.go`
- [Ready work](https://github.com/steveyegge/beads/blob/main/cmd/bd/ready.go): `cmd/bd/ready.go`
- **Claim work**
- [Close issues](https://github.com/steveyegge/beads/blob/main/cmd/bd/close.go): `cmd/bd/close.go`
- [Agent memory](https://github.com/steveyegge/beads/blob/main/cmd/bd/memory.go): `cmd/bd/memory.go`
- [Messages](https://github.com/steveyegge/beads/blob/main/cmd/bd/mail.go): `cmd/bd/mail.go`
- [Memory compaction](https://github.com/steveyegge/beads/blob/main/cmd/bd/compact.go): `cmd/bd/compact.go`

### Storage and API

- [Storage contracts](https://github.com/steveyegge/beads/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Dolt database](https://github.com/steveyegge/beads/tree/main/internal/storage/dolt): `internal/storage/dolt`
- [Storage decorators](https://github.com/steveyegge/beads/blob/main/cmd/bd/storage_chain.go): `cmd/bd/storage_chain.go`
- [HTTP API](https://github.com/steveyegge/beads/blob/main/internal/httpapi/server.go): `internal/httpapi/server.go`
- [API routes](https://github.com/steveyegge/beads/blob/main/internal/httpapi/routes.go): `internal/httpapi/routes.go`
- [Storage telemetry](https://github.com/steveyegge/beads/blob/main/internal/telemetry/storage.go): `internal/telemetry/storage.go`

### Agent interfaces

- [MCP server](https://github.com/steveyegge/beads/blob/main/integrations/beads-mcp/src/beads_mcp/server.py): `integrations/beads-mcp/src/beads_mcp/server.py`
- [MCP tools](https://github.com/steveyegge/beads/blob/main/integrations/beads-mcp/src/beads_mcp/tools.py): `integrations/beads-mcp/src/beads_mcp/tools.py`
- [CLI client](https://github.com/steveyegge/beads/blob/main/integrations/beads-mcp/src/beads_mcp/bd_client.py): `integrations/beads-mcp/src/beads_mcp/bd_client.py`

### Sync and extensions

- [Tracker synchronization](https://github.com/steveyegge/beads/blob/main/internal/tracker/engine.go): `internal/tracker/engine.go`
- [Linear integration](https://github.com/steveyegge/beads/blob/main/internal/linear/client.go): `internal/linear/client.go`
- **Dolt remotes**

### Other components

- **User or agent**

## Connections

- User or agent → bd CLI: runs
- bd CLI → Create issues: routes commands
- User or agent → Create issues: creates issues
- User or agent → Dependency graph: links issues
- User or agent → Ready work: lists ready
- User or agent → Claim work: claims work
- User or agent → Close issues: closes work
- Close issues → Ready work: releases blockers
- Create issues → Storage contracts: persists issues
- Dependency graph → Storage contracts: stores links
- Ready work → Storage contracts: queries work
- Claim work → Storage contracts: claims atomically
- Close issues → Storage contracts: updates status
- Storage decorators → Storage telemetry: wraps storage (evidence: `cmd/bd/storage_chain.go`)
- Storage decorators → Storage contracts: decorates store (evidence: `cmd/bd/storage_chain.go`)
- Storage contracts → Dolt database: implemented by (evidence: `internal/storage/storage.go`)
- HTTP API → API routes: registers routes (evidence: `internal/httpapi/routes.go`)
- User or agent → HTTP API: calls API
- MCP server → MCP tools: exposes tools (evidence: `integrations/beads-mcp/src/beads_mcp/server.py`)
- MCP tools → CLI client: uses client (evidence: `integrations/beads-mcp/src/beads_mcp/tools.py`)
- CLI client → bd CLI: invokes CLI
- User or agent → MCP server: uses MCP
- User or agent → Agent memory: stores memories
- Agent memory → Storage contracts: persists memories
- User or agent → Messages: sends messages
- User or agent → Memory compaction: compacts history
- User or agent → Tracker synchronization: synchronizes trackers
- Tracker synchronization → Linear integration: uses integration
- User or agent → Dolt remotes: pushes or pulls
