beads

README

bd - Beads

Distributed, git-backed graph issue tracker for AI agents.

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

⚡ Quick Start

# Install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize (Humans run this once)
bd init

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

🛠 Features

• Git as Database: Issues stored as JSONL in .beads/. Versioned, branched, and merged like code.
• Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
• Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
• Invisible Infrastructure: SQLite local cache for speed; background daemon for auto-sync.
• Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.

📖 Essential Commands

Command	Action
bd ready	List tasks with no open blockers.
bd create "Title" -p 0	Create a P0 task.
bd dep add <child> <parent>	Link tasks (blocks, related, parent-child).
bd show <id>	View task details and audit trail.
bd quickstart	Interactive guide for AI agents.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

• bd-a3f8 (Epic)
• bd-a3f8.1 (Task)
• bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects.

📦 Installation

• npm: npm install -g @beads/bd
• Homebrew: brew install steveyegge/beads/bd
• Go: go install github.com/steveyegge/beads/cmd/bd@latest

Requirements: Linux (glibc 2.32+), macOS, or Windows.

🌐 Community Tools

• beads_viewer - Keyboard-driven terminal UI with kanban board, insights panel, and graph view. Built by @Dicklesworthstone.
• beads.el - Emacs UI to browse, edit, and manage beads. Built by @ctietze.
• beads-ui - Local web interface with live updates and kanban board. npx beads-ui start. Built by @mantoni.
• bdui - Real-time terminal UI with tree view, dependency graph, and vim-style navigation. Built by @assimelha.
• perles - Terminal UI with BQL (Beads Query Language) and multi-view kanban. Built by @zjrosen.
• vscode-beads - VS Code extension with issues panel and daemon management. Built by @jdillon.

📝 Documentation

• Installing | Agent Workflow | Sync Branch Mode | FAQ

Documentation

Overview

Package beads provides a minimal public API for extending bd with custom orchestration.

Most extensions should use direct SQL queries against bd's database. This package exports only the essential types and functions needed for Go-based extensions that want to use bd's storage layer programmatically.

For detailed guidance on extending bd, see docs/EXTENDING.md.

Index

• Constants
• func FindBeadsDir() string
• func FindDatabasePath() string
• func FindJSONLPath(dbPath string) string
• type BlockedIssue
• type Comment
• type DatabaseInfo
  • func FindAllDatabases() []DatabaseInfo
• type Dependency
• type DependencyCounts
• type DependencyType
• type EpicStatus
• type Event
• type EventType
• type Issue
• type IssueFilter
• type IssueType
• type IssueWithCounts
• type Label
• type SortPolicy
• type StaleFilter
• type Status
• type Storage
  • func NewSQLiteStorage(ctx context.Context, dbPath string) (Storage, error)
• type Transaction
• type TreeNode
• type WorkFilter

Constants

const (
	StatusOpen       = types.StatusOpen
	StatusInProgress = types.StatusInProgress
	StatusBlocked    = types.StatusBlocked
	StatusClosed     = types.StatusClosed
)

Status constants

const (
	TypeBug     = types.TypeBug
	TypeFeature = types.TypeFeature
	TypeTask    = types.TypeTask
	TypeEpic    = types.TypeEpic
	TypeChore   = types.TypeChore
)

IssueType constants

const (
	DepBlocks         = types.DepBlocks
	DepRelated        = types.DepRelated
	DepParentChild    = types.DepParentChild
	DepDiscoveredFrom = types.DepDiscoveredFrom
)

DependencyType constants

const (
	SortPolicyHybrid   = types.SortPolicyHybrid
	SortPolicyPriority = types.SortPolicyPriority
	SortPolicyOldest   = types.SortPolicyOldest
)

SortPolicy constants

const (
	EventCreated           = types.EventCreated
	EventUpdated           = types.EventUpdated
	EventStatusChanged     = types.EventStatusChanged
	EventCommented         = types.EventCommented
	EventClosed            = types.EventClosed
	EventReopened          = types.EventReopened
	EventDependencyAdded   = types.EventDependencyAdded
	EventDependencyRemoved = types.EventDependencyRemoved
	EventLabelAdded        = types.EventLabelAdded
	EventLabelRemoved      = types.EventLabelRemoved
	EventCompacted         = types.EventCompacted
)

EventType constants

Functions

func FindBeadsDir

func FindBeadsDir() string

FindBeadsDir finds the .beads/ directory in the current directory tree Returns empty string if not found. Supports both database and JSONL-only mode.

func FindDatabasePath

func FindDatabasePath() string

FindDatabasePath finds the beads database in the current directory tree

func FindJSONLPath

func FindJSONLPath(dbPath string) string

FindJSONLPath finds the JSONL file corresponding to a database path

Types

type BlockedIssue

type BlockedIssue = types.BlockedIssue

Core types from internal/types

type Comment

type Comment = types.Comment

Core types from internal/types

type DatabaseInfo

type DatabaseInfo = beads.DatabaseInfo

DatabaseInfo contains information about a beads database

func FindAllDatabases

func FindAllDatabases() []DatabaseInfo

FindAllDatabases finds all beads databases in the system

type Dependency

type Dependency = types.Dependency

Core types from internal/types

type DependencyCounts

type DependencyCounts = types.DependencyCounts

Core types from internal/types

type DependencyType

type DependencyType = types.DependencyType

Core types from internal/types

type EpicStatus

type EpicStatus = types.EpicStatus

Core types from internal/types

type Event

type Event = types.Event

Core types from internal/types

type EventType

type EventType = types.EventType

Core types from internal/types

type Issue

type Issue = types.Issue

Core types from internal/types

type IssueFilter

type IssueFilter = types.IssueFilter

Core types from internal/types

type IssueType

type IssueType = types.IssueType

Core types from internal/types

type IssueWithCounts

type IssueWithCounts = types.IssueWithCounts

Core types from internal/types

type Label

type Label = types.Label

Core types from internal/types

type SortPolicy

type SortPolicy = types.SortPolicy

Core types from internal/types

type StaleFilter

type StaleFilter = types.StaleFilter

Core types from internal/types

type Status

type Status = types.Status

Core types from internal/types

type Storage

type Storage = beads.Storage

Storage is the interface for beads storage operations

func NewSQLiteStorage

func NewSQLiteStorage(ctx context.Context, dbPath string) (Storage, error)

NewSQLiteStorage creates a new SQLite storage instance at the given path

type Transaction

type Transaction = beads.Transaction

Transaction provides atomic multi-operation support within a database transaction. Use Storage.RunInTransaction() to obtain a Transaction instance.

type TreeNode

type TreeNode = types.TreeNode

Core types from internal/types

type WorkFilter

type WorkFilter = types.WorkFilter

Core types from internal/types