Skip to main content
Beads includes a comprehensive dependency system for ordering work, tracking relationships, and managing external conditions through gates.

​
Adding Dependencies

Create a dependency relationship between two issues: 
# issue-2 depends on issue-1 (issue-1 blocks issue-2)
bd dep add issue-2 issue-1
When issue-1 is open, issue-2 won’t appear in bd ready. Once issue-1 closes, issue-2 unblocks automatically.

​
Removing Dependencies

bd dep remove issue-2 issue-1
bd dep rm issue-2 issue-1        # alias

​
Dependency Types

Dependencies have a type that determines whether they block work:

​
Blocking Types

These affect what appears in bd ready:
TypeMeaningExample Use Case
blocks (default)B cannot start until A closesSequential task ordering
parent-childChildren blocked when parent blockedEpic hierarchies
conditional-blocksB runs only if A failsError handling paths
waits-forB waits for all of A’s childrenFanout aggregation
# Task ordering - implement before testing
bd dep add test-feature implement-feature

​
Non-Blocking Types

These are graph annotations only (informational):
TypeMeaningWhen to Use
relatedInformational linkRelated context
tracksProgress trackingMonitor another issue
discovered-fromFound during workSide quests, bugs found
caused-byRoot cause linkLink bug to cause
validatesTest or verificationLink test to feature
supersedesReplaces another issueDuplicate resolution
# Found a bug while working on feature
bd create "Fix auth timeout" -t bug -p 1 \
  --deps discovered-from:bd-a1b2

​
Finding Ready Work

bd ready shows issues with no open blocking dependencies: 
bd ready
An issue is ready when ALL of its blocking dependencies are closed.

​
Example Output

📋 Ready work (3 issues with no blockers):

1. [P0] bd-a1b2: Set up database schema
   Priority: 0 | Type: task | Created: 2 days ago

2. [P1] bd-c3d4: Add authentication
   Priority: 1 | Type: feature | Created: 1 day ago

3. [P1] bd-e5f6: Write integration tests
   Priority: 1 | Type: task | Created: 3 hours ago

​
Viewing Blocked Issues

See what’s blocked and why: 
bd blocked
Shows every blocked issue and what blocks it. Use after closing an issue to see what just unblocked.

​
Example Output

🚧 Blocked issues (2):

bd-g7h8: Deploy to production
  Blocked by:
  - bd-a1b2: Set up database schema [open]
  - bd-c3d4: Add authentication [in_progress]

bd-i9j0: Update documentation
  Blocked by:
  - bd-e5f6: Write integration tests [open]

​
Visualizing Dependencies

​
Dependency Tree

View hierarchical dependency structure: 
bd dep tree issue-id

​
Dependency Graph

Visualize the entire dependency graph: 
bd graph issue-id                        # Single issue DAG
bd graph --all                           # All open issues
The graph organizes issues into layers:
  • Layer 0: No dependencies (can start immediately)
  • Layer 1: Depends on layer 0
  • Higher layers: Depend on lower layers
  • Same layer: Can run in parallel

​
Dependency List

Simple text list of dependencies: 
bd dep list issue-id                     # What does this depend on?
bd dep list issue-id --direction=up      # What depends on this?
bd dep list issue-id --type=tracks       # Filter by type

​
Cycle Detection

Beads prevents circular dependencies: 
# Check for cycles
bd dep cycles
Beads rejects cycles at write time — bd dep add checks for cycles before committing.

​
Cross-Repo Dependencies

Reference issues in other beads rigs: 
bd dep add local-issue external:other-project:remote-issue
External dependencies always block. When the remote issue closes, bd ready reflects the change (checked at query time).

​
Gates

Gates are special issues that block dependent work until an external condition is met. They bridge the gap between beads (which tracks work) and external systems (which track code, CI, or time).

​
The Problem Gates Solve

When you use Dolt, issue state is decoupled from code state. Closing a beads issue means “work is done” but the code may still be on a feature branch: With file-based storage (JSONL), issue updates land atomically with code. With Dolt, they don’t. Gates solve this by making the dependency wait for the external condition — not just the beads issue status.

​
Gate Types

TypeConditionAuto-Resolution
gh:prPR mergedgh pr view returns MERGED
gh:runCI passesgh run view returns completed + success
timerTime elapsedCurrent time exceeds timeout
beadCross-rig issue closedRemote bead status checked
humanManual approvalbd gate resolve <id>

​
Creating Gates

# Wait for PR #42 to merge
bd create --type=gate --title="Wait for PR #42" \
  --await-type=gh:pr --await-id=42

​
Wiring Gates

A gate is an issue. Wire it into the dependency graph: 
# issue-2 waits for the gate (which waits for PR #42)
bd dep add issue-2 <gate-id>

​
Checking Gates

bd gate check evaluates all open gates and closes resolved ones: 
bd gate check
Escalation marks gates whose conditions failed (e.g., PR closed without merge, CI run failed) so they surface for attention.

​
Manual Resolution

For human gates or overrides: 
bd gate resolve <gate-id> --reason "Approved by team lead"

​
Automating Gate Checks

Run bd gate check periodically:
  • CI step: Add to your GitHub Actions workflow
  • Cron: */5 * * * * cd /path/to/repo && bd gate check
  • Agent hook: Run at session start or after PR operations

​
Common Patterns

​
PR Merge Gate

Agent finishes work, opens PR, creates a gate so follow-up work waits for merge: 
bd update issue-1 --status=in_progress
# ... write code, open PR #42 ...

bd create --type=gate --title="Wait for PR #42" \
  --await-type=gh:pr --await-id=42

bd dep add issue-2 <gate-id>
bd close issue-1

​
Epic with Ordered Phases

bd create "Auth System" -t epic
bd create "Design" --parent <epic>
bd create "Implement" --parent <epic>
bd create "Test" --parent <epic>

bd dep add <implement> <design>
bd dep add <test> <implement>

bd dep tree <epic>
bd ready                         # Only "Design" is ready

​
Parallel Work Streams

# Backend and frontend can work in parallel
bd create "Backend API" -p 1
bd create "Frontend UI" -p 1
bd create "Integration" -p 1

# Integration waits for both
bd dep add integration backend-api
bd dep add integration frontend-ui

bd ready  # Shows backend-api AND frontend-ui (parallel)

​
Best Practices

Only use blocks when work truly cannot proceed. Overuse creates unnecessary bottlenecks.
After closing an issue, run bd blocked to see what just unblocked.
Don’t close issues before code is merged. Use gates to wait for PR merge or CI success.
Run bd graph --all before major dependency changes to understand impact.

Architecture

Understand the two-layer data model

Workflows

Learn about contributor, stealth, and maintainer modes

CLI Reference

Complete command documentation

Gates Deep Dive

Advanced gate patterns and automation

Build docs developers (and LLMs) love

Get started for freeTalk to us