Beads: Persistent Memory for AI Coding Agents with 18.7k+ GitHub Stars

Tosin Akinosho

— 4 min read

Beads is a distributed, git-backed issue tracker designed specifically for AI coding agents. Created by Steve Yegge, it solves a critical problem: AI agents lose context between sessions and struggle with long-horizon planning. With 18.7k+ GitHub stars and active development, Beads has become essential infrastructure for teams using Claude Code, Sourcegraph Amp, and other agentic workflows.

What is Beads?

Beads is not a traditional issue tracker. It's external memory for AI agents—a dependency-aware task database that persists across sessions and enables agents to maintain coherent long-term plans. The name comes from the metaphor of beads on a chain: tasks linked by dependencies that agents can follow to complete work in the correct order.

Created by Steve Yegge (ex-Amazon, ex-Google, ex-Sourcegraph), Beads emerged from his "vibe coding" experiments with AI agents. After spending six weeks building a 350k-line orchestration system that ultimately failed due to architectural flaws, Yegge discovered that a specialized issue tracker solved the core problem in just 15 minutes. The insight: agents don't need markdown plans—they need structured, queryable task graphs.

The project is written in Go (92.9% of codebase) and uses a hybrid architecture combining git-backed JSONL storage with SQLite caching. This design enables conflict-free merging when multiple agents work in parallel, version control for all task state changes, and blazing-fast queries for agent decision-making.

Core Features and Architecture

1. Git-Native Storage with JSONL Format

Beads stores tasks as append-only JSON Lines in a hidden `.beads/` directory. Each task update appends a new line rather than modifying existing data. This design makes git merges naturally conflict-resistant—when two agents create tasks on different branches, the JSONL logs merge cleanly without collisions.

# Example task structure
{"id": "bd-a1b2", "desc": "Implement auth", "status": "open", "priority": 0}
{"id": "bd-c3d4", "desc": "Fix database", "status": "in_progress", "blocked_by": ["bd-a1b2"]}

2. Hash-Based ID Generation

Instead of sequential IDs (1, 2, 3) that collide in distributed systems, Beads uses shortened hashes like `bd-a1b2`. This enables zero-coordination task creation across multiple agents and branches. If collisions occur, the tool extends the prefix deterministically.

3. Dependency-Aware Task Queries

The `bd ready` command returns only unblocked tasks—work that can actually be started. This saves agents from parsing dependency graphs manually and burning tokens on analysis. The tool does the topological sorting in Go, serving up focused work lists via JSON.

$ bd ready --json
[
  {"id": "bd-a1b2", "desc": "Implement auth", "status": "open"},
  {"id": "bd-e5f6", "desc": "Write tests", "status": "open"}
]

4. Hybrid Storage: Git + SQLite

The source of truth lives in git-tracked JSONL files. For performance, Beads hydrates a local SQLite database on startup, enabling fast queries without re-parsing append-only logs. This hybrid approach combines git's versioning benefits with database query speed.

5. Multi-Agent Coordination

Multiple agents can work on the same project simultaneously. The `--assignee` filter prevents duplicate work, and git's merge capabilities handle concurrent task creation. Agents see claimed tasks (`status: in_progress`) and avoid duplicating effort.

6. Audit Trail and History

Every task change is logged with timestamps and actor information. Agents can inspect the complete history of a task, understanding what changed and why. This transparency is crucial for debugging agent behavior and understanding work evolution.

Get free AI agent insights weekly

Join our community of builders exploring the latest in AI agents, frameworks, and automation tools.

Join Free

Getting Started

Prerequisites: macOS, Linux, Windows, or FreeBSD. Git installed and configured.

Installation:

# Via npm
npm install -g @beads/bd

# Via Homebrew
brew install beads

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

Quick Start:

# Initialize Beads in your project
cd your-project
bd init

# Tell your agent to use Beads
echo "Use 'bd' for task tracking" >> AGENTS.md

# Create your first task
bd create "Implement authentication" -p 0

# See what's ready to work on
bd ready --json

That's it. Your agents now have persistent, structured memory across sessions.

Real-World Use Cases

Long-Horizon Feature Development

A typical feature requires multiple agent sessions: design, implementation, testing, review, cleanup. Without Beads, agents forget earlier decisions and recreate work. With Beads, agents query the task graph, see what's blocked, and continue intelligently from where they left off.

Multi-Agent Coordination

Teams running multiple agents on the same codebase face duplicate work and conflicting changes. Beads enables agents to claim tasks (`--assignee`), see what others are working on, and coordinate without human intervention. The git-backed architecture handles merge conflicts automatically.

Incident Response and Bug Triage

When bugs are discovered during development, agents can file issues with `discovered-from` links, creating an audit trail of how problems were found. This prevents work from being lost and helps teams understand the full context of fixes.

Hierarchical Planning

Beads supports hierarchical IDs: `bd-a3f8` (epic), `bd-a3f8.1` (task), `bd-a3f8.1.1` (subtask). Agents can break large features into manageable pieces while maintaining the dependency graph, preventing the "markdown plan explosion" that plagued earlier approaches.

How It Compares

vs. GitHub Issues

GitHub Issues is designed for human collaboration. Beads is optimized for agent cognition: structured JSON output, dependency queries, and token-efficient commands. GitHub Issues requires API calls and parsing HTML; Beads is a local CLI tool with instant feedback.

vs. Markdown TODO Files

Markdown TODOs are write-only memory for agents. Updating status means editing text files, which often causes git conflicts and accidental data loss. Beads provides structured queries, dependency tracking, and conflict-free merging via git's append-only JSONL format.

vs. Jira

Jira is heavyweight and requires a server. Beads is lightweight, file-based, and distributed. You can branch task state alongside code, revert task changes with git, and work offline. For teams using AI agents, Beads' simplicity is a feature, not a limitation.

What's Next

Beads is actively maintained with regular releases (v0.59.0 as of March 2026). The roadmap includes enhanced multi-agent orchestration, improved conflict resolution, and deeper integration with Claude Code and other agent frameworks. Steve Yegge is also building GasTown, a full agent orchestration environment that uses Beads as its core memory layer.

The project demonstrates a broader trend: as AI agents become more capable, the tooling around them becomes critical. Beads isn't just an issue tracker—it's a blueprint for building agent-first infrastructure that enables long-horizon planning, multi-agent coordination, and persistent memory across sessions.

Sources

Read more