feat(cli): add 'dimos graph' subcommand

[jeff-hykin]

Adds dimos graph <python_file> to render Blueprint flowchart diagrams as interactive Mermaid in the browser, designed for debugging.

Example

# Open an interactive Mermaid view in the browser
dimos graph dimos/manipulation/blueprints.py

# Print Mermaid markdown to stdout instead
dimos graph dimos/manipulation/blueprints.py --markdown

Options

• --no-disconnected — hide disconnected streams
• --markdown — print Mermaid markdown to stdout instead of serving
• --port — pick HTTP port (default: random)

[codecov]

Codecov Report

❌ Patch coverage is 79.24945% with 94 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/utils/cli/graph.py	64.24%	51 Missing and 8 partials ⚠️
dimos/core/introspection/mermaid.py	84.82%	7 Missing and 15 partials ⚠️
dimos/robot/cli/dimos.py	27.27%	8 Missing ⚠️
dimos/utils/cli/test_graph.py	94.04%	3 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

Adds dimos graph <python_file> — a developer debugging tool that introspects Blueprint module-level globals, renders them as Mermaid flowcharts, and either serves an interactive pan/zoom browser view, writes an HTML file, or prints raw Mermaid markdown. The implementation also surfaces connection conflicts and likely typos.

• dimos/core/introspection/mermaid.py — new Mermaid renderer; sanitize_id correctly escapes all non-alphanumeric characters.
• dimos/utils/cli/graph.py — blueprint loader emits diagnostics to stderr so stdout stays clean for --markdown piping.
• dimos/utils/cli/graph.html.jinja — interactive viewer with tab, pan, zoom, and warning overlays.

Confidence Score: 5/5

Safe to merge — this is a new, self-contained developer CLI tool with no changes to existing production paths.

All changed code is additive: new CLI subcommand, new Mermaid renderer, new HTML template, and new tests. The existing codebase is not modified beyond wiring the subcommand into dimos.py.

No files require special attention.

Important Files Changed

Filename	Overview
dimos/core/introspection/mermaid.py	New Mermaid renderer for Blueprint flowcharts; correctly handles producers/consumers, disconnected streams, edge/node coloring and theming.
dimos/utils/cli/graph.py	Main CLI backend. Minor dead code: per_bp_node_colors is accumulated but never passed to the template render call.
dimos/utils/cli/graph.html.jinja	Jinja template for the interactive graph viewer; inlines mermaid.js without escaping </script> which is safe today but fragile against future mermaid versions.
dimos/robot/cli/dimos.py	Adds the graph Typer subcommand; clean dispatch to print_markdown, save_html, or serve_graph.
dimos/utils/cli/test_graph.py	Snapshot test for HTML output and round-trip HTTP serve using write-on-first-run / fail-on-mismatch pattern.
dimos/utils/cli/test_graph_blueprints.py	Blueprint fixtures exercising typo-detection and conflict-warning paths.

_{Reviews (17): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

[leshy]

we already have a very detailed renderer for dimos blueprints used in our documentation, as well as rerun blueprint graph view tab

https://github.com/dimensionalOS/dimos/blob/main/docs/usage/modules.md

is there a reason to introduce a new one?

from dimos.core.introspection.svg import to_svg
from dimos.robot.unitree_webrtc.unitree_go2_blueprints import agentic

to_svg(agentic, "assets/go2_agentic.svg")

I don't super mind this if someone prefers to above, but can add to core.introspection.mermaid perhaps

[jeff-hykin]

we already have a very detailed renderer for dimos blueprints used in our documentation, as well as rerun blueprint graph view tab

@leshy

Yeah I know. For context, I never planned to PR this, I've been using it since February - Mustafa and Andrew just saw me using it and asked if I could add it to dimos.

I don't find the existing tools useful for debugging blueprint streams, so I end up using this a lot.

Main differences:

• Doesn't hide anything (need to see disconnected edges and show all modules for debugging)
• Easy one-off invoke; no blueprint/rerun launching, no writing python code to import a blueprint, just cli command pointed at a python file
• Lighter weight (e.g. no graphviz)
• Different layout (each node owns its output)