Track issues with dependencies and let graph analysis guide your work.
What Is Beads?
Beads is a graph-aware issue tracking system designed for agent workflows. It tracks dependencies between tasks and uses graph algorithms to tell you what to work on next.
BV (Beads Viewer) is the TUI and CLI for working with Beads. It provides both interactive views and machine-readable outputs for agents.
Dependency Tracking
Issues can block other issues
Graph Metrics
PageRank, betweenness, critical path
Smart Triage
Know what to work on next
Git Integration
All data lives in .beads/
Core bd Commands
bd is the CLI for managing Beads issues:
bv—it launches a TUI. Use bv --robot-* flags for agent output.BV Robot Commands
BV provides machine-readable outputs with precomputed graph metrics:
bv --robot-triageTHE mega-command: recommendations, quick wins, blockers to clear
bv --robot-nextJust the single top pick + claim command
bv --robot-planParallel execution tracks with unblocks lists
bv --robot-insightsFull graph metrics
Issue Types & Priorities
Types
bugSomething brokenfeatureNew functionalitytaskWork to doepicLarge initiativechoreMaintenancePriorities (0-4)
The Agent Workflow
bd readyFind unblocked work
bd show <id>Review issue details
bd update --status=in_progressClaim the work
Implement + testDo the actual work
bd close <id>Mark complete
bd syncSync with remote
Understanding Graph Metrics
BV calculates graph metrics to help prioritize work:
PageRank
How central is this issue? High PageRank = many things depend on it
→ Focus on high PageRank blockers first
Betweenness
How often does this issue sit on critical paths?
→ Clearing high betweenness issues unblocks the most work
Critical Path
The longest chain of dependencies
→ Prioritize work on the critical path to reduce total time
Cycles
Circular dependencies (A blocks B, B blocks A)
→ Must be resolved—they create deadlocks
Best Practices
Start with bd ready
Find work that has no blockers—you can start immediately
Use bd dep add for dependencies
Explicit dependencies enable smart prioritization
Claim work with --status=in_progress
Prevents duplicate work by other agents
Close issues promptly
Unblocks dependent work faster
Run bd sync at session end
Keeps .beads/ in sync across agents and machines
.beads/ with your code changes. It's the authoritative source of truth for issue state.Try It Now
1# See what's ready to work on2$ bd ready34# Get smart triage recommendations5$ bv --robot-triage | jq '.quick_ref'67# Create a task8$ bd create "Add login page" -t feature -p 2910# Start working on it11$ bd update bd-1 --status=in_progress1213# Sync when done14$ bd sync