Skip to content

Beads Integration

Persistent cross-session issue tracking with dependency-aware work detection.

Beads is a distributed, git-backed issue tracker designed for AI agent workflows. When enabled, it provides persistent task tracking that survives conversation clearing and session boundaries.

When to Use

Enable Beads when the project:

  • Has multi-session development where TodoWrite items get lost between conversations
  • Needs dependency-aware task management (what's blocked, what's ready)
  • Uses parallel reviewers that need collision-safe finding tracking
  • Benefits from cross-session incident tracking in production
  • Has complex feature work where discovered issues need parent-child linking

Skip if the project is a quick prototype, single-session task, or already uses an external issue tracker (Jira, Linear, GitHub Issues) as source of truth.

Setup

Option A: During bootstrap

Run /1-bootstrap and accept the "Issue Tracking with Beads" prompt. This runs:

bd init --quiet          # Initialize .beads/ directory
bd hooks install         # Add git hooks for auto-sync

And adds to .gitignore: 

.beads/beads.db
.beads/bd.sock
.beads/*.log

The .beads/issues.jsonl and .beads/deletions.jsonl files are git-tracked (they are the distributed source of truth).

Option B: Manual setup

Install the Beads CLI (bd) and run bd init in any project directory. The workflow detects .beads/ automatically — no configuration flag needed.

Prerequisites

Install Beads CLI via one of:

# npm
npm install -g beads-cli

# Homebrew
brew install beads

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

Detection

Every phase checks: does .beads/issues.jsonl exist? If yes, Beads steps activate. If no, the workflow behaves exactly as before.

Per-Phase Behavior

Phase 0: Start

Detects .beads/ and reports status: 

✓ Beads issue tracker active. Cross-session issue tracking enabled.

Phase 1: Bootstrap

Offers optional Beads initialization with bd init --quiet && bd hooks install.

Phase 3: Build

The implementation orchestrator:

  1. Runs bd prime at session start to inject compact context (~1-2k tokens)
  2. Runs bd ready --json to find unblocked work items
  3. Sets issues to in_progress when work begins
  4. Creates discovered-from issues when bugs are found during implementation
  5. Closes issues when work completes

Phase 4: Review

After the quality gate decision, creates Beads issues for review findings:

  • Critical/High findings → Beads issues with priority 0-1 and review label
  • Medium findings → Beads issues with priority 2 and review label
  • Low findings → Not tracked (too noisy)

This ensures review findings survive conversation clearing between review and fix cycles.

Phase Checkpoint

When writing .claude-checkpoint.md, includes a "Ready Work" section with the top 5 unblocked Beads issues. The next session can immediately see actionable items.

Phase 6: Operate

The incident orchestrator creates structured incident issues:

bd create "[SEV-1] Production outage" --type bug --priority 0 --label incident,sev-1

Hotfix work links via discovered-from, and post-mortem action items become follow-up issues with the post-mortem label.

CLI Cheat Sheet

Command Purpose
bd init --quiet Initialize in project root
bd prime Inject session context (~1-2k tokens)
bd ready Show unblocked work items
bd create "Title" --type bug -p 1 Create an issue (types: bug, feature, task, epic, chore)
bd update <id> --status in_progress Start working on an issue
bd close <id> --reason "Done" Close with resolution
bd list --status open List open issues
bd dep add <from> <to> Add dependency
bd dep tree <id> Visualize dependency tree
bd sync Force immediate git sync
bd hooks install Install git hooks for auto-sync

Priority Levels

Priority Meaning
0 Critical (SEV-1 incidents, security vulnerabilities)
1 High (must fix before deploy)
2 Medium (should fix soon)
3 Low (backlog)
4 Backlog (someday/maybe)

Dependency Types

Type Use For
blocks Hard dependency — prevents work from starting
related Soft relationship between issues
parent-child Epics with sub-tasks
discovered-from Issues found while working on another issue

Relationship to Other Toolkit Mechanisms

Beads complements (does not replace) existing toolkit mechanisms:

Mechanism Purpose Beads Relationship
Session Journal Captures decisions and learnings Different concern — journal = knowledge, Beads = work items
Compound-docs Documents solved problems Complementary — Beads tracks open issues, compound-docs records solutions
Phase Checkpoint Workflow state between phases Enhanced — checkpoint includes Beads ready work summary
file-todos Development task tracking Superseded — Beads provides the same data with better queries and dependency resolution
Continuous Learning Pattern detection Complementary — recurring Beads issues could inform pattern detection