Beads Task Tracker

Overview

Beads 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.

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:

bd version

If not installed, install via:

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:

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

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

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

Then reload your shell:

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):

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:

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:

bd create -f plan.md --json

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

Add labels for organization:

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

3. Managing Dependencies

Link related work to establish ordering and track blockers:

Add dependency:

# 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)
  bashCopy

  bd dep add bd-task bd-epic --type parent-child
  

• discovered-from - Issue found during work on another issue
  bashCopy

  bd dep add bd-new bd-current --type discovered-from
  

• related - Soft connection; issues are related but not blocking

Visualize dependencies:

bd dep tree bd-42 --json

Detect cycles:

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:

# 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):

# 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:

# 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:

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

5. Working and Updating

Update issue status as work progresses:

Start work:

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

Valid statuses:

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

Update other fields:

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

Close completed work:

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

6. Discovery During Work

When discovering new work during implementation:

# 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:

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:

bd show bd-42 --json

View blocked issues:

bd blocked --json

Project statistics:

bd stats --json

JSON Output Parsing

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

# 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:

# 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):

# 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:

bd quickstart

Run this to see comprehensive examples and workflows.

Integration with Project Documentation

Add to AGENTS.md or CLAUDE.md:

## 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