Summary

Beads is a lightweight, graph-based issue tracker designed to enhance the memory and planning capabilities of AI coding agents. It addresses the challenge of agents losing context or failing to manage complex, long-horizon tasks by organizing work into chained issues. The primary benefit is enabling agents to reliably execute multi-step tasks, maintain focus, and avoid "amnesia" by providing a persistent, queryable memory. It's targeted at developers integrating AI agents into their workflows, offering an instant upgrade in organization and task management.

How It Works

Beads employs a novel dual-storage architecture: a Git-committed JSON Lines (.beads/issues.jsonl) file serves as the source of truth, while a local SQLite database (.beads/*.db) acts as a fast, ephemeral cache. Changes made via the bd CLI are written to SQLite and automatically exported to JSONL after a short debounce period. Conversely, git pull triggers an automatic import of newer JSONL data into SQLite. This approach creates a serverless, distributed database accessible across multiple machines via Git, with AI assistance for resolving merge conflicts.

Quick Start & Requirements

• Primary install: curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
• Prerequisites: Git. Go 1.21+ is required for manual installation via go install or building from source. Windows 11 users must build from source.
• Setup: Zero setup required; bd init creates a project-local database.
• Links: Project Repository, Examples

Highlighted Details

• Distributed Git-backed Database: Acts as a managed SQL database shared across agents and machines via Git, without requiring a server.
• Agent-Centric Design: Features --json flags for programmatic integration and a bd ready --json command to efficiently find unblocked tasks.
• Rich Dependency Tracking: Supports four dependency types (blocks, related, parent-child, discovered-from) for sophisticated task chaining and context.
• AI-Resolvable Conflicts: Leverages AI capabilities to help resolve merge conflicts in the .beads/issues.jsonl file.
• Extensible SQLite Backend: Allows users to add custom tables to the SQLite database for deeper integration.

Maintenance & Community

The project is actively developed and dogfooded. Specific details on maintainers, community channels (like Discord/Slack), or sponsorships are not provided in the README.

Licensing & Compatibility

Licensed under the MIT License, permitting commercial use and integration into closed-source projects.

Limitations & Caveats

The project is currently in Alpha Status (v0.9.0), with potential for API and format changes before version 1.0. It is recommended for development or internal projects. Issues are isolated per project database and cannot reference issues across different projects.