Visualize DAG topology and diff artifacts across runs

agentgraph graph prints a text representation of your DAG’s node topology — useful for understanding wave structure before running a complex workflow. agentgraph diff compares the artifact produced by each node across two runs of the same DAG, making it straightforward to evaluate the effect of a prompt change or a backend switch.

graph
diff

agentgraph graph

Render the DAG as Mermaid flowchart or Graphviz DOT. Output goes to stdout so you can pipe it directly to a renderer.

agentgraph graph <dag_path> [OPTIONS]

Arguments and flags

dag_path

string

required

Path to the DAG YAML file.

--format / -f

string

default:"mermaid"

Output format. Options: mermaid or graphviz.

Examples

agentgraph graph examples/research.yaml

Mermaid output format

The Mermaid output groups nodes by execution wave inside subgraph blocks, with node types shown as italicised labels. Edges reflect the depends_on declarations in your YAML.

flowchart TD
    classDef agent fill:#cfe2ff,stroke:#084298;
    subgraph wave1["wave 1"]
        research_a["research_a<br/><i>agent</i>"]:::agent
        research_b["research_b<br/><i>agent</i>"]:::agent
        research_c["research_c<br/><i>agent</i>"]:::agent
    end
    subgraph wave2["wave 2"]
        synthesizer["synthesizer<br/><i>agent</i>"]:::agent
    end
    research_a --> synthesizer
    research_b --> synthesizer
    research_c --> synthesizer

Node type colours match the inspect status colour scheme: agent nodes are blue, approval gates are red, exec nodes are grey, and so on.

agentgraph diff

Compare per-node artifacts between two runs of the same DAG as a unified diff. Lines added in run_b are green, lines removed from run_a are red, and unchanged nodes are shown with an = marker.

agentgraph diff <run_a> <run_b> [OPTIONS]

Arguments and flags

run_a

string

required

Baseline run ID.

run_b

string

required

Comparison run ID.

--runs-dir

string

default:"runs"

Runs directory containing both runs.

--context / -c

number

default:"3"

Number of context lines to show around each change in the unified diff output.

Examples

agentgraph diff a1b2c3d4e5f6 f6e5d4c3b2a1

Output format

For each node that appears in either run:

= node_id (identical digest) — node produced the same output in both runs
~ node_id (changed) — followed by a unified diff of the two artifacts
+ node_id — only in <run_b> — node exists only in the second run
- node_id — only in <run_a> — node exists only in the first run

Use cases

Prompt iteration — Run the same DAG twice with a modified prompt on one node, then diff to see exactly what changed in downstream outputs.Backend comparison — Run the same DAG with --backend claude_code and --backend api to compare output quality across providers.Regression testing — Record a fixture from a known-good run, replay it after a DAG change, and diff to confirm no outputs changed unintentionally.

Paste Mermaid output directly into a GitHub pull request comment — GitHub renders Mermaid natively inside code fences tagged ```mermaid.

Commands

​agentgraph graph

​Arguments and flags

​Examples

​Mermaid output format

​agentgraph diff

​Arguments and flags

​Examples

​Output format

​Use cases

agentgraph graph

Arguments and flags

Examples

Mermaid output format

agentgraph diff

Arguments and flags

Examples

Output format

Use cases