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