Beads Task Tracker

Overview

Beads (v0.32.1+) is a git-versioned, dependency-aware issue tracker designed specifically for AI coding agents. It solves the "amnesia problem" where agents lose context between sessions by providing a persistent, queryable task database that agents can use to orient themselves, find ready work, and track dependencies across long-horizon projects.

Key Architecture:

•SQLite database (beads.db) for efficient local queries
•JSONL file (issues.jsonl) for git-based synchronization
•Hash-based IDs (e.g., bd-a1b2, bd-f14c) prevent merge conflicts in multi-agent workflows
•Daemon process maintains sync between database and JSONL

Use Beads when:

•Working on projects with multiple interconnected tasks
•Tasks span multiple agent sessions (>10 minutes)
•Need to track what work is blocked vs. ready
•Discovering new work during implementation that should be captured
•Multiple agents or machines are working on the same codebase
•Want to avoid the "markdown plan swamp" where plans become stale and disorganized

Installation Check

Before using Beads, verify the bd command is installed:

bash

bd version

If not installed, install via:

bash

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

Post-installation PATH setup:

After installation, if bd is not found in your PATH, add the Go bin directory to your shell profile:

For zsh (most macOS systems), add to ~/.zshrc:

bash

export PATH="$PATH:$HOME/go/bin"

For bash, add to ~/.bashrc or ~/.bash_profile:

bash

export PATH="$PATH:$HOME/go/bin"

Then reload your shell:

bash

source ~/.zshrc  # or source ~/.bashrc

Alternatively, you can use the full path /Users/[username]/go/bin/bd until PATH is configured.

Workflow Overview

1. Project Initialization

Initialize Beads in a project directory (only needed once per project):

bash

bd init

This creates a .beads/ directory with:

•issues.jsonl - Git-versioned source of truth
•*.db - Local SQLite cache (gitignored)

2. Creating Work

Create issues when starting new work or discovering tasks during implementation:

Basic creation:

bash

bd create "Task title" -d "Description" -p 1 -t task --json

Issue types:

•task - Standard work item (default)
•feature - New functionality
•bug - Defect to fix
•epic - Large body of work (parent to multiple tasks)
•chore - Maintenance work

Priority levels (0-4):

•0 - Critical/blocking
•1 - High priority
•2 - Medium priority (default)
•3 - Low priority
•4 - Nice to have

Creating from markdown file:

bash

bd create -f plan.md --json

Format: ## Issue Title creates new issue, with optional sections ### Priority, ### Type, ### Description, ### Dependencies

Add labels for organization:

bash

bd create "Add auth" -l "backend,security,p1" --json

3. Managing Dependencies

Link related work to establish ordering and track blockers:

Add dependency:

bash

# Format: bd dep add <dependent> <blocker>
bd dep add bd-5 bd-3  # bd-5 depends on bd-3 completing first

Dependency types:

•blocks (default) - Hard blocker; dependent cannot start until blocker closes
•
parent-child - Hierarchical relationship (child depends on parent)
bash
```
bd dep add bd-task bd-epic --type parent-child
```
•
discovered-from - Issue found during work on another issue
bash
```
bd dep add bd-new bd-current --type discovered-from
```
•related - Soft connection; issues are related but not blocking

Visualize dependencies:

bash

bd dep tree bd-42 --json

Detect cycles:

bash

bd dep cycles --json

Cycles break ready work detection and must be resolved.

4. Finding Ready Work

Query for actionable work with no open blockers:

bash

# All ready work
bd ready --json

# Filter by priority
bd ready --priority 1 --json

# Filter by labels
bd ready --label backend --json

# Limit results
bd ready --limit 5 --json

Finding Recent/Latest Tasks

IMPORTANT: When starting a session, always check for the latest/highest-numbered tasks first, as these typically represent the most recent work and current priorities.

View recent tasks sorted by ID (descending):

bash

# List all open tasks, sorted by ID number (highest/newest first)
bd list --status open --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -20

# Show full details of highest-numbered tasks
bd list --status open --json | jq 'sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[0:10]'

# Find tasks in a specific number range (e.g., 120-150)
bd list --json | jq '[.[] | select(.id | test("Twilio-Aldea-1[2-5][0-9]"))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[] | {id, title, status, priority}'

Example workflow at session start:

bash

# 1. First, check what the highest task numbers are
HIGHEST=$(bd list --json | jq -r '.[].id' | grep -oE '[0-9]+$' | sort -n | tail -1)
echo "Highest task number: $HIGHEST"

# 2. View tasks in the recent range (e.g., last 30 tasks)
RANGE_START=$((HIGHEST - 30))
bd list --json | jq --arg start "$RANGE_START" '[.[] | select(.id | test(".*-([0-9]+)$") and (.id | match(".*-([0-9]+)$").captures[0].string | tonumber) >= ($start | tonumber))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse'

# 3. Find ready work among recent tasks
bd ready --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -10

Why check recent tasks first:

•Most recent work is usually the current focus
•Recent tasks often have the freshest context
•Prevents overlooking newly-created high-priority work
•Helps identify what was worked on most recently

At session start, always:

•Check the highest task numbers to understand the current work range
•List recent tasks (highest 20-30 IDs) to see current focus areas
•Run bd ready --json to find unblocked work, prioritizing recent tasks
•Choose highest-priority ready issue (preferring recent tasks when priorities are equal)
•Update status to in_progress before starting work

5. Working and Updating

Update issue status as work progresses:

Start work:

bash

bd update bd-42 --status in_progress --json

Valid statuses:

•open - Not started
•in_progress - Currently being worked on
•closed - Completed

Update other fields:

bash

bd update bd-42 --priority 0 --json
bd update bd-42 --assignee alice --json

Close completed work:

bash

bd close bd-42 --reason "Implementation complete, tests passing" --json

6. Discovery During Work

When discovering new work during implementation:

bash

# 1. Create the discovered issue
NEW_ID=$(bd create "Fix discovered bug in auth" -t bug -p 1 --json | jq -r '.id')

# 2. Link back to parent work
bd dep add $NEW_ID bd-current --type discovered-from --json

# 3. Decide: handle now or defer?
# If blocking current work: switch to new issue
# If not blocking: continue current work, new issue will show in bd ready

7. Querying and Inspection

List issues with filters:

bash

bd list --status open --json
bd list --priority 1 --json
bd list --label backend,urgent --json  # AND: must have ALL
bd list --label-any frontend,backend --json  # OR: at least one

Show full issue details:

bash

bd show bd-42 --json

View blocked issues:

bash

bd blocked --json

Project statistics:

bash

bd stats --json

JSON Output Parsing

Always use --json flag for programmatic access. Parse with jq:

bash

# Get first ready issue
ISSUE=$(bd ready --json | jq -r '.[0]')
ISSUE_ID=$(echo "$ISSUE" | jq -r '.id')
ISSUE_TITLE=$(echo "$ISSUE" | jq -r '.title')

# Check if any ready work exists
READY_COUNT=$(bd ready --json | jq 'length')
if [ "$READY_COUNT" -eq 0 ]; then
  echo "No ready work. Check blocked issues:"
  bd blocked --json
fi

# Get highest task number and list recent tasks
HIGHEST=$(bd list --json | jq -r 'max_by(.id | sub(".*-"; "") | tonumber) | .id | sub(".*-"; "")')
echo "Highest task: #$HIGHEST"
bd list --json | jq --arg num "$HIGHEST" '[.[] | select((.id | sub(".*-"; "") | tonumber) >= (($num | tonumber) - 20))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[] | {id, title, status, priority}'

Best Practices

DO:

•Initialize Beads at project start (bd init)
•Create issues for discovered work instead of informal notes
•Use dependencies to model task relationships
•Query bd ready at session start to orient yourself
•Close issues with descriptive reasons
•Use labels to categorize work (e.g., backend, frontend, urgent)
•Commit .beads/issues.jsonl to git (auto-exported after changes)

DON'T:

•Create circular dependencies (use bd dep cycles to detect)
•Skip updating status (stale statuses confuse ready work detection)
•Forget to link discovered work back to parent issues
•Use markdown files for task tracking when Beads is available
•Ignore blocked issues indefinitely (reassess dependencies)

Multi-Session Workflow Pattern

Session 1 - Starting fresh:

bash

# 1. Check for ready work
bd ready --json

# 2. If no ready work, check what's blocked
bd blocked --json

# 3. Start working on highest-priority ready issue
bd update bd-5 --status in_progress --json

# 4. During work, discover new issue
bd create "Fix validation bug" -t bug -p 0 --json
bd dep add bd-new bd-5 --type discovered-from --json

# 5. Complete original work
bd close bd-5 --reason "Feature implemented" --json

Session 2 - Agent resumes (different session, possibly different day):

bash

# 1. Check ready work (newly created bd-new is now ready)
bd ready --json

# 2. See discovered issue from previous session
# 3. Continue work seamlessly without context loss
bd update bd-new --status in_progress --json

Quick Reference

See references/quick-reference.md for a comprehensive command cheat sheet.

For workflow patterns and advanced usage, see references/workflow-patterns.md.

Built-in Help

Beads includes an interactive quickstart guide:

bash

bd quickstart

Run this to see comprehensive examples and workflows.

Integration with Project Documentation

Add to AGENTS.md or CLAUDE.md:

markdown

## Task Tracking with Beads

We track implementation work using Beads (`bd`), a dependency-aware issue tracker. Use `bd ready --json` to see unblocked work, `bd create` to add tasks, and `bd update <id> --status in_progress` to claim work. Run `bd quickstart` for full documentation.

Resources

This skill includes reference documentation to support effective Beads usage:

references/

•quick-reference.md - Command cheat sheet organized by category
•workflow-patterns.md - Common patterns and best practices for agent workflows