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

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

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