Beads (bd) is an open-source task coordination and state orchestration harness for AI coding agents developed by Gastown Hall. It provides a structured, version-controlled task graph and execution framework that enables coding agents—such as Claude, GitHub Copilot, and Amp—to collaborate deterministically across codebase tasks without losing context or clobbering state. In day-to-day use, Beads operates via the `bd` command-line interface and repo-level configuration directories (`.beads/` and `.agent/`). Workflows are defined as declarative formulas (such as `gh-issue-to-pr`) and step-by-step agent instructions. Task state, execution leases, and agent artifacts are tracked through a versioned database layer (leveraging Dolt), with changes pushed and pulled via commands like `bd dolt push` and `bd dolt pull`. Unlike traditional CLI agent wrappers that rely on transient in-memory chat histories, Beads treats agent tasks as discrete, version-controlled units of work. It incorporates explicit lease migrations, contradiction-handling cursors, and conflict-resolution workflows so multiple agent instances or human developers can work asynchronously on the same repository. Beads is free, open-source software distributed on GitHub. It is implemented as a CLI tool with plugin integrations for agent environments like Claude Code and GitHub Copilot.
Tags: ai agent, cli, coding agent, developer tools, memory, OpenSource
bd dolt push and bd dolt pull. - Declarative Task Formulas — Structures multi-step development pipelines, such as gh-issue-to-pr, inside .beads/formulas to enforce repeatable agent workflows. - Conflict Resolution Workflows — Implements structured recovery and resolution protocols (.agent/workflows/resolve-beads-conflict.md) for handling contradictory states between agent runs. - Multi-Agent Ecosystem Support — Interoperates with multiple agent runners including Claude (.claude-plugin), GitHub Copilot, and Amp threads. - Task Leases & Migration Cursors — Manages task ownership and state replays to avoid duplicate or colliding agent executions.gh-issue-to-pr) to direct an agent to read an issue description, implement code changes across the repository, execute validation suites, and open a pull request with structured tracking.Beads is built for software engineers, platform teams, and AI tool builders who need structured, reproducible orchestration for CLI-based coding agents across large repositories. It is not intended for users looking for a single turnkey conversational chatbot with zero repository configuration.
bd) from the official repository releases or via the project installer (standard build): bash # Clone and build the binary (or download the latest release binary from GitHub Releases) git clone https://github.com/gastownhall/beads.git cd beads make build # Verify installation bd --versionbash cd /path/to/your/project bd init # Check synchronization and state backend status bd dolt statusbash # Pull the latest task state bd dolt pull # Run a task formula (e.g., GitHub Issue to PR) bd run formula gh-issue-to-pr --issue 128 # Push updated task records and lease state bd dolt pushPart of CLI Coding Agents
Categories: AI Coding Agents, Developer Tools, Memory