gastownhall

beads

AI#AI Agents#Dolt#CLI#Task Tracking#Database

// summary

Beads is a distributed, Dolt-powered issue tracking system designed to provide persistent, structured memory for AI coding agents. It utilizes a dependency-aware graph structure to help agents manage complex, long-horizon tasks without losing critical context. The tool offers flexible storage modes and integrates seamlessly into development workflows with or without Git.

// technical analysis

Beads is a distributed, dependency-aware graph issue tracker designed specifically to provide persistent, structured memory for AI coding agents. By leveraging Dolt as its underlying version-controlled SQL database, it enables agents to manage long-horizon tasks and complex workflows without the context loss associated with traditional markdown-based planning. The project prioritizes agent-friendly outputs and conflict-free collaboration, offering flexible storage modes that allow it to function either as an integrated Git-based tool or as a standalone system for non-Git environments.

// key highlights

Utilizes Dolt as a version-controlled SQL backend to provide cell-level merging and native branching capabilities.

Employs hash-based IDs to ensure zero-conflict task management across multi-agent and multi-branch workflows.

Features semantic memory compaction that summarizes closed tasks to optimize the context window for AI agents.

Supports a hierarchical task structure, allowing for the organization of epics, tasks, and sub-tasks with unique identifiers.

Offers a stealth mode and Git-free configuration to support non-Git version control systems, monorepos, and isolated CI/CD environments.

Provides native dependency tracking and auto-ready task detection to help agents prioritize work effectively.

// use cases

Persistent task tracking for AI agents with dependency-aware graph structures

Version-controlled issue management using Dolt for mergeable, branchable data

Semantic memory compaction to optimize context windows for long-running projects

// getting started

To begin, install the Beads CLI via the provided shell script, Homebrew, or npm. Once installed, navigate to your project directory and run 'bd init' to initialize the local database. You can then start managing tasks using commands like 'bd create' and 'bd ready', or consult the documentation for advanced configurations like server mode or stealth usage.