Beads

Beads

by Steve Yegge

A memory upgrade for your coding agent - Distributed, git-backed graph issue tracker for AI agents

See https://github.com/steveyegge/beads

Features

• Persistent Memory: Structured memory system that prevents coding agents from losing context during long-horizon tasks
• Git-Backed Storage: Issues stored as JSONL in .beads/ directory, versioned and merged like code
• Dependency-Aware Graph: Tasks organized with automatic detection of “ready” tasks without open blockers
• Hash-Based IDs: Format like bd-a1b2 prevents merge conflicts in multi-agent/multi-branch workflows
• Hierarchical Task Structure: Supports Epic → Task → Subtask relationships (e.g., bd-a3f8.1.1)
• JSON Output: Machine-readable output optimized for AI agent integration
• Semantic Memory Compaction: Summarizes closed tasks to preserve context windows
• Background Sync: Daemon enables auto-sync functionality across sessions
• Stealth Mode: Allows local-only usage on shared projects (bd init --stealth)

Superpowers

Beads solves the “50 First Dates” problem where coding agents wake up with no memory of previous work. Without Beads, agents struggle to distinguish between “we decided this yesterday” and “this was a brainstorm from three weeks ago.”

Key Benefits:

• For AI Agents: Works with Claude Code, Codex, AMP (Sourcegraph Amp), or any agent that can read/write files
• For Multi-Agent Teams: Hash-based IDs eliminate merge conflicts when multiple agents work simultaneously
• For Long-Running Projects: Maintains task context across days, weeks, and branches without losing track
• For Developers: Git integration means your agent’s memory is version-controlled alongside your code

Who This Is For:

• Developers using AI coding agents for complex, multi-step projects
• Teams running multiple coding agents in parallel
• Anyone frustrated with agents losing context or forgetting decisions
• Projects requiring structured task tracking integrated with version control

Installation

Package Managers:

# npm  
npm install -g @beads/bd  
  
# Homebrew  
brew install steveyegge/beads/bd  
  
# Go  
go install github.com/steveyegge/beads/cmd/bd@latest  
  
# Shell script  
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash  

Requirements: Linux (glibc 2.32+), macOS, or Windows

Essential Commands

Command	Function
bd ready	Lists tasks without open blockers
bd create "Title" -p 0	Creates priority-0 task
bd dep add <child> <parent>	Links tasks (blocks, related, parent-child)
bd show <id>	Displays task details and audit trail

Technical Architecture

• Storage Layer: JSONL files in .beads/ directory
• Cache Layer: SQLite for performance optimization
• Version Control: Git integration for branching and merging
• Data Model: Dependency graph with automatic ready-task detection

Agent Integration

Beads provides structured memory through:

1. JSON output for machine parsing
2. Dependency tracking to prevent blocked work
3. Audit trails showing task history
4. Context preservation across sessions

Agents can query bd ready to find actionable tasks and use bd show to understand task context and history.

Community & Adoption

Within six days of launch, Beads achieved:

• 1,000+ GitHub stars
• ~50 forks
• Growing ecosystem of community-built tools and integrations

Documentation

Primary guides in repository:

• AGENT_INSTRUCTIONS.md - Integration guide for AI agents
• PROTECTED_BRANCHES.md - Git workflow management
• TROUBLESHOOTING.md - Common issues and solutions
• FAQ.md - Frequently asked questions

Pricing

Open source and free (MIT License)