How gastownhall/beads works
1. What this repo is
Beads is a Go-based CLI and task database for AI-agent workflows. The core product is the bd command, which manipulates a persistent issue graph stored in Dolt, with optional sync/integration layers for Git and external trackers.
2. Primary runtime boundary
The executable entrypoint lives in cmd/bd/main.go and fans out into many command handlers under cmd/bd/*.go. Those commands are the user-facing boundary: parse flags, resolve repo/context, call storage/services, and render CLI or JSON output.
3. Core domain model
The repository models tasks, dependencies, comments, labels, events, and message-like issues (“wisps”/threads). The domain types and validation are split across internal/types, internal/validation, internal/molecules, internal/formula, and internal/query, with internal/utils providing ID and path helpers.
4. Storage is the central subsystem
Most business logic ultimately goes through internal/storage. That layer is the abstraction over the persistent issue graph and supports two backends:
- internal/storage/embeddeddolt for in-process, file-locked local use
- internal/storage/dolt for external dolt sql-server usage and multi-writer workflows
Both backends expose the same issue/version-control operations to higher layers.
5. Database and migration shape
The embedded backend has a SQL schema and migration chain under internal/storage/embeddeddolt/schema and internal/storage/dolt/migrations. This is where the graph data, metadata, compaction snapshots, routing tables, federation peers, and counters are persisted and evolved over time.
6. Issue operations are a separate service layer
internal/storage/issueops contains the concrete create/update/close/dep/search/ready/stale/compaction logic. It sits between the CLI and the storage backends, so most commands map to one or more issue operations rather than speaking to the database directly.
7. Version-control and repo lifecycle
Beads treats the issue database like versioned state. internal/storage/versioncontrolops and related version_control.go files handle clone/branch/commit/compact/gc/backup flows. This is how Beads supports branching behavior, snapshots, restore, and backup/migration between embedded and server modes.
8. Repo discovery, routing, and identity
internal/beads, internal/routing, internal/config, and internal/git manage “where is the Beads database for this working copy?” and “which repo/project should this task belong to?” This is the boundary that lets Beads work in normal git repos, contributor forks, monorepos, and even git-free setups via BEADS_DIR.
9. External tracker integrations
internal/tracker is the abstraction over third-party issue systems, with concrete adapters in internal/github, internal/gitlab, internal/jira, internal/linear, internal/notion, and internal/ado. These adapters map Beads concepts to external tracker objects so tasks can be imported, synchronized, or linked across systems.
10. AI-agent integrations and plugin ecosystem
There are two integration surfaces for agents:
- claude-plugin/ and integrations/claude-code, integrations/junie, examples/* for command/skill-based workflows
- integrations/beads-mcp, a Python MCP server that exposes Beads as tools to agent runtimes
The repo also includes template generation under internal/templates and examples/ to bootstrap agent-specific workflows and prompts.
11. Operational support: hooks, telemetry, and diagnostics
Git hooks, lockfiles, and runtime health checks are spread across internal/hooks, internal/lockfile, internal/telemetry, and the large cmd/bd/doctor* suite. This support layer detects corruption, permissions issues, stale state, and installation problems, then offers repair/fix paths.
12. Docs, website, and release pipeline
The docs/ tree and website/ Docusaurus site describe architecture, workflows, and CLI behavior. Release and packaging are handled through .github/workflows, .goreleaser.yml, npm-package/, winget/, and scripts under scripts/, reflecting that the repo ships as a Go CLI plus auxiliary package distributions and docs.
Main entry points: storage Storage API · bd CLI commands · issueops Issue ops · versioncontrolops Version control ops
Components 22
CLI runtime
User-facing command entrypoints and command handlers.
- bd main · Command entrypoint that dispatches into the bd CLI surface.
cmd/bd/main.go - CLI commands · Main command handlers for create, update, list, sync, doctor, and related actions.
cmd/bd - Doctor suite · Health checks, repair flows, and environment validation for repositories and installs.
cmd/bd/doctor - Agent setup · Setup commands and templates for Claude, Junie, Codex, Cursor, and other agent runtimes.
cmd/bd/setup
Core model
Domain types, parsing, validation, and query logic.
- Domain types · Core issue, wisp, dependency, label, comment, and event types.
internal/types - Validation · Issue and template validation rules.
internal/validation - Query engine · Query parsing and evaluation for filtering issues and workflows.
internal/query - Formulas · Workflow and gate formula parsing plus execution helpers.
internal/formula - IDs and paths · Utility helpers for IDs, path handling, and related primitives.
internal/utils - Repo routing · Finds the right beads repo, workspace, and project context.
internal/routing - Beads context · Working-copy discovery, repository context, and database location resolution.
internal/beads
Storage layer
Persistent issue graph, issue ops, and version-control workflows.
- Storage API · Top-level storage abstraction used by CLI and services.
internal/storage - Issue ops · Create, update, close, dependency, search, stale, ready, and compaction operations.
internal/storage/issueops - Version control ops · Clone, branch, commit, compact, gc, backup, and flatten flows for the issue database.
internal/storage/versioncontrolops - Embedded Dolt · In-process local backend with file locking and embedded SQL schema.
internal/storage/embeddeddolt - Dolt backend · External Dolt SQL-server backend for multi-writer and shared workflows.
internal/storage/dolt
Integrations
External trackers, agent surfaces, and plugin adapters.
- Tracker layer · Common abstraction for external issue tracker synchronization.
internal/tracker - Tracker adapters · Concrete adapters for GitHub, GitLab, Jira, Linear, Notion, and Azure DevOps.
internal/github - Agent plugins · Claude plugin, Claude Code, Junie, and MCP server integration surfaces.
integrations/beads-mcp - Templates · Agent and workflow templates used to bootstrap integrations and prompts.
internal/templates
Ops and docs
Diagnostics, hooks, docs, scripts, and release packaging.
- Hooks and telemetry · Git hooks, lockfiles, and telemetry for reliability and diagnostics.
internal/hooks - Docs and release · Documentation site, release automation, packaging, and scripting.
docs/ARCHITECTURE.md
Connections 26
- bd main → CLI commands: dispatches to · Main CLI entrypoint fans out into command handlers.
- CLI commands → Repo routing: resolves · Commands resolve repository and workspace context before operating.
- CLI commands → Storage API: uses · Commands delegate persistent operations to storage services.
- CLI commands → Domain types: renders · Commands format issue and wisp domain objects for output.
- CLI commands → Query engine: filters · List/search/status flows rely on query evaluation.
- CLI commands → Formulas: evaluates · Workflow and gate commands use formula logic.
- Doctor suite → Hooks and telemetry: checks · Doctor validates hooks, locks, health, and runtime diagnostics.
- Agent setup → Templates: boots · Setup commands install or render agent workflow templates.
- Repo routing → Beads context: discovers · Routing depends on repository and workspace discovery.
- Beads context → Storage API: locates · Context resolution determines which database instance to open.
- Storage API → Issue ops: delegates to · Business actions are implemented in the issue operations layer.
- Storage API → Version control ops: delegates to · Versioned state flows go through version-control operations.
- Storage API → Embedded Dolt: backs onto · Local use is served by the embedded Dolt backend.
- Storage API → Dolt backend: backs onto · Server and multi-writer use is served by the Dolt backend.
- Issue ops → Domain types: mutates · Issue ops create and update domain entities.
- Issue ops → Validation: validates · Operations enforce issue and template constraints.
- Issue ops → Query engine: queries · Search, readiness, and stale flows use query logic.
- Issue ops → Tracker layer: syncs with · Issue ops bridge to external tracker state when needed.
- Version control ops → Embedded Dolt: manages · Branching, compaction, and backup coordinate embedded state.
- Version control ops → Dolt backend: manages · Lifecycle flows also apply to external Dolt-backed repositories.
- Tracker layer → Tracker adapters: implemented by · Tracker abstraction is realized by provider-specific adapters.
- Agent plugins → Storage API: calls · Agent tooling surfaces call into the same storage-backed API.
- Agent plugins → Tracker layer: integrates · Agent workflows can link or sync with external trackers.
- Hooks and telemetry → Storage API: observes · Operational checks read storage state and integrity signals.
- Docs and release → bd main: documents · Docs and packaging describe the CLI and its workflows.
- Docs and release → Agent plugins: packages · Docs and release assets cover plugin and integration distribution.