# gastownhall/beads architecture

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

- Interactive diagram: https://gitdiagram.com/gastownhall/beads
- Repository: https://github.com/gastownhall/beads
- Video tour (about a minute): https://gitdiagram.com/gastownhall/beads/video

## Overview

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: [`internal/storage`](https://github.com/gastownhall/beads/tree/main/internal/storage) (Storage API), [`cmd/bd`](https://github.com/gastownhall/beads/tree/main/cmd/bd) (CLI commands), [`internal/storage/issueops`](https://github.com/gastownhall/beads/tree/main/internal/storage/issueops) (Issue ops), [`internal/storage/versioncontrolops`](https://github.com/gastownhall/beads/tree/main/internal/storage/versioncontrolops) (Version control ops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_cmd_main["bd main<br/>cli entrypoint<br/>[main.go]"]
  node_cmd_commands["CLI commands<br/>command handlers"]
  node_cmd_doctor["Doctor suite<br/>diagnostics"]
  node_cmd_setup["Agent setup<br/>agent bootstrap"]
end

subgraph group_core["Core model"]
  node_core_types["Domain types<br/>issue model"]
  node_core_validation["Validation<br/>constraints"]
  node_core_query["Query engine<br/>parser/evaluator"]
  node_core_formula["Formulas<br/>workflow rules"]
  node_core_utils["IDs and paths<br/>helpers"]
  node_routing["Repo routing<br/>repo identity"]
  node_beads_ctx["Beads context<br/>repo discovery"]
end

subgraph group_storage["Storage layer"]
  node_storage_api[("Storage API<br/>storage facade")]
  node_issueops["Issue ops<br/>issue service"]
  node_vcops["Version control ops<br/>state lifecycle"]
  node_embedded[("Embedded Dolt<br/>local backend")]
  node_dolt_backend[("Dolt backend<br/>server backend")]
end

subgraph group_integrations["Integrations"]
  node_tracker["Tracker layer<br/>tracker facade"]
  node_tracker_adapters["Tracker adapters<br/>external systems"]
  node_mcp_plugin["Agent plugins<br/>agent surfaces"]
  node_templates["Templates<br/>prompt assets"]
end

subgraph group_ops["Ops and docs"]
  node_hooks_telemetry["Hooks and telemetry<br/>ops layer"]
  node_docs_release["Docs and release<br/>delivery<br/>[ARCHITECTURE.md]"]
end

node_cmd_main -->|"dispatches to"| node_cmd_commands
node_cmd_commands -->|"resolves"| node_routing
node_cmd_commands -->|"uses"| node_storage_api
node_cmd_commands -->|"renders"| node_core_types
node_cmd_commands -->|"filters"| node_core_query
node_cmd_commands -->|"evaluates"| node_core_formula
node_cmd_doctor -->|"checks"| node_hooks_telemetry
node_cmd_setup -->|"boots"| node_templates
node_routing -->|"discovers"| node_beads_ctx
node_beads_ctx -->|"locates"| node_storage_api
node_storage_api -->|"delegates to"| node_issueops
node_storage_api -->|"delegates to"| node_vcops
node_storage_api -->|"backs onto"| node_embedded
node_storage_api -->|"backs onto"| node_dolt_backend
node_issueops -->|"mutates"| node_core_types
node_issueops -->|"validates"| node_core_validation
node_issueops -->|"queries"| node_core_query
node_issueops -->|"syncs with"| node_tracker
node_vcops -->|"manages"| node_embedded
node_vcops -->|"manages"| node_dolt_backend
node_tracker -->|"implemented by"| node_tracker_adapters
node_mcp_plugin -->|"calls"| node_storage_api
node_mcp_plugin -->|"integrates"| node_tracker
node_hooks_telemetry -->|"observes"| node_storage_api
node_docs_release -->|"documents"| node_cmd_main
node_docs_release -->|"packages"| node_mcp_plugin

click node_cmd_main "https://github.com/gastownhall/beads/blob/main/cmd/bd/main.go"
click node_cmd_commands "https://github.com/gastownhall/beads/tree/main/cmd/bd"
click node_cmd_doctor "https://github.com/gastownhall/beads/tree/main/cmd/bd/doctor"
click node_cmd_setup "https://github.com/gastownhall/beads/tree/main/cmd/bd/setup"
click node_core_types "https://github.com/gastownhall/beads/tree/main/internal/types"
click node_core_validation "https://github.com/gastownhall/beads/tree/main/internal/validation"
click node_core_query "https://github.com/gastownhall/beads/tree/main/internal/query"
click node_core_formula "https://github.com/gastownhall/beads/tree/main/internal/formula"
click node_core_utils "https://github.com/gastownhall/beads/tree/main/internal/utils"
click node_routing "https://github.com/gastownhall/beads/tree/main/internal/routing"
click node_beads_ctx "https://github.com/gastownhall/beads/tree/main/internal/beads"
click node_storage_api "https://github.com/gastownhall/beads/tree/main/internal/storage"
click node_issueops "https://github.com/gastownhall/beads/tree/main/internal/storage/issueops"
click node_vcops "https://github.com/gastownhall/beads/tree/main/internal/storage/versioncontrolops"
click node_embedded "https://github.com/gastownhall/beads/tree/main/internal/storage/embeddeddolt"
click node_dolt_backend "https://github.com/gastownhall/beads/tree/main/internal/storage/dolt"
click node_tracker "https://github.com/gastownhall/beads/tree/main/internal/tracker"
click node_tracker_adapters "https://github.com/gastownhall/beads/tree/main/internal/github"
click node_mcp_plugin "https://github.com/gastownhall/beads/tree/main/integrations/beads-mcp"
click node_templates "https://github.com/gastownhall/beads/tree/main/internal/templates"
click node_hooks_telemetry "https://github.com/gastownhall/beads/tree/main/internal/hooks"
click node_docs_release "https://github.com/gastownhall/beads/blob/main/docs/ARCHITECTURE.md"

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_cmd_main,node_cmd_commands,node_cmd_doctor,node_cmd_setup toneBlue
class node_core_types,node_core_validation,node_core_query,node_core_formula,node_core_utils,node_routing,node_beads_ctx toneAmber
class node_storage_api,node_issueops,node_vcops,node_embedded,node_dolt_backend toneMint
class node_tracker,node_tracker_adapters,node_mcp_plugin,node_templates toneRose
class node_hooks_telemetry,node_docs_release toneIndigo
```

## Components

### CLI runtime

User-facing command entrypoints and command handlers.

- [bd main](https://github.com/gastownhall/beads/blob/main/cmd/bd/main.go): cli entrypoint · Command entrypoint that dispatches into the bd CLI surface. · `cmd/bd/main.go`
- [CLI commands](https://github.com/gastownhall/beads/tree/main/cmd/bd): command handlers · Main command handlers for create, update, list, sync, doctor, and related actions. · `cmd/bd`
- [Doctor suite](https://github.com/gastownhall/beads/tree/main/cmd/bd/doctor): diagnostics · Health checks, repair flows, and environment validation for repositories and installs. · `cmd/bd/doctor`
- [Agent setup](https://github.com/gastownhall/beads/tree/main/cmd/bd/setup): agent bootstrap · 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](https://github.com/gastownhall/beads/tree/main/internal/types): issue model · Core issue, wisp, dependency, label, comment, and event types. · `internal/types`
- [Validation](https://github.com/gastownhall/beads/tree/main/internal/validation): constraints · Issue and template validation rules. · `internal/validation`
- [Query engine](https://github.com/gastownhall/beads/tree/main/internal/query): parser/evaluator · Query parsing and evaluation for filtering issues and workflows. · `internal/query`
- [Formulas](https://github.com/gastownhall/beads/tree/main/internal/formula): workflow rules · Workflow and gate formula parsing plus execution helpers. · `internal/formula`
- [IDs and paths](https://github.com/gastownhall/beads/tree/main/internal/utils): helpers · Utility helpers for IDs, path handling, and related primitives. · `internal/utils`
- [Repo routing](https://github.com/gastownhall/beads/tree/main/internal/routing): repo identity · Finds the right beads repo, workspace, and project context. · `internal/routing`
- [Beads context](https://github.com/gastownhall/beads/tree/main/internal/beads): repo discovery · Working-copy discovery, repository context, and database location resolution. · `internal/beads`

### Storage layer

Persistent issue graph, issue ops, and version-control workflows.

- [Storage API](https://github.com/gastownhall/beads/tree/main/internal/storage): storage facade · Top-level storage abstraction used by CLI and services. · `internal/storage`
- [Issue ops](https://github.com/gastownhall/beads/tree/main/internal/storage/issueops): issue service · Create, update, close, dependency, search, stale, ready, and compaction operations. · `internal/storage/issueops`
- [Version control ops](https://github.com/gastownhall/beads/tree/main/internal/storage/versioncontrolops): state lifecycle · Clone, branch, commit, compact, gc, backup, and flatten flows for the issue database. · `internal/storage/versioncontrolops`
- [Embedded Dolt](https://github.com/gastownhall/beads/tree/main/internal/storage/embeddeddolt): local backend · In-process local backend with file locking and embedded SQL schema. · `internal/storage/embeddeddolt`
- [Dolt backend](https://github.com/gastownhall/beads/tree/main/internal/storage/dolt): server 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](https://github.com/gastownhall/beads/tree/main/internal/tracker): tracker facade · Common abstraction for external issue tracker synchronization. · `internal/tracker`
- [Tracker adapters](https://github.com/gastownhall/beads/tree/main/internal/github): external systems · Concrete adapters for GitHub, GitLab, Jira, Linear, Notion, and Azure DevOps. · `internal/github`
- [Agent plugins](https://github.com/gastownhall/beads/tree/main/integrations/beads-mcp): agent surfaces · Claude plugin, Claude Code, Junie, and MCP server integration surfaces. · `integrations/beads-mcp`
- [Templates](https://github.com/gastownhall/beads/tree/main/internal/templates): prompt assets · 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](https://github.com/gastownhall/beads/tree/main/internal/hooks): ops layer · Git hooks, lockfiles, and telemetry for reliability and diagnostics. · `internal/hooks`
- [Docs and release](https://github.com/gastownhall/beads/blob/main/docs/ARCHITECTURE.md): delivery · Documentation site, release automation, packaging, and scripting. · `docs/ARCHITECTURE.md`

## Connections

- 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.
