explainx.aijoin newsletter3.01k
developer-toolsproductivity

Beads▌

by steveyegge

Beads — a drop-in memory upgrade for your coding agent that boosts context, speed, and reliability with zero friction.

A drop-in memory upgrade for your coding agent

github stars

★ 18.6K

GitHubnpm
Git-backed with cell-level mergeHash-based IDs prevent merge conflictsCross-platform CLI tool

best for

  • / AI agents working on long-horizon coding projects
  • / Multi-agent development workflows
  • / Persistent task tracking across coding sessions

capabilities

  • / Track development tasks with dependency graphs
  • / Store and retrieve structured project memory
  • / Version control task states with automatic merging
  • / Handle multi-agent workflows without conflicts
  • / Compact old tasks to save context window space
  • / Link related issues with semantic relationships

what it does

Provides a distributed, git-backed issue tracker that gives AI agents persistent structured memory for managing complex coding tasks over time.

about

Beads is an official MCP server published by steveyegge that provides AI assistants with tools and capabilities via the Model Context Protocol. Beads — a drop-in memory upgrade for your coding agent that boosts context, speed, and reliability with zero friction. It is categorized under developer tools, productivity.

how to install

You can install Beads in your AI client of choice. Use the install panel on this page to get one-click setup for Cursor, Claude Desktop, VS Code, and other MCP-compatible clients. This server runs locally on your machine via the stdio transport.

license

MIT

Beads is released under the MIT license. This is a permissive open-source license, meaning you can freely use, modify, and distribute the software.

readme

bd - Beads

Distributed, git-backed graph issue tracker for AI agents.

Platforms: macOS, Linux, Windows, FreeBSD

License Go Report Card Release npm version PyPI

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

⚡ Quick Start

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

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

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

🛠 Features

  • Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
  • Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
  • Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
  • Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
  • Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
  • Graph Links: relates_to, duplicates, supersedes, and replies_to for knowledge graphs.

📖 Essential Commands

CommandAction
bd readyList tasks with no open blockers.
bd create "Title" -p 0Create a P0 task.
bd update <id> --claimAtomically claim a task (sets assignee + in_progress).
bd dep add <child> <parent>Link tasks (blocks, related, parent-child).
bd show <id>View task details and audit trail.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

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

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects.

Contributor vs Maintainer: When working on open-source projects:

  • Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
  • Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation

  • npm: npm install -g @beads/bd
  • Homebrew: brew install beads
  • Go: go install github.com/steveyegge/beads/cmd/bd@latest

Requirements: Linux, FreeBSD, macOS, or Windows.

🌐 Community Tools

See docs/COMMUNITY_TOOLS.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

📝 Documentation