Skip to main content

​
Overview

Display a visualization of issue dependency graphs. Shows execution order, blocking relationships, and parallel work opportunities.

​
Syntax

bd graph [issue-id] [flags]

​
Display Formats

​
Default: Terminal DAG

Box-drawing characters with columns showing execution order: 
bd graph issue-id

​
Box Format

ASCII boxes grouped by layer: 
bd graph --box issue-id

​
Compact Format

Tree format, one line per issue, most scannable: 
bd graph --compact issue-id

​
Graphviz DOT

Export to DOT format for rendering with Graphviz: 
bd graph --dot issue-id | dot -Tsvg > graph.svg
bd graph --dot issue-id | dot -Tpng > graph.png

​
Interactive HTML

Self-contained HTML with D3.js visualization: 
bd graph --html issue-id > graph.html
bd graph --all --html > all.html       # All issues, interactive

​
Graph Interpretation

​
Execution Order

The graph shows topological ordering:
  • Layer 0 / Leftmost: No dependencies, can start immediately
  • Higher layers: Depend on lower layers
  • Same layer: Can run in parallel

​
Status Icons

Icons indicate issue state:
  • ○ open
  • ◐ in_progress
  • ● blocked
  • ✓ closed
  • ❄ deferred

​
Relationships

The graph shows:
  • Blocking dependencies: Arrows from blocker to blocked
  • Parent-child: Epic/subtask hierarchies
  • Connected components: Issues grouped by dependency relationships

​
Flags

FlagDescription
--allShow graph for all open issues
--compactTree format, one line per issue
--boxASCII boxes showing layers
--dotGraphviz DOT format
--htmlSelf-contained interactive HTML
--jsonOutput JSON format

​
Examples

​
Visualize Epic Dependencies

For an epic with multiple subtasks: 
bd graph epic-123
Output: 
📊 Dependency graph for epic-123:

  Status: ○ open  ◐ in_progress  ● blocked  ✓ closed

  Layer 0 (ready)
  ├── ○ epic-124  P1  Design authentication system
  │   ├── ○ task-125  P1  Research OAuth providers
  │   └── ○ task-126  P2  Design token storage
  └── ○ task-127  P1  Update documentation

  Layer 1
  └── ● epic-128  P1  Implement authentication
          needs:1

  Total: 5 issues across 2 layers
  Dependencies: 1 blocking relationships

​
View All Open Issues

See connected components of all open work: 
bd graph --all
Shows separate subgraphs for disconnected work.

​
Generate SVG Diagram

Create a visual diagram for documentation: 
bd graph epic-123 --dot | dot -Tsvg > architecture.svg

​
Interactive Browser View

Create interactive HTML with zoom and pan: 
bd graph --all --html > project-status.html
open project-status.html

​
Compact Tree View

Quick scannable overview: 
bd graph --compact epic-123
Output: 
📊 Dependency graph for epic-123 (5 issues, 2 layers)

  Status: ○ open  ◐ in_progress  ● blocked  ✓ closed  ❄ deferred

  LAYER 0 (ready)
  ├── ○ epic-124 ● P1 Design authentication system
  │   ├── ○ task-125 ● P1 Research OAuth providers
  │   └── ○ task-126 ● P2 Design token storage
  └── ○ task-127 ● P1 Update documentation

  LAYER 1
  └── ● epic-128 ● P1 Implement authentication

​
Check for Parallel Work

Identify tasks that can run simultaneously: 
bd graph --box epic-123
Issues in Layer 0 can all start immediately. Issues in the same higher layer can run in parallel once their dependencies complete.

​
When to Use Graph

Use bd graph when:
  • Planning work: Identify parallel work opportunities
  • Understanding blockers: See what’s blocking critical work
  • Reviewing epic scope: Visualize all subtasks and dependencies
  • Communicating status: Share visual diagrams with stakeholders
  • Finding ready work: Layer 0 shows unblocked tasks

​
Graph Types

​
Single Issue Mode

For a specific issue:
  • Shows the issue and all connected issues
  • Traverses both directions (dependencies AND dependents)
  • Includes all dependency types (blocks, parent-child, related)

​
All Issues Mode (—all)

For all open issues:
  • Groups issues by connected components
  • Shows multiple subgraphs if work is disconnected
  • Sorted by size (largest first) and priority
  • Each component chooses best “root” (epics preferred)

​
Understanding Layers

​
Layer Assignment

Layers are computed using topological sort:
  1. Layer 0: Issues with no blocking dependencies
  2. Layer N: Issues that depend on Layer N-1
  3. Parent-child lifting: Children appear in same layer as blocked parent

​
Parallel Work Detection

Issues in the same layer:
  • Have no dependencies between them
  • Can be worked on simultaneously
  • May still share a common parent (epic)

​
Critical Path

The longest path from Layer 0 to completion:
  • Determines minimum project duration
  • Issues on this path are bottlenecks
  • Prioritize resolving blockers on critical path

​
Troubleshooting

​
”Issue not found”

Cause: Invalid issue ID Solution: Verify ID with bd list or bd show <id>

​
Graph is empty

Cause: Issue has no dependencies or dependents Solution:
  • This is normal for independent issues
  • Use --all to see other work
  • Add dependencies with bd deps add

​
Too many issues in —all mode

Cause: Large project with many open issues Solution:
  • Filter to specific epic: bd graph epic-id
  • Use --compact for more scannable output
  • Use --html for interactive exploration

​
Graphviz command not found

Cause: Graphviz not installed Solution: Install with package manager: 
# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt-get install graphviz

# Fedora
sudo dnf install graphviz
  • bd deps - Manage dependencies directly
  • bd ready - Find unblocked work (Layer 0)
  • bd blocked - Show blocked issues and blockers
  • bd list - List issues with blocker annotations

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us