DOCSEARCHbyAlgolia
Submit Docs

Beads (bd) Distributed Issue Tracker

repository·main·Indexed 12 days ago

https://github.com/gastownhall/beads

A distributed, graph-based issue tracker powered by Dolt, designed specifically for AI agents to provide persistent, version-controlled memory and dependency tracking. It includes a `bd` CLI, a Go API for issue management, and integrations such as a Model Context Protocol (MCP) server for Claude Desktop.

Tokens
328.4K
Snippets
1.1K
Records
1.5K
Agent score
97%

What's inside Beads

  1. Overview of the `bd serve` v0 HTTP surface

    main

    The bd serve command provides an HTTP interface for the Beads issue tracker, designed for automation clients and orchestrators. It avoids the overhead of spawning a new bd subprocess for every call and provides a structured wire contract instead of parsing stdout text.

    Key Characteristics

    • Base Path: All operations reside under /v0 (except liveness checks).
    • Liveness: GET /healthz and GET /v0/beads/context are available for health checks and identity. These do not touch the database and carry bypassSemaphore.
    • Capabilities: Clients should probe GET /v0/beads/context to discover supported operations via the capabilities field. This list is derived directly from registered handlers to ensure accuracy.
    • Data Consistency: Response bodies marshal internal/types values directly. This means the HTTP contract is strictly tied to the internal types; renaming or removing fields in the core types will break the API.
    • Write Posture: Writes use either custom methods (e.g., :claim, :close, :add) or standard CRUD methods (PATCH, POST, DELETE). All writes follow a specific posture: the actor is caller-asserted provenance (not authenticated identity), hooks do not fire, and auto-commit machinery does not run. Durability is guaranteed by a single storage commit per request within the role's transaction.

  2. Understand the status of Pluggable Storage Backends

    main

    The proposal for pluggable storage backends (including PostgreSQL and MySQL) was superseded on 2026-07-16.

    Current Supported Backends:

    • Dolt (Default and richest backend)
    • Dolt server (Uses MySQL wire protocol)
    • SQLite (Fast, zero-dependency, pure-Go single-writer store)

    Direct PostgreSQL and MySQL adapters are no longer supported to keep Beads simple and resource-efficient. For the current design, refer to docs/architecture/storage-backends.md.

  3. Identify available documentation and integration guides

    main

    The engdocs/DOC_INVENTORY.md file serves as a disposition inventory for the project's documentation. It categorizes files into 'Active Docs' (canonical sources of truth) and 'Staged Docs' (files slated for removal).

    When looking for specific guidance, use the following mapping based on the inventory:

    • Installation & Setup: Refer to INSTALLING.md and SETUP.md.
    • Core Architecture: Refer to ARCHITECTURE.md and DOLT.md (for Dolt backend specifics).
    • CLI Reference: Use CLI_REFERENCE.md (which is generated from live help output).
    • Integrations:
      • AI Agents: AIDER_INTEGRATION.md, CLAUDE_INTEGRATION.md, COPILOT_INTEGRATION.md.
      • Git: GIT_INTEGRATION.md.
    • Advanced Workflows: ADVANCED.md, MOLECULES.md, and WORKTREES.md.
    • Troubleshooting & Recovery: TROUBLESHOOTING.md, RECOVERY.md, and SERVE_RUNBOOK.md (for bd serve).
    • Data & Schema: JSON_SCHEMA.md and METADATA.md.

  4. Integrate with Beads using community-built UIs and extensions

    main

    Beads supports a wide ecosystem of community-built tools including Terminal UIs, Web UIs, Editor Extensions, and Native Apps.

    Important Compatibility Note: Beads uses a Dolt SQL database for storage. To ensure compatibility with current versions, tools should access data via the bd CLI (e.g., using bd list --json). Tools that attempt to read the legacy .beads/issues.jsonl format directly are not compatible with current versions of Beads. Most modern tools route writes through the bd CLI to preserve hooks, history, and validation logic.

  5. Explore Beads integration examples

    main

    The examples/ directory provides several reference implementations for integrating bd into different environments:

    Agent Integration

    • Python Agent: A simple Python implementation that discovers and completes tasks.
    • Bash Agent: A shell script demonstrating the full agent lifecycle.
    • Startup Hooks: Scripts for automatic bd upgrade detection during session startup.
    • Claude Desktop MCP: An MCP (Model Context Protocol) server for integrating bd with Claude Desktop.

    Tools & Utilities

    • Monitor Web UI: A standalone web interface for real-time visualization and monitoring of issues.
    • Git Hooks: Pre-configured hooks for automatic Dolt synchronization.

    Workflow Patterns

    • Contributor Workflow: Setup for OSS contributors using separate planning repositories.
    • Team Workflow: Patterns for collaboration using shared repositories.
    • Multi-phase Development: Organizing large projects into phases (planning, MVP, iteration, polish).
    • Multiple Personas: Separating roles such as Architect, Implementer, and Reviewer.
    • Protected Branch: Workflow designed for team collaboration using protected branches.

  6. Use the bd CLI to manage issues

    main

    The bd command-line tool is the primary interface for the Beads issue tracker. It allows users to create, query, manage, and synchronize issues across distributed systems. The CLI supports two operational modes:

    1. Server Mode: The CLI communicates with a Dolt server via RPC, delegating operations to the server.
    2. Embedded Mode: The CLI performs local database operations directly.

    Most commands transparently handle the connection state using a PersistentPreRun hook, meaning you can use the same commands regardless of whether you are connected to a remote server or working locally.

  7. What is beads and when to use it?

    main

    Beads (bd) is a lightweight, Dolt-backed issue tracker designed for AI coding agents. It provides dependency-aware task management with built-in sync across machines, allowing agents and humans to collaborate on the same task graph.

    When to use beads vs. other tools

    • Use beads when you need offline-first task memory, version-controlled task state, graph-based dependencies (e.g., blocks, discovered-from), and agent-native APIs (JSON-first design and MCP support).
    • Use GitHub Issues or Jira for human teams requiring web UIs, cross-repo dashboards, and standard third-party integrations.
    • Use Taskwarrior for personal task management, whereas beads is optimized for agent semantics and multi-user/multi-agent synchronization.

  8. What is Multi-Repo Mode in beads?

    main

    By default, beads stores issues in a Dolt database under .beads/ in your current repository. Multi-repo mode extends this by allowing you to:

    • Route issues to different repositories based on your role (e.g., maintainer vs. contributor).
    • Aggregate issues from multiple repos into a unified view using hydration.
    • Keep contributor planning separate from upstream projects to avoid polluting Pull Requests.
    • Maintain data integrity using Dolt version control in every participating repository.

  9. What is a bd swarm?

    main

    A swarm is a structured body of work used to coordinate parallel work on an epic. It is defined by an epic and its child issues, where dependencies form a Directed Acyclic Graph (DAG) of work.

    Swarms are managed via swarm molecules, which:

    • Link to the epic they orchestrate.
    • Use mol_type=swarm for discovery.
    • Optionally specify a coordinator.
    • Can be picked up by any coordinator agent.

  10. What is Beads?

    main

    Beads is a lightweight, graph-based issue tracker designed specifically for AI coding agents to provide long-term memory and task context.

    Key Features:

    • Zero setup: bd init creates a project-local database immediately.
    • Dependency tracking: Supports four dependency types: blocks, related, parent-child, and discovered-from.
    • Ready work detection: Automatically identifies tasks that are unblocked.
    • Agent-friendly: Provides --json output for easy parsing by LLMs.
    • Version-controlled: Uses a Dolt database, allowing for full history, branching, and distributed sharing via Dolt remotes.

  11. Overview of bd dependency types

    main

    The bd issue tracker supports four dependency types to organize and track work. These types differ in their purpose and whether they affect the bd ready state (the list of issues currently actionable).

    TypePurposeAffects bd ready?Common Use
    blocksHard blockerYes - blocked issues excludedSequential work, prerequisites
    relatedSoft linkNo - just informationalContext, related work
    parent-childHierarchyNo - structural onlyEpics and subtasks
    discovered-fromProvenanceNo - tracks originSide quests, research findings

    Key insight: Only blocks dependencies affect what work is ready. The other three provide structure and context.