Skip to main content

Distributed-Systems

Beads

task-management ai-agents distributed-systems git-native project-planning workflow-automation

Beads is a lightweight, distributed task management system built specifically for AI agents managing complex, multi-session projects. Created by Steve Yegge, it leverages Git as its distributed database and models work as a directed acyclic graph (DAG) with explicit dependencies and priority levels, enabling agents to identify “ready work” and maintain context across sessions without losing state or requiring a central server.

Core Features

Directed Acyclic Graph (DAG) Dependencies

  • Explicit Task Relationships: Model blocking dependencies, parent-child relationships, and thematic links
  • Ready Work Detection: Automatically surface tasks with no blocking dependencies and high priority
  • Dependency Visualization: View full dependency trees and impact analysis
  • Multi-type Relationships: Supports “blocks,” “related,” “parent,” and “discovered-from” link types

Priority-Driven Task Management

  • 5-Level Priority System: Critical (0), High (1), Medium (2), Low (3), Backlog (4)
  • Priority + Readiness: Combine priority with dependency status to determine actual work urgency
  • Smart Task Sorting: Get highest-impact unblocked work first
  • Threshold-Based Filtering: Filter work by priority level and status

Git-Native Architecture

  • No Central Server: Uses Git as distributed database for complete decentralization
  • Local SQLite Cache: Fast local queries with automatic sync to Git
  • JSONL Source of Truth: Single .beads/issues.jsonl file committed to Git
  • Custom Merge Driver: Intelligent conflict resolution for concurrent edits from multiple agents
  • Protected Branch Support: Works with strict Git workflows and branch protection rules

Agent-Friendly Interface

  • JSON-First Output: Every command supports --json for programmatic use
  • MCP Server Support: Use Claude, OpenAI, or other MCP-compatible clients directly with Beads
  • Batch Operations: Import and export large task sets efficiently
  • Audit Trail: Complete history of all changes for reconstruction and debugging

Multi-Agent Coordination

  • Distributed by Design: Multiple agents on different branches/machines can coordinate through Git
  • Hash-Based IDs (v0.20.1+): Collision-resistant task IDs for safe concurrent creation
  • No Conflicts: Concurrent edits merge safely without manual intervention
  • Zero Coordinator: No central service needed for multi-agent workflows

Technical Specifications

  • Platform: CLI (cross-platform), MCP server, Python package
  • Backend: SQLite (local cache) + Git (distributed sync)
  • Storage: JSON Lines (.beads/issues.jsonl)
  • Database Format: Extendable schema with custom table support
  • Performance: Fast queries for <200 issues; performance degrades on larger databases
  • Integration Points: Git hooks, shell completion, CI/CD pipelines, MCP servers

Unique Advantages

Purpose-Built for AI Agents

Unlike general-purpose issue trackers, Beads’ entire design assumes an AI agent as the primary user. The --json interface isn’t an afterthought but the primary way the system works. The DAG model forces you to think about dependencies explicitly, preventing agents from attempting impossible tasks.

Read More