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)
```
bd dep add bd-task bd-epic --type parent-child
```

discovered-from - Issue found during work on another issue

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:

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:

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

beads-task-tracker