beads

package module
v0.57.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2026 License: MIT Imports: 4 Imported by: 2

README

bd - Beads

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

Platforms: macOS, Linux, Windows, FreeBSD

License Go Report Card Release npm version PyPI

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 beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

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

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

🛠 Features

  • Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
  • 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.
  • Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
  • Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
  • Graph Links: relates_to, duplicates, supersedes, and replies_to for knowledge graphs.

📖 Essential Commands

Command Action
bd ready List tasks with no open blockers.
bd create "Title" -p 0 Create a P0 task.
bd update <id> --claim Atomically claim a task (sets assignee + in_progress).
bd dep add <child> <parent> Link tasks (blocks, related, parent-child).
bd show <id> View task details and audit trail.

🔗 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.

Contributor vs Maintainer: When working on open-source projects:

  • Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
  • Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation

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

Requirements: Linux, FreeBSD, macOS, or Windows.

🌐 Community Tools

See docs/COMMUNITY_TOOLS.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

📝 Documentation

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

View Source 
const (
	StatusOpen       = types.StatusOpen
	StatusInProgress = types.StatusInProgress
	StatusBlocked    = types.StatusBlocked
	StatusDeferred   = types.StatusDeferred
	StatusClosed     = types.StatusClosed
)

Status constants

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

IssueType constants

View Source 
const (
	DepBlocks            = types.DepBlocks
	DepRelated           = types.DepRelated
	DepParentChild       = types.DepParentChild
	DepDiscoveredFrom    = types.DepDiscoveredFrom
	DepConditionalBlocks = types.DepConditionalBlocks // B runs only if A fails (bd-kzda)
)

DependencyType constants

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

SortPolicy constants

View Source 
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

Variables

This section is empty.

Functions

func FindBeadsDir added in v0.24.0 

func FindBeadsDir() string

FindBeadsDir finds the .beads/ directory in the current directory tree. Returns empty string if not found.

func FindDatabasePath 

func FindDatabasePath() string

FindDatabasePath finds the beads database in the current directory tree

Types

type BlockedIssue added in v0.12.0 

type BlockedIssue = types.BlockedIssue

Core types from internal/types

type Comment added in v0.12.0 

type Comment = types.Comment

Core types from internal/types

type DatabaseInfo added in v0.17.0 

type DatabaseInfo = beads.DatabaseInfo

DatabaseInfo contains information about a beads database

func FindAllDatabases added in v0.17.0 

func FindAllDatabases() []DatabaseInfo

FindAllDatabases finds all beads databases in the system

type Dependency added in v0.12.0 

type Dependency = types.Dependency

Core types from internal/types

type DependencyCounts added in v0.22.1 

type DependencyCounts = types.DependencyCounts

Core types from internal/types

type DependencyType added in v0.12.0 

type DependencyType = types.DependencyType

Core types from internal/types

type EpicStatus added in v0.12.0 

type EpicStatus = types.EpicStatus

Core types from internal/types

type Event added in v0.12.0 

type Event = types.Event

Core types from internal/types

type EventType added in v0.12.0 

type EventType = types.EventType

Core types from internal/types

type Issue 

type Issue = types.Issue

Core types from internal/types

type IssueFilter added in v0.12.0 

type IssueFilter = types.IssueFilter

Core types from internal/types

type IssueType 

type IssueType = types.IssueType

Core types from internal/types

type IssueWithCounts added in v0.22.1 

type IssueWithCounts = types.IssueWithCounts

Core types from internal/types

type IssueWithDependencyMetadata added in v0.54.0 

type IssueWithDependencyMetadata = types.IssueWithDependencyMetadata

Core types from internal/types

type Label added in v0.12.0 

type Label = types.Label

Core types from internal/types

type RedirectInfo added in v0.39.1 

type RedirectInfo = beads.RedirectInfo

RedirectInfo contains information about a beads directory redirect

func GetRedirectInfo added in v0.39.1 

func GetRedirectInfo() RedirectInfo

GetRedirectInfo checks if the current beads directory is redirected. Returns RedirectInfo with IsRedirected=true if a redirect is active.

type SortPolicy added in v0.17.7 

type SortPolicy = types.SortPolicy

Core types from internal/types

type StaleFilter added in v0.22.1 

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 Open added in v0.51.0 

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

Open opens a Dolt-backed beads database at the given path. This always opens in embedded mode. Use OpenFromConfig to respect server mode settings from metadata.json.

func OpenFromConfig added in v0.53.0 

func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error)

OpenFromConfig opens a beads database using configuration from metadata.json. Unlike Open, this respects Dolt server mode settings and database name configuration, connecting to the Dolt SQL server when dolt_mode is "server". beadsDir is the path to the .beads directory.

type Transaction added in v0.24.5 

type Transaction = beads.Transaction

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

type TreeNode added in v0.12.0 

type TreeNode = types.TreeNode

Core types from internal/types

type WorkFilter 

type WorkFilter = types.WorkFilter

Core types from internal/types

Source Files

View all Source files

Directories

Path Synopsis
cmd
bd command
Package main provides the CommandContext struct that consolidates runtime state.
 Package main provides the CommandContext struct that consolidates runtime state.
bd/doctor
Package doctor provides health check and repair functionality for beads.
 Package doctor provides health check and repair functionality for beads.
bd/doctor/fix
bd/setup
examples
go-agent module
monitor-webui module
internal
audit
beads
Package beads provides a minimal public API for extending bd with custom orchestration.
 Package beads provides a minimal public API for extending bd with custom orchestration.
compact
Package compact provides AI-powered issue compaction using Claude Haiku.
 Package compact provides AI-powered issue compaction using Claude Haiku.
config
configfile
debug
doltserver
Package doltserver manages the lifecycle of a local dolt sql-server process.
 Package doltserver manages the lifecycle of a local dolt sql-server process.
formula
Package formula provides advice operators for step transformations.
 Package formula provides advice operators for step transformations.
git
gitlab
Package gitlab provides client and data types for the GitLab REST API.
 Package gitlab provides client and data types for the GitLab REST API.
hooks
Package hooks provides a hook system for extensibility.
 Package hooks provides a hook system for extensibility.
idgen
jira
Package jira provides client, types, and utilities for Jira integration.
 Package jira provides client, types, and utilities for Jira integration.
linear
Package linear provides client and data types for the Linear GraphQL API.
 Package linear provides client and data types for the Linear GraphQL API.
lockfile
molecules
Package molecules handles loading template molecules from molecules.jsonl catalogs.
 Package molecules handles loading template molecules from molecules.jsonl catalogs.
query
Package query implements a simple query language for filtering beads.
 Package query implements a simple query language for filtering beads.
recipes
Package recipes provides recipe-based configuration for bd setup.
 Package recipes provides recipe-based configuration for bd setup.
routing
storage
Package storage defines the interface for issue storage backends.
 Package storage defines the interface for issue storage backends.
storage/dolt
Package dolt implements the storage interface using Dolt (versioned MySQL-compatible database).
 Package dolt implements the storage interface using Dolt (versioned MySQL-compatible database).
storage/dolt/migrations
storage/doltutil
Package doltutil provides shared utilities for Dolt operations.
 Package doltutil provides shared utilities for Dolt operations.
telemetry
Package telemetry provides OpenTelemetry integration for beads.
 Package telemetry provides OpenTelemetry integration for beads.
templates/agents
Package agents provides embedded AGENTS.md templates for bd init and setup.
 Package agents provides embedded AGENTS.md templates for bd init and setup.
testutil
testutil/fixtures
Package fixtures provides realistic test data generation for benchmarks and tests.
 Package fixtures provides realistic test data generation for benchmarks and tests.
timeparsing
Package timeparsing provides layered time parsing for relative date/time expressions.
 Package timeparsing provides layered time parsing for relative date/time expressions.
tracker
Package tracker provides a plugin framework for external issue tracker integrations.
 Package tracker provides a plugin framework for external issue tracker integrations.
types
Package types defines core data structures for the bd issue tracker.
 Package types defines core data structures for the bd issue tracker.
ui
Package ui provides terminal styling for beads CLI output.
 Package ui provides terminal styling for beads CLI output.
utils
Package utils provides utility functions for issue ID parsing and resolution.
 Package utils provides utility functions for issue ID parsing and resolution.
validation
scripts
repro-dolt-hang command
repro-dolt-hang: Compare old vs new Dolt transaction patterns under concurrent load
 repro-dolt-hang: Compare old vs new Dolt transaction patterns under concurrent load

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.