BAGEL BY EXTELLIGENCE · TASK GUIDE

Analyze MCAP and ROS bags

Bagel analyzes MCAP and ROS recordings through an MCP client: inspect the source and topic schemas, then query actual messages with DuckDB SQL. Start with a summary, locate a suspicious time window, and keep the query alongside each finding.

Start with a bundled ROS 2 bag

Install Docker with Compose and an MCP-enabled client. These commands use Claude Code; other client setup guides are available. Docker supplies the ROS runtime.

terminal · first terminal

git clone https://github.com/Extelligence-ai/bagel.git
cd bagel
mkdir -p ~/.bagel/artifacts ~/.bagel/capabilities
docker compose run --service-ports ros2-kilted

Wait for Uvicorn running on http://0.0.0.0:8000. Open a second terminal in the same checkout:

terminal · second terminal

claude mcp add --transport sse bagel http://localhost:8000/sse
claude

If port 8000 is busy, start the service with MCP_SERVER_PORT=8100 docker compose run --service-ports ros2-kilted and connect to http://localhost:8100/sse.

For your own recordings, uncomment and edit the data volume under your service in compose.yaml before starting it. For example, mount /absolute/path/to/logs:/home/ubuntu/data:ro and ask about /home/ubuntu/data/recording.mcap. Paths in prompts must be visible to the Bagel server. Compose maps output artifacts back to ~/.bagel/artifacts on the host.

Inspect first. Ask a bounded question.

prompt · bundled sample

Summarize the metadata of the ROS2 bag "./data/sample/ros2/mcap".
List its topics and time range. Inspect one topic's schema, then count
its messages using Bagel SQL. Show the query and the returned result.

The bundled bag is a setup check. Inspect what it contains before asking it a question about acceleration, temperature, or battery voltage. For numeric incident data, use the shareable synthetic MCAP example or your own telemetry.

prompt · adapt the path and time window

Analyze /home/ubuntu/data/recording.mcap. Describe the source, then
inspect the topics relevant to a suspected deceleration near 120 seconds
after the recording starts. Confirm the acceleration field, axis and units.
Use a coarse SQL aggregate to locate unusual values, then query the
surrounding 10 seconds in detail. Show the executed SQL, exact timestamps,
and missing-data limitations. Keep observations separate from possible causes.

The current MCP tools are describe_data_source(path), describe_topic(path, topic), and query_messages(path, sql_statement, topic, start_seconds, end_seconds). A single-topic query uses that topic as both its table name and its message STRUCT column.

SQL pattern · only after the schema confirms these names

SELECT MIN("/imu"['linear_acceleration']['x']) AS min_accel_x
FROM "/imu"

This is an illustrative field path, not a measured result. Substitute the inspected topic and fields. Bagel's start_seconds and end_seconds filters are inclusive timestamps in source seconds; convert a relative offset using the reported source start. Do not pass an elapsed offset as an absolute timestamp.

A useful answer includes the source identity, selected topics and window, executed query, returned values with verified units, and the limits of the evidence. Deterministic SQL makes a calculation repeatable; the field choice and interpretation still need review.

Choose the runtime and schema for the file

Recording	Requirements
MCAP with `ros2msg`, `protobuf`, or `jsonschema` schemas	The generic MCAP reader and reducer run in every Bagel image. Message analysis needs a supported embedded schema and matching message encoding. No installed ROS runtime is needed for these generic MCAP paths.
ROS 2 SQLite `.db3` bag	Choose the matching ROS 2 service: Kilted, Jazzy, Iron, or Humble. Keep the bag directory and metadata together. Custom message types may need their packages installed in the image.
ROS 1 `.bag`	Use `ros1-noetic` or `ros1-noetic-cv`. Use the ROS 1 bag workflow for message analysis.
Other MCAP schema encodings	Being able to list a channel does not establish that its messages can be queried. The generic topic-to-Arrow conversion currently handles the three schema encodings above; `ros1msg` conversion is not implemented there.

What to check when an answer is incomplete

No matching field: return to the topic schema. Topic names, nested fields and units vary between robots.
Empty window: compare the requested timestamps with the source time range and check whether the topic actually published there.
Large recording: select the relevant topic and time window and aggregate first. Reading or decoding large files can still require significant memory and time.
Model access: the connected model sees the tool results supplied by its client. Use the documented local-model setup when the model and data must stay local.

These are workflow instructions, not a new performance measurement. For a measured preservation check and downloadable data, continue to reduce logs around incidents. For flight telemetry, see investigate a PX4 flight log.

Implementation references: MCP tools, MCAP schema support, and investigation capability.