ros2ai 🤖

ros2ai is a next-generation ROS 2 command line interface extension with OpenAI, Anthropic and Ollama.

see overview slide deck for more information.

Motivation

• (Just for fun 😝)
• Thin wrapper for ros2cli and ros2documentation.
• Getting answers against the questions directly without browsing, clicking and typing many times.
• Easy to use for everyone, especially for ROS 2 beginners and students who do not really know ros2cli.
• Multiple language support.
• Multiple LLMs support (with OpenAI Python API, any OpenAI compatible endpoint such as Anthropic and Ollama)

Demo 🖥️

See how it works 🔥

(Full quality video: ros2ai_demo.mp4)

Supported ROS Distribution

Installation

Binary

ros2ai is released for every supported distribution, replace <distro> with rolling, lyrical, kilted, jazzy or humble.

apt install ros-<distro>-ros2ai

Docker Container

see available images for tomoyafujita/ros2ai@dockerhub

docker run -it --rm --net=host -e ROS2AI_API_KEY=$ROS2AI_API_KEY -e ROS2AI_ENDPOINT=$ROS2AI_ENDPOINT -e ROS2AI_MODEL_NAME=$ROS2AI_MODEL_NAME tomoyafujita/ros2ai:rolling

[!NOTE] ROS2AI_API_KEY environmental variable is not required if using Ollama. And it is expecting that Ollama runs on the host system mostly, so that container is bound to the host network interface.

Required Package

• rolling / lyrical / kilted / jazzy

  pip install openai validators --break-system-packages --ignore-installed
  

[!NOTE] see PEP 668 – Marking Python base environments as “externally managed” why --break-system-packages is required.

• humble

  pip install openai validators --ignore-installed
  

Build

To use the latest development version, build it in the colcon workspace.

source /opt/ros/rolling/setup.bash
mkdir -p colcon_ws/src
cd colcon_ws/src
git clone https://github.com/fujitatomoya/ros2ai.git
cd ..
colcon build --symlink-install --packages-select ros2ai

Usage

Prerequisites

As described in overview diagram, ros2ai uses only OpenAI Python API but backend implementation can be replaced with any LLM service that provides the compatible API with OpenAI, such as Anthropic and Ollama. User need to choose which of them is used by ros2ai as following configuration, otherwise it falls back to use OpenAI.

• OpenAI

  ros2ai requires OpenAI API key

File truncated at 100 lines see the full file

Changelog for package ros2ai

1.0.0 (2026-11-13)

• Adjust verification.sh to the session mode. (#122) [ros2 ai]{.title-ref} without a request now starts the interactive session, so the verification blocked on the prompt. The interactive session is driven by the requests piped to the standard input instead, and the session file is isolated in a temporary directory so that the verification does not touch the session of the user. [--continue]{.title-ref} and [--trace]{.title-ref} are verified as well. Co-authored-by: Claude Fable 5.1 <<noreply@anthropic.com>>

• cosmetic documentation fixes.

• Hide the trace of the tool calls by default, --trace prints it. (#120) (#121) The tool calls, the executed commands and their output are not printed unless -T / --trace is given (-v implies it). The commands that change the system, the failures and the documentation download are printed regardless. The system role tells the model that the user does not see the tool results, so that the answer is self-contained. Co-authored-by: Claude Fable 5.1 <<noreply@anthropic.com>>

• Align documentation with the current implementation. (#116)

  • Align documentation with the current implementation.

  - README: ros2ai is released for every supported distribution, drop the unused ollama pip package, fix the PEP 668 link and add the command line options table.

  • Dockerfile: drop the unused ollama pip package.

  - Architecture diagram: add Anthropic, OpenAI compatible API and the ros2cli tool calling path.

  - overview: add the tool calling policy slide, remove the daemonized agent plan (#35) and regenerate the html and pdf exports. Co-Authored-By: Claude Fable 5.1 <<noreply@anthropic.com>>

  * Drop the unused ollama pip package from the CI script as well. Co-Authored-By: Claude Fable 5.1 <<noreply@anthropic.com>>

  * Ground the answers on the ROS 2 documentation of the distribution. (#117) (#118) Add the documentation tools [search_ros2_docs]{.title-ref} and [read_ros2_docs]{.title-ref} that look up the official ROS 2 documentation of the running distribution.

  - The reStructuredText sources of the [ROS_DISTRO]{.title-ref} branch of ros2/ros2_documentation are cached under [~/.cache/ros2ai/docs/<distro>]{.title-ref} ([ROS2AI_DOCS_CACHE]{.title-ref}), only the pages are extracted from the branch archive, refreshed when older than a week, the lookup works offline.

  - [search_ros2_docs]{.title-ref} scores the pages by the query terms in the title, the page name and the text (stem matching, density, phrase bonus) and returns the pages with their URL and a snippet.

  - [read_ros2_docs]{.title-ref} returns the page text with the placeholders expanded, paged to fit the tool output limit, with the docs.ros.org URL.

  - The page content is only returned to the model ([ToolResult.printable]{.title-ref}), the matched pages are printed under the tool call.

  • The system role asks to consult the documentation and to cite the page.
  • README: documentation lookup, [ROS2AI_DOCS_CACHE]{.title-ref}, Ollama context length.

  - overview: documentation grounding slide, exports regenerated. Co-authored-by: Claude Fable 5.1 <<noreply@anthropic.com>> ---------Co-authored-by: Claude Fable 5.1 <<noreply@anthropic.com>>

• Support session mode to keep the context of the requests. (#34) (#115) [ros2 ai]{.title-ref} without a request starts the interactive session, and [ros2 ai --continue "<request>"]{.title-ref} continues the previous session saved to the session file, so that the follow-up requests can refer to the previous ones. The conversation is kept on the client side and sent with every request, grouped by turns so that the tool calls are never separated from their results. The oldest turns are dropped beyond ROS2AI_CONTEXT_LIMIT, or when the endpoint reports that the context length is exceeded. closes #34 Co-authored-by: Claude Fable 5.1 <<noreply@anthropic.com>>

File truncated at 100 lines see the full file