How steveyegge/beads works
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: storage.go Storage contracts · close.go Close issues · main.go bd CLI · create.go Create issues
Components 22
CLI workflow
- bd CLI
cmd/bd/main.go - Create issues
cmd/bd/create.go - Dependency graph
cmd/bd/dep.go - Ready work
cmd/bd/ready.go - Claim work
- Close issues
cmd/bd/close.go - Agent memory
cmd/bd/memory.go - Messages
cmd/bd/mail.go - Memory compaction
cmd/bd/compact.go
Storage and API
- Storage contracts
internal/storage/storage.go - Dolt database
internal/storage/dolt - Storage decorators
cmd/bd/storage_chain.go - HTTP API
internal/httpapi/server.go - API routes
internal/httpapi/routes.go - Storage telemetry
internal/telemetry/storage.go
Agent interfaces
- MCP server
integrations/beads-mcp/src/beads_mcp/server.py - MCP tools
integrations/beads-mcp/src/beads_mcp/tools.py - CLI client
integrations/beads-mcp/src/beads_mcp/bd_client.py
Sync and extensions
- Tracker synchronization
internal/tracker/engine.go - Linear integration
internal/linear/client.go - Dolt remotes
Other components
- User or agent
Connections 29
- 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
cmd/bd/storage_chain.go - Storage decorators → Storage contracts: decorates store
cmd/bd/storage_chain.go - Storage contracts → Dolt database: implemented by
internal/storage/storage.go - HTTP API → API routes: registers routes
internal/httpapi/routes.go - User or agent → HTTP API: calls API
- MCP server → MCP tools: exposes tools
integrations/beads-mcp/src/beads_mcp/server.py - MCP tools → CLI client: uses client
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