beads

README

bd - Beads Issue Tracker 🔗

Give your coding agent a memory upgrade

🚨 CRITICAL: SOLO WORKFLOWS ONLY UNTIL 1.0.0 🚨

DO NOT USE BEADS FOR MULTI-REPO OR MULTI-CLONE WORKFLOWS.

Beads has critical bugs when used across multiple clones or repositories. The import collision resolution system incorrectly treats normal updates as conflicts, creating duplicate issues and database corruption.

What works: ✅ Single developer, single clone, solo agent workflows
What's broken: ❌ Multiple clones, multiple agents, team workflows

While AI agents can resolve collisions, it's painful and error-prone. We're working on a complete rearchitecture using hash-based IDs to eliminate these issues.

Use Beads for solo projects only. Multi-repo support will be available in 1.0.0.

⚠️ Alpha Status: This project is in active development. The core features work well, but expect API changes before 1.0. Use for development/internal projects first.

Beads is a lightweight memory system for coding agents, using a graph-based issue tracker. Four kinds of dependencies work to chain your issues together like beads, making them easy for agents to follow for long distances, and reliably perform complex task streams in the right order.

Drop Beads into any project where you're using a coding agent, and you'll enjoy an instant upgrade in organization, focus, and your agent's ability to handle long-horizon tasks over multiple compaction sessions. Your agents will use issue tracking with proper epics, rather than creating a swamp of rotten half-implemented markdown plans.

Instant start:

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

Then tell your coding agent to start using the bd tool instead of markdown for all new work, somewhere in your AGENTS.md or CLAUDE.md. That's all there is to it!

You don't use Beads directly as a human. Your coding agent will file and manage issues on your behalf. They'll file things they notice automatically, and you can ask them at any time to add or update issues for you.

Beads gives agents unprecedented long-term planning capability, solving their amnesia when dealing with complex nested plans. They can trivially query the ready work, orient themselves, and land on their feet as soon as they boot up.

Agents using Beads will no longer silently pass over problems they notice due to lack of context space -- instead, they will automatically file issues for newly-discovered work as they go. No more lost work, ever.

Beads issues are backed by git, but through a clever design it manages to act like a managed, centrally hosted SQL database shared by all of the agents working on a project (repo), even across machines.

Beads even improves work auditability. The issue tracker has a sophisticated audit trail, which agents can use to reconstruct complex operations that may have spanned multiple sessions.

Agents report that they enjoy working with Beads, and they will use it spontaneously for both recording new work and reasoning about your project in novel ways. Whether you are a human or an AI, Beads lets you have more fun and less stress with agentic coding.

Features

• ✨ Zero setup - bd init creates project-local database (and your agent will do it)
• 🔗 Dependency tracking - Four dependency types (blocks, related, parent-child, discovered-from)
• 📋 Ready work detection - Automatically finds issues with no open blockers
• 🤖 Agent-friendly - --json flags for programmatic integration
• 📦 Git-versioned - JSONL records stored in git, synced across machines
• 🌍 Distributed by design - Agents on multiple machines share one logical database via git
• 🏗️ Extensible - Add your own tables to the SQLite database
• 🔍 Multi-project isolation - Each project gets its own database, auto-discovered by directory
• 🌲 Dependency trees - Visualize full dependency graphs
• 🎨 Beautiful CLI - Colored output for humans, JSON for bots
• 💾 Full audit trail - Every change is logged
• ⚡ High performance - Batch operations for bulk imports (1000 issues in ~950ms)
• 🗜️ Memory decay - Semantic compaction gracefully reduces old closed issues

Installation

Quick install (all platforms):

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

Homebrew (macOS/Linux):

brew tap steveyegge/beads
brew install bd

Other platforms and methods: See INSTALLING.md for Windows, Arch Linux, and manual installation.

IDE Integration: See INSTALLING.md for Claude Code plugin and MCP server setup.

Quick Start

For Humans

Beads is designed for AI coding agents to use on your behalf. Setup takes 30 seconds:

You run this once (humans only):

# In your project root:
bd init

# bd will:
# - Create .beads/ directory with database
# - Import existing issues from git (if any)
# - Prompt to install git hooks (recommended: say yes)
# - Auto-start daemon for sync

# Then tell your agent about bd:
echo "BEFORE ANYTHING ELSE: run 'bd onboard' and follow the instructions" >> AGENTS.md

Your agent does the rest: Next time your agent starts, it will:

1. Run bd onboard and receive integration instructions
2. Add bd workflow documentation to AGENTS.md
3. Update CLAUDE.md with a note (if present)
4. Remove the bootstrap instruction

For agents setting up repos: Use bd init --quiet for non-interactive setup (auto-installs git hooks, no prompts).

For new repo clones: Run bd init (or bd init --quiet for agents) to import existing issues from .beads/issues.jsonl automatically.

Most tasks will be created and managed by agents during conversations. You can check on things with:

bd list                  # See what's being tracked
bd show <issue-id>       # Review a specific issue
bd ready                 # See what's ready to work on
bd dep tree <issue-id>   # Visualize dependencies

For AI Agents

Run the interactive guide to learn the full workflow:

bd quickstart

Quick reference for agent workflows:

# Find ready work
bd ready --json | jq '.[0]'

# Create issues during work
bd create "Discovered bug" -t bug -p 0 --json

# Link discovered work back to parent
bd dep add <new-id> <parent-id> --type discovered-from

# Update status
bd update <issue-id> --status in_progress --json

# Complete work
bd close <issue-id> --reason "Implemented" --json

The Magic: Distributed Database via Git

Here's the crazy part: bd acts like a centralized database, but it's actually distributed via git.

When you install bd on any machine with your project repo, you get:

• ✅ Full query capabilities (dependencies, ready work, etc.)
• ✅ Fast local operations (<100ms via SQLite)
• ✅ Shared state across all machines (via git)
• ✅ No server, no daemon required, no configuration
• ✅ AI-assisted merge conflict resolution

How it works: Each machine has a local SQLite cache (.beads/*.db, gitignored). Source of truth is JSONL (.beads/issues.jsonl, committed to git). Auto-sync keeps them in sync: SQLite → JSONL after CRUD operations (5-second debounce), JSONL → SQLite when JSONL is newer (e.g., after git pull).

The result: Agents on your laptop, your desktop, and your coworker's machine all query and update what feels like a single shared database, but it's really just git doing what git does best - syncing text files across machines.

No PostgreSQL instance. No MySQL server. No hosted service. Just install bd, clone the repo, and you're connected to the "database."

Git Workflow & Auto-Sync

bd automatically syncs your local database with git:

Making changes (auto-export):

bd create "Fix bug" -p 1
bd update bd-42 --status in_progress
# bd automatically exports to .beads/issues.jsonl after 5 seconds

git add .beads/issues.jsonl
git commit -m "Working on bd-42"
git push

Pulling changes (auto-import):

git pull
# bd automatically detects JSONL is newer and imports on next command

bd ready  # Fresh data from git!
bd list   # Shows issues from other machines

Manual sync (optional):

bd sync  # Immediately flush pending changes and import latest JSONL

For zero-lag sync, install the git hooks:

cd examples/git-hooks && ./install.sh

This adds:

• pre-commit - Immediate flush before commit (no 5-second wait)
• post-merge - Guaranteed import after git pull or git merge

Disable auto-sync if needed:

bd --no-auto-flush create "Issue"   # Skip auto-export
bd --no-auto-import list            # Skip auto-import check

Usage

Creating Issues

bd create "Fix bug" -d "Description" -p 1 -t bug
bd create "Add feature" --description "Long description" --priority 2 --type feature
bd create "Task" -l "backend,urgent" --assignee alice

# Get JSON output for programmatic use
bd create "Fix bug" -d "Description" --json

# Create multiple issues from a markdown file
bd create -f feature-plan.md

Options:

• -f, --file - Create multiple issues from markdown file
• -d, --description - Issue description
• -p, --priority - Priority (0-4, 0=highest, default=2)
• -t, --type - Type (bug|feature|task|epic|chore, default=task)
• -a, --assignee - Assign to user
• -l, --labels - Comma-separated labels
• --id - Explicit issue ID (e.g., worker1-100 for ID space partitioning)
• --json - Output in JSON format

Viewing Issues

bd info                                    # Show database path and daemon status
bd show bd-1                               # Show full details
bd list                                    # List all issues
bd list --status open                      # Filter by status
bd list --priority 1                       # Filter by priority
bd list --assignee alice                   # Filter by assignee
bd list --label=backend,urgent             # Filter by labels (AND)
bd list --label-any=frontend,backend       # Filter by labels (OR)

# JSON output for agents
bd info --json
bd list --json
bd show bd-1 --json

Updating Issues

bd update bd-1 --status in_progress
bd update bd-1 --priority 2
bd update bd-1 --assignee bob
bd close bd-1 --reason "Completed"
bd close bd-1 bd-2 bd-3   # Close multiple

# JSON output
bd update bd-1 --status in_progress --json

Dependencies

# Add dependency (bd-2 depends on bd-1)
bd dep add bd-2 bd-1
bd dep add bd-3 bd-1 --type blocks

# Remove dependency
bd dep remove bd-2 bd-1

# Show dependency tree
bd dep tree bd-2

# Detect cycles
bd dep cycles

Dependency Types

• blocks: Hard blocker (default) - issue cannot start until blocker is resolved
• related: Soft relationship - issues are connected but not blocking
• parent-child: Hierarchical relationship (child depends on parent)
• discovered-from: Issue discovered during work on another issue

Only blocks dependencies affect ready work detection.

Finding Work

# Show ready work (no blockers)
bd ready
bd ready --limit 20
bd ready --priority 1
bd ready --assignee alice

# Sort policies (hybrid is default)
bd ready --sort priority    # Strict priority order (P0, P1, P2, P3)
bd ready --sort oldest      # Oldest issues first (backlog clearing)
bd ready --sort hybrid      # Recent by priority, old by age (default)

# Show blocked issues
bd blocked

# Statistics
bd stats

# JSON output for agents
bd ready --json

Labels

Add flexible metadata to issues for filtering and organization:

# Add labels during creation
bd create "Fix auth bug" -t bug -p 1 -l auth,backend,urgent

# Add/remove labels
bd label add bd-42 security
bd label remove bd-42 urgent

# List labels
bd label list bd-42              # Labels on one issue
bd label list-all                # All labels with counts

# Filter by labels
bd list --label backend,auth     # AND: must have ALL labels
bd list --label-any frontend,ui  # OR: must have AT LEAST ONE

See LABELS.md for complete label documentation and best practices.

Deleting Issues

# Single issue deletion (preview mode)
bd delete bd-1

# Force single deletion
bd delete bd-1 --force

# Batch deletion
bd delete bd-1 bd-2 bd-3 --force

# Delete from file (one ID per line)
bd delete --from-file deletions.txt --force

# Cascade deletion (recursively delete dependents)
bd delete bd-1 --cascade --force

The delete operation removes all dependency links, updates text references to [deleted:ID], and removes the issue from database and JSONL.

Configuration

Manage per-project configuration for external integrations:

# Set configuration
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"

# Get configuration
bd config get jira.url

# List all configuration
bd config list --json

# Unset configuration
bd config unset jira.url

See CONFIG.md for complete configuration documentation.

Compaction (Memory Decay)

Beads uses AI to compress old closed issues, keeping databases lightweight as they age:

bd compact --dry-run --all  # Preview candidates
bd compact --days 90        # Compact closed issues older than 90 days

This is agentic memory decay - your database naturally forgets fine-grained details while preserving essential context.

Export/Import

# Export to JSONL (automatic by default)
bd export -o issues.jsonl

# Import from JSONL (automatic when JSONL is newer)
bd import -i issues.jsonl

# Manual sync
bd sync

Note: Auto-sync is enabled by default. Manual export/import is rarely needed.

Managing Daemons

bd runs a background daemon per workspace for auto-sync and RPC operations. Use bd daemons to manage multiple daemons:

# List all running daemons
bd daemons list

# Check health (version mismatches, stale sockets)
bd daemons health

# Stop a specific daemon
bd daemons stop /path/to/workspace
bd daemons stop 12345  # By PID

# View daemon logs
bd daemons logs /path/to/workspace -n 100
bd daemons logs 12345 -f  # Follow mode

# Stop all daemons
bd daemons killall
bd daemons killall --force  # Force kill if graceful fails

Common use cases:

• After upgrading bd: Run bd daemons health to check for version mismatches, then bd daemons killall to restart all daemons with the new version
• Debugging: Use bd daemons logs <workspace> to view daemon logs
• Cleanup: bd daemons list auto-removes stale sockets

See commands/daemons.md for complete documentation.

Examples

Check out the examples/ directory for:

• Python agent - Full agent implementation in Python
• Bash agent - Shell script agent example
• Git hooks - Automatic export/import on git operations
• Branch merge workflow - Handle ID collisions when merging branches
• Claude Desktop MCP - MCP server for Claude Desktop
• Claude Code Plugin - One-command installation with slash commands

Advanced Features

For advanced usage, see:

• ADVANCED.md - Prefix renaming, merging duplicates, daemon configuration
• CONFIG.md - Configuration system for integrations
• EXTENDING.md - Database extension patterns
• ADVANCED.md - JSONL format and merge strategies

Documentation

• README.md - You are here! Core features and quick start
• INSTALLING.md - Complete installation guide for all platforms
• QUICKSTART.md - Interactive tutorial (bd quickstart)
• FAQ.md - Frequently asked questions
• TROUBLESHOOTING.md - Common issues and solutions
• ADVANCED.md - Advanced features and use cases
• LABELS.md - Complete label system guide
• CONFIG.md - Configuration system
• EXTENDING.md - Database extension patterns
• ADVANCED.md - JSONL format analysis
• PLUGIN.md - Claude Code plugin documentation
• CONTRIBUTING.md - Contribution guidelines
• SECURITY.md - Security policy

Community & Ecosystem

Third-Party Tools

• Beadster - Native macOS app for viewing and managing bd issues across multiple projects. Features a compact, always-on-top window for quick reference during development. Built by @podviaznikov.

Have you built something cool with bd? Open an issue to get it featured here!

Development

# Run tests
go test ./...

# Build
go build -o bd ./cmd/bd

# Run
./bd create "Test issue"

# Bump version
./scripts/bump-version.sh 0.9.3           # Update all versions, show diff
./scripts/bump-version.sh 0.9.3 --commit  # Update and auto-commit

See scripts/README.md for more development scripts.

License

MIT

Credits

Built with ❤️ by developers who love tracking dependencies and finding ready work.

Inspired by the need for a simpler, dependency-aware issue tracker.

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 EXTENDING.md.

Index

• Constants
• Variables
• func ComputeRepoID() (string, error)
• func FindDatabasePath() string
• func FindJSONLPath(dbPath string) string
• func GetCloneID() (string, error)
• type BlockedIssue
• type Comment
• type DatabaseInfo
  • func FindAllDatabases() []DatabaseInfo
• type Dependency
• type DependencyType
• type EpicStatus
• type Event
• type EventType
• type Issue
• type IssueFilter
• type IssueType
• type Label
• type SortPolicy
• type Statistics
• type Status
• type Storage
  • func NewSQLiteStorage(dbPath string) (Storage, error)
• type TreeNode
• type WorkFilter

Constants

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

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

const CanonicalDatabaseName = "beads.db"

CanonicalDatabaseName is the required database filename for all beads repositories

Variables

var LegacyDatabaseNames = []string{"bd.db", "issues.db", "bugs.db"}

LegacyDatabaseNames are old names that should be migrated

Functions

func ComputeRepoID

func ComputeRepoID() (string, error)

ComputeRepoID generates a unique identifier for this git repository

func FindDatabasePath

func FindDatabasePath() string

FindDatabasePath discovers the bd database path using bd's standard search order:

1. $BEADS_DB environment variable
2. .beads/*.db in current directory or ancestors

Returns empty string if no database is found.

func FindJSONLPath

func FindJSONLPath(dbPath string) string

FindJSONLPath returns the expected JSONL file path for the given database path. It searches for existing *.jsonl files in the database directory and returns the first one found, or defaults to "issues.jsonl".

This function does not create directories or files - it only discovers paths. Use this when you need to know where bd stores its JSONL export.

func GetCloneID

func GetCloneID() (string, error)

GetCloneID generates a unique ID for this specific clone (not shared with other clones)

Types

type BlockedIssue

type BlockedIssue = types.BlockedIssue

BlockedIssue represents an issue with blocking dependencies.

type Comment

type Comment = types.Comment

Comment represents a user comment on an issue.

type DatabaseInfo

type DatabaseInfo struct {
	Path       string // Full path to the .db file
	BeadsDir   string // Parent .beads directory
	IssueCount int    // Number of issues (-1 if unknown)
}

DatabaseInfo contains information about a discovered beads database

func FindAllDatabases

func FindAllDatabases() []DatabaseInfo

FindAllDatabases scans the directory hierarchy for all .beads directories Returns a slice of DatabaseInfo for each database found, starting from the closest to CWD (most relevant) to the furthest (least relevant).

type Dependency

type Dependency = types.Dependency

Dependency represents a relationship between issues.

type DependencyType

type DependencyType = types.DependencyType

DependencyType represents the type of dependency (blocks, related, parent-child, discovered-from).

type EpicStatus

type EpicStatus = types.EpicStatus

EpicStatus represents the status of an epic issue.

type Event

type Event = types.Event

Event represents an audit log event.

type EventType

type EventType = types.EventType

EventType represents the type of audit event.

type Issue

type Issue = types.Issue

Issue represents a tracked work item with metadata, dependencies, and status.

type IssueFilter

type IssueFilter = types.IssueFilter

IssueFilter represents filtering criteria for issue queries.

type IssueType

type IssueType = types.IssueType

IssueType represents the type of issue (bug, feature, task, epic, chore).

type Label

type Label = types.Label

Label represents a tag attached to an issue.

type SortPolicy

type SortPolicy = types.SortPolicy

SortPolicy determines how ready work is ordered.

type Statistics

type Statistics = types.Statistics

Statistics represents project-wide metrics.

type Status

type Status = types.Status

Status represents the current state of an issue (open, in progress, closed, blocked).

type Storage

type Storage = storage.Storage

Storage provides the minimal interface for extension orchestration

func NewSQLiteStorage

func NewSQLiteStorage(dbPath string) (Storage, error)

NewSQLiteStorage opens a bd SQLite database for programmatic access. Most extensions should use this to query ready work and update issue status.

type TreeNode

type TreeNode = types.TreeNode

TreeNode represents a node in a dependency tree.

type WorkFilter

type WorkFilter = types.WorkFilter

WorkFilter represents filtering criteria for work queries.