Beads: Branch-Aware Memory for Coding Agents
Replace messy markdown plans with a Dolt-powered dependency graph for persistent, structured agent memory.
Evidence shows: README and SECURITY.md clearly state local-first, no telemetry, but Dolt dependency collects metrics by default, requiring manual disable; install script verifies checksums, but no user confirmation step; data flow transparency is good, documenting storage location and sync mechanism; sensitive data handling is insufficient, storing tokens in plaintext without encryption; dependency security has go.sum pinning and Renovate monitoring, but dependency count is large; external effects are limited, but git operations and Dolt sync may have side effects; rollback support is limited, only via Dolt history; source attribution is unclear, publisher unverified. Deductions: lack of user confirmation, plaintext sensitive data, excessive dependencies, unknown publisher identity.
Evidence shows: README and SECURITY.md content is consistent, command descriptions are clear; dependencies are pinned via go.sum, but Dolt and others may be unavailable; failure messages provide actionable errors, such as schema version mismatch. Deductions: dependency availability unverified, failure messages only partially covered.
Evidence shows: clear target audience of coding agents, scenarios include multi-agent, CI/CD, non-git environments; capability boundaries are clear, such as stealth mode, contributor mode; trigger precision is high, commands are explicit; environment fit is broad, supporting multiple platforms. Deductions: no detailed environment configuration examples.
Evidence shows: documentation structure is clear, with installation guide, FAQ, known limitations; installation notes are detailed, supporting multiple methods; naming is stable, but version number not explicit; examples and FAQ exist; known limitations are clear; MIT license; versioning changelog not provided; maintenance responsibility not clear. Deductions: missing versioning changelog, unclear maintenance responsibility.
Evidence shows: output usability is high, providing JSON output; marginal value is high, solving agent memory problem; cost-benefit not fully explained, dependency complexity. Deductions: insufficient cost-benefit analysis.
Evidence shows: README claims are partially supported by documentation, but no test results provided; cross-source corroboration insufficient, relying on single repository; fact-inference separation unclear. Deductions: lack of test evidence and external verification.
- Dolt collects metrics by default, requiring manual disable, which may violate privacy expectations.
- Sensitive data (e.g., API tokens) is stored in plaintext without encryption, not suitable for production.
- Large dependency count increases supply chain risk, requiring regular audits.
- Publisher identity unverified; verify checksums before installation.
What does this agent do, and when should you use it?
Beads is a distributed graph issue tracker for AI agents, powered by Dolt, a version-controlled SQL database with cell-level merge, native branching, and sync. It provides persistent, structured memory for coding agents, replacing markdown plans with a dependency-aware graph to handle long-horizon tasks without losing context. Beads offers agent-optimized features like JSON output, dependency tracking, and auto-ready task detection, plus hash-based IDs to avoid conflicts. It supports embedded and server storage modes, cross-machine sync via Dolt remotes, and features like compaction and messaging. It integrates with Claude Code, Codex, and other agents, running on macOS, Linux, Windows, and FreeBSD.
The bd CLI manages a task graph for AI agents. It initializes a project (bd init), installs agent integrations (bd setup claude, bd setup codex), and provides commands for agents to list ready tasks (bd ready), create tasks (bd create), claim tasks atomically (bd update --claim), show task details (bd show), close tasks (bd close), and link tasks (bd dep add). It also prints workflow context and memories (bd prime) and stores project memories (bd remember). Beads stores data in a Dolt database (embedded or server) and syncs via Dolt push/pull on git remotes. It supports hierarchical IDs (bd-a3f8.1) and compaction to archive old tasks.
- A solo developer using Claude Code wants a reliable task memory to track issues and TODOs across a long project without losing context.
- A team using Codex CLI installs Beads to automatically create AGENTS.md, hooks, and settings for consistent agent behavior.
- A maintainer working on an open-source project with multiple contributors uses hash-based IDs and Dolt merging to avoid conflicts when tasks are created in parallel.
- A remote team needs to sync task state across machines, using
bd dolt pushandbd dolt pullto share progress. - A developer working in a non-git environment (e.g., Sapling) uses
--stealthmode to manage tasks without git integration.
What are this agent's strengths and limitations?
- Dolt's version-controlled SQL database enables fine-grained merge and branching, which is ideal for multi-agent workflows.
- Hash-based IDs and dependency graph structure prevent merge conflicts, enabling smooth multi-agent collaboration.
- Agent-optimized JSON output and auto-ready detection integrate seamlessly with coding agent workflows.
- Stealth mode enables usage in non-git projects, increasing flexibility.
- Cross-platform support (macOS, Linux, Windows, FreeBSD) and multiple installation methods.
- Learning curve for new CLI commands and concepts like beads, dependency graph, and compaction, which may be overkill for simple tasks.
- Dependency on Dolt adds storage and sync complexity, requiring additional maintenance and understanding.
- Install script executes code, requiring trust and checksum verification.
- Advanced features like server mode and cross-machine sync require additional configuration.
- Some features (e.g., compaction, messaging) may be underdocumented in the README.
How do you install or deploy this agent?
Install the Beads CLI (system-wide) using the install script:
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bashOr via Homebrew or npm:
brew install beads
npm install -g @beads/bdHow do you use this agent?
Initialize Beads in your project directory:
cd your-project
bd initOptionally set up agent integrations:
bd setup claudeUse key commands:
- bd ready to list tasks with no open blockers.
- bd create "Title" -p 0 to create a P0 task.
- bd update <id> --claim to claim a task.
- bd close <id> "Fixed" to close a task.
- bd prime to print workflow context and persistent memories.
- bd remember "insight" to store project memory.