Project-Planning

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 brings a refreshing take on agent-friendly task management, using a dependency-aware, distributed DAG model backed by git. While it’s still rapidly evolving, my experience adapting Beads has been positive—no major growing pains so far, likely because I’m integrating it as an agent memory and not as my exclusive planning tool.

What Stands Out

• DAG + Priority Model: Beads natively organizes tasks with dependencies and priorities, making long-horizon agent planning much easier than vanilla markdown TODOs.
• Distributed Git-Backed Design: Issues sync via regular git operations, so collaborating across machines and agents is seamless.
• Agent-Centric Workflow: Designed for coding agents to file, update, and track tasks for you. Human users mostly manage initialization and hygiene, leaving agents to handle the rest.
• CLI & API Integrations: Easy to experiment with in your local setup, and plays well with other agent frameworks and planning tools.

Caveats & Considerations

• Alpha-Quality: Beads is under heavy development. Bugs and version churn are expected, but the developer (and contributor community) fix issues quickly.
• Not a One-Size-Fits-All Tracker: I haven’t relied solely on Beads—I recommend it for agent-task management, not for entire teams, org-wide roadmaps, or finished/archived work. Keep established tools (GitHub Issues, Jira, etc.) on hand.
• Migration and Setup: Upgrading between versions (e.g., hash-based IDs) requires a bit of care, but the documentation covers most migration scenarios.
• Session Hygiene: Some manual cleanup and cross-tool coordination (“landing the plane”) is still useful, but not a blocker.

Best Practices & Recommendations

• Use Beads for active agent workflows, dependency planning, and ready-to-work detection.
• Pair it with broader planning frameworks for high-level goals, future roadmaps, and archiving.
• Experiment in side projects before bringing into larger scale, production environments.
• Don’t expect Beads to be invisible—agents, and occasionally humans, need to reference issue IDs and help sync state.

Technical Details

Git-Native Architecture

Beads uses Git as its distributed database—no servers, just version control: