Task-Management

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.

Beads offers distributed task management for AI agents with dependency-aware DAGs, git-backed persistence, and agent-friendly workflows that integrate seamlessly with development workflows.