Beads: Branch-Aware Memory for Coding Agents
Replace messy markdown plans with a Dolt-powered dependency graph for persistent, structured agent memory.
- Source repo
- gastownhall/beads
- Stars
- ★ 28k
- Last updated
- today
- License
- MIT
- Primary language
- Go
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A solo developer using Claude Code wants a reliable task memory to track issues and TODOs across a long project without losing context.
- Not a fit if
- Users who want a simple todo list, not dependency graphs and compaction
- Teams unwilling to maintain a Dolt database and cross-machine sync
- Environments that must stay fully offline or refuse to run install scripts
- Source review
- 53/100 · Major gaps
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.
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.
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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Beads: Branch-Aware Memory for Coding Agents This agent | 53 · Major gaps | CLIFree | ★ 28k | today | Go | Codex · Claude Code |
| SkillKit — Package Manager for AI Agent Skills | 40 · Major gaps | CLIFree + model costs | ★ 1.6k | 4mo ago | TypeScript | ChatGPT · Claude Code |
| ZhikunCode | 56 · Major gaps | Self-hosted serviceFree + model costs | ★ 525 | 1d ago | Java | OpenAI API · Claude API |
| PowerContext | 55 · Major gaps | CLIFree | ★ 1.3k | today | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.3.2-rc.2 Pre-release
Release notes excerpt
beads v1.3.2-rc.2 Pre-compiled binaries for Linux, macOS (Intel & Apple Silicon), Windows (AMD64 & ARM64), Android/Termux (ARM64), and FreeBSD. Installation (release candidate) > This is a prerelease for validation. The stable install channels — > Homebrew, the install.sh / install.ps1 scripts, npm, and PyPI — > intentionally keep serving the latest stable release, so they will not > install this RC. Use one of the methods below. Manual download (recommended): Download the archive for your platform from the Assets below, extract it, …View on GitHub ↗ -
Release notes excerpt
<!-- STYLE: follows the v1.3.0 release body (title, version/date line, framing intro, Highlights -> Upgrading Notes -> Added -> Changed -> Fixed -> Validation -> Installing -> Contributors -> Full Changelog; bolded operative sentence then dense prose; refs inline as #NNNN; operator-facing; no emoji), scaled down for a patch release the way v1.2.2 was framed. SPAN: v1.3.0 -> v1.3.1 = the CHANGELOG sections [1.3.1], [1.3.1-rc.2] and [1.3.1-rc.1] at the v1.3.1 tag (c1c4b642a), cross-checked against git log v1.3.0..v1.3.1 and the PRs it references. …View on GitHub ↗