23dccff03a
When .beads/redirect points to another location that crosses directory boundaries, isExternalBeadsDir() can return true even when both paths are in the same git repo. Previously, this would trigger the direct commit mode, bypassing the configured sync.branch workflow. Now we check hasSyncBranchConfig before entering the external path. When sync.branch is configured, we skip direct-commit mode and use the sync.branch worktree workflow instead, which properly handles copying JSONL files regardless of where the source .beads lives. 🤖 Generated with [Claude Code](https://claude.com/claude-code) 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)
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.
📦 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
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.
