c78889fa65
Pre-commit and post-merge git hooks were unconditionally running bd sync/import for JSONL sync, which fails with Dolt backend. Now both hooks check metadata.json for backend type and exit early if Dolt is configured. Dolt uses its own sync mechanism. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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/FreeBSD)
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. |
🔗 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 --contributorto 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 maintainerif 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.
