Beads (bd) — A Memory Upgrade for Your Coding Agent

Overview

Beads is an open-source CLI tool (bd) designed to give AI coding agents (such as Claude Code, GitHub Copilot, and similar tools) a persistent, structured memory system. Instead of relying on flat markdown files or in-context scratchpads that get lost between sessions, Beads provides a dependency-aware task graph backed by a version-controlled SQL database. This allows agents to plan, track, and execute long-horizon tasks reliably across multiple sessions, branches, and even multiple collaborating agents.

The project is written primarily in Go (91.9%), with Python (5.5%) and Shell (1.1%) rounding out the stack. It supports macOS, Linux, Windows, and FreeBSD.

Core Problem It Solves

AI coding agents suffer from two critical limitations:

Short context windows — long tasks get forgotten or truncated.
No persistent task state — plans written in markdown are fragile, unstructured, and easy to lose.

Beads addresses both by acting as a structured external memory: tasks are stored in a database (powered by Dolt), versioned with git, and exposed to agents via a simple CLI with JSON output.

Key Features

🔷 Dolt-Powered Storage

Beads uses Dolt, a version-controlled SQL database with cell-level merging, native branching, and sync via Dolt remotes. This means the task database itself has a full git-like history.

🤖 Agent-Optimized Interface

All commands produce JSON output by default, making it trivial for agents to parse results programmatically. The bd ready command auto-detects tasks with no open blockers, guiding agents on what to work on next.

🔗 Dependency Graph

Tasks can be linked with typed relationships:

blocks / blocked_by
relates_to
duplicates
supersedes
replies_to

This forms a true knowledge graph, not just a flat list.

🧠 Semantic Memory Compaction

Old closed tasks are automatically summarized ("memory decay") to reduce context window usage while preserving essential history.

💬 Messaging System

A built-in message issue type supports threaded discussions (--thread), ephemeral lifecycles, and mail delegation between agents.

🪢 Hierarchical Task IDs

Tasks support epic/task/subtask nesting via hash-based IDs:

bd-a3f8       (Epic)
bd-a3f8.1     (Task)
bd-a3f8.1.1   (Sub-task)

Hash-based IDs prevent merge collisions in multi-agent workflows.

🥷 Stealth Mode

bd init --stealth lets you use Beads locally without committing any files to the main repository — perfect for personal use on shared or open-source projects.

👥 Contributor vs Maintainer Roles

Contributors (forked repos): bd init --contributor routes planning issues to a separate personal repo, keeping experimental work out of PRs.
Maintainers: Beads auto-detects the maintainer role via SSH URLs or credentialed HTTPS.

Essential CLI Commands

Command	Description
`bd init`	Initialize Beads in your project
`bd ready`	List tasks with no open blockers
`bd create "Title" -p 0`	Create a P0 (highest priority) task
`bd update <id> --claim`	Atomically claim a task (set assignee + in_progress)
`bd dep add <child> <parent>`	Link tasks with a dependency relationship
`bd show <id>`	View task details and audit trail

Installation

# One-liner install
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Or via npm
npm install -g @beads/bd

# Or via Homebrew
brew install beads

# Or via Go
go install github.com/steveyegge/beads/cmd/bd@latest

Then initialize in your project:

cd your-project
bd init
echo "Use 'bd' for task tracking" >> AGENTS.md

Integrations

Beads integrates with major AI coding agents and IDEs:

Claude Code (Anthropic)
GitHub Copilot
Cursor, Windsurf, Amp and other MCP-compatible tools
MCP server available via beads-mcp on PyPI

Community-built extensions include terminal UIs, web dashboards, editor plugins, and native apps. See docs/COMMUNITY_TOOLS.md for the full list.

Project Stats (as of early 2026)

Metric	Value
GitHub Stars	17,300+
Forks	1,100+
Contributors	258
Releases	78
Primary Language	Go
License	MIT

Who Is It For?

AI Agent Developers building autonomous coding pipelines
Individual Developers who use Claude Code, Copilot, or Cursor and want better task tracking
Teams running multi-agent workflows on shared codebases
Open-source contributors who need personal task management without polluting the upstream repo

Summary

Beads fills a critical gap in the AI coding agent ecosystem: persistent, structured, version-controlled memory. By combining a graph-based task model with a git-native SQL backend and an agent-friendly CLI, it enables coding agents to tackle complex, multi-session projects that would otherwise exceed their context limits. Its MIT license, multi-platform support, and active community make it a practical choice for anyone working seriously with AI coding tools.