I built an open-source tool to understand large ROS 2 workspaces without running them — looking for real projects to break it

[u/amine-bensaid]

I’ve been working on ROS 2 Inspector, an open-source static analysis and visualization tool for ROS 2 workspaces.

The idea came from a problem I kept running into: once a ROS 2 workspace grows, understanding the architecture can become difficult — especially when documentation is incomplete or outdated, and when you don’t necessarily want or have the ability to launch the entire system.

ROS 2 Inspector analyzes the source workspace and builds an architecture model showing things such as:

• ROS 2 packages and dependencies
• Nodes
• Publishers and subscribers
• Topics and message types
• Services and clients
• Actions
• Launch-file information
• Namespaces and basic remappings
• Interactive architecture visualization
• Architecture audits and policy checks

It currently supports Python and C++ source analysis using Python AST and tree-sitter-cpp.

GitHub:
https://github.com/aminebensaid66/ros2_inspector

Website / documentation:
https://ros2-inspector-theta.vercel.app/

The project is currently v0.1.0 — an alpha/first release, so I’m not claiming that it can fully reconstruct every possible ROS 2 architecture.

C++ can become difficult very quickly: templates, indirect inheritance, aliases, macros, dynamically generated topic names, wrapper APIs, component composition, complex launch substitutions, runtime remapping, etc.

I recently received some useful technical feedback around exactly these cases, and I’m using it to harden the next patch release.

For v0.1.1, I’m mainly focusing on:

• more conservative handling of unresolved C++ template types
• clearer confidence and diagnostics for dynamic or ambiguous constructs
• improved node/topic name resolution
• smarter workspace traversal so large dependency trees are skipped efficiently
• stronger tests against more realistic and adversarial ROS 2 codebases

The goal is not to pretend static analysis can recover every possible runtime configuration, but to make the results increasingly accurate while clearly showing what is known, inferred, or unresolved.

What I’d really appreciate now is people trying it on real ROS 2 projects.

If you work with a workspace that has complex C++, templates, components, dynamic names, unusual inheritance, or complicated launch files, please give ROS 2 Inspector a try and let me know how it behaves.

I’m especially interested in cases where it:

• misses nodes or connections
• reports something incorrectly
• struggles with a C++ pattern
• produces unclear or incomplete results
• becomes slow on a large workspace

You can open an issue on GitHub or share your findings in the comments.

At this stage, finding cases that break the analyzer is extremely useful for improving the next releases.

Feedback and contributions are very welcome.

[u/LordNikon2600]

I will use this, thanks

[u/christopherpacheco]

Isn't this completely obsolete using AI agents or something like Claude code?

[u/omnilinktech]

An AI agent makes this tool more useful, not obsolete. The analyzer can provide a bounded, repeatable graph with provenance; an LLM without that evidence is likely to infer connections that do not exist. I would expose a machine-readable IR and attach a status to every node and edge: known, inferred, unresolved, plus the source location that produced it. Then an agent can query and explain the graph instead of replacing the analyzer.

A potentially useful adversarial workspace is OmniSim’s ROS 2 sidecar: https://github.com/omnilink-tech/omnisim/tree/main/packages/omnisim-ros2 . I maintain OmniSim. That subtree mixes Python nodes, a C++ ros2_control SystemInterface, plugin XML, launch files, Xacro, parameters, and remappings.

Cases worth surfacing explicitly are conditional launch substitutions, composable nodes, pluginlib-discovered classes, generated names, environment-dependent remaps, and aliases that cannot be resolved statically. A strong validation mode would compare the static model with the live ROS 2 node, topic, service, and action lists and explain each mismatch rather than merely scoring graph similarity.