Skip to content
Back to search

bagel

Query robotics, drone, and IoT data in plain English through an MCP server, with an intelligent edge data reduction pipeline that keeps only the data that matters.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/extelligence-ai/bagel with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/extelligence-ai/bagel'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/extelligence-ai--bagel/badge.svg)](/listings/extelligence-ai--bagel)

HTML

<a href="/listings/extelligence-ai--bagel"><img src="/api/listings/extelligence-ai--bagel/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> [!TIP] > **Already have Claude Code?** Just paste the link to this repo and tell Claude > what environment you want: > > > Set up https://github.com/Extelligence-ai/bagel for ROS2 Kilted. > > Claude will clone the repo, start Docker, and wire up the MCP connection for you.

📋 Prerequisites

Install [Docker Desktop](https://docs.docker.com/get-started/get-docker/) and [Claude Code](https://docs.claude.com/en/docs/claude-code/quickstart) (or another MCP-enabled LLM).

> [!NOTE] > **arm64 hosts (Apple Silicon, Raspberry Pi, Jetson, Graviton):** `ros2-kilted` > — the default service, and the one `server.json` pins — ships as a multi-arch > image, so Docker pulls a native arm64 build. No extra setup. > > The other services are published for **amd64 only**. Docker Desktop emulates > them automatically, so they run on Apple Silicon (slower, but they work). On > arm64 **Linux** with plain Docker Engine there is no emulation by default and > they fail immediately with `exec format error` — install QEMU/binfmt first: > > ```bash > docker run --privileged --rm tonistiigi/binfmt --install amd64 > ```

1. Clone and start Bagel

git clone https://github.com/Extelligence-ai/bagel.git && cd bagel
docker compose run --service-ports ros2-kilted

> [!TIP] > Port 8000 already in use? Set `MCP_SERVER_PORT` to something else, for example > `MCP_SERVER_PORT=8100 docker compose run --service-ports ros2-kilted`, and use > that port in step 2.

Pick the service that matches your environment:

| Service | Use case | | ----------------- | ----------------------- | | `ros2-kilted` | ROS2 Kilted (latest) | | `ros2-jazzy` | ROS2 Jazzy | | `ros2-jazzy-jev` | ROS2 Jazzy + on-robot decision model (GPU, beta) | | `ros2-iron` | ROS2 Iron | | `ros2-humble` | ROS2 Humble | | `ros1-noetic` | ROS1 Noetic | | `ros1-noetic-cv` | ROS1 Noetic + CV | | `px4` | PX4 flight logs | | `ardupilot` | ArduPilot flight logs | | `betaflight` | Betaflight flight logs | | `iot` | IoT / MQTT (live) |

The `-jev` image *(beta)* adds PyTorch for running a decision model on the robot (`backend: local` in the [anomaly gate](./doc/runbooks/anomaly_detection.md)). Build any other service the same way with `--build-arg JEV_MODE=true`. CPU-only robots don't need it: the hosted Jev backend works in every image.

> [!TIP] > To give Bagel access to your local files, edit `compose.yaml` before starting Docker: > uncomment and update the `volumes` section under your chosen service.

Wait for this output:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

2. Connect Claude Code

In a new terminal:

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

> [!NOTE] > The MCP endpoint is bound to `localhost` only (not exposed to the LAN) for security. > To share it with other machines, drop the `127.0.0.1` prefix in `compose.yaml` and > put an authenticated proxy in front: see [SECURITY.md](./SECURITY.md).

3. Prompt

claude

> Summarize the metadata of the ROS2 bag "./data/sample/ros2/mcap".

That’s it: you’re chatting with your data.

🔒 Prefer fully offline?

Swap step 2 for a local model: your data *and* your LLM stay on the machine:

brew install ollama && ollama serve &                                  # or ollama.com
ollama pull qwen3:8b
uvx ollmcp --mcp-server-url http://localhost:8000/sse --model qwen3:8b

Model picks, expectations, and troubleshooting: [Local LLMs guide](./doc/runbooks/local_llm.md).

<details> <summary>📚 Using a different LLM?</summary>

Bagel works with any MCP-enabled LLM. Setup runbooks for tested alternatives:

- [Claude Code](./doc/runbooks/setup/claude_code.md) (detailed guide) - [Gemini CLI](./doc/runbooks/setup/gemini_cli.md) - [Codex](./doc/runbooks/setup/codex.md)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "bagel",
  3. "description": "Bagel: plain-English analysis of robotics, drone, and IoT data, with intelligent edge data reduction.",
  4. "owner": {
  5. "name": "Extelligence",
  6. "url": "https://github.com/Extelligence-ai"
  7. },
  8. "plugins": [
  9. {
  10. "name": "bagel",
  11. "source": "./plugin",
  12. "description": "Query robot logs and live data in plain language via the Bagel MCP server; includes skills for triage, pipelines, live sinks, and visualization export."
  13. }
  14. ]
  15. }
README.md · README · 653 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/bagel_logo_light_mode.png" width="560">
  3. </p>
  4. <p align="center">
  5. <strong>Bits to atoms.<br>Atoms to bits.</strong>
  6. </p>
  7. <p align="center">
  8. <em>If you still have a script called <code>parse_bag_final_v7.py</code>, we need to talk.</em>
  9. </p>
  10. <h1 align="center">
  11. <a href="https://github.com/Extelligence-ai/bagel/blob/main/LICENSE">
  12. <img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square">
  13. </a>
  14. <a href="https://pypi.org/project/bagel-mcp/">
  15. <img src="https://img.shields.io/pypi/v/bagel-mcp?label=PyPI&style=flat-square">
  16. </a>
  17. <a href="https://pypi.org/project/bagel-mcp/">
  18. <img src="https://img.shields.io/badge/python-3.10%E2%80%933.12-blue?style=flat-square">
  19. </a>
  20. <a href="https://github.com/Extelligence-ai/bagel/actions/workflows/test.yaml">
  21. <img src="https://img.shields.io/github/actions/workflow/status/Extelligence-ai/bagel/test.yaml?event=pull_request&label=tests&style=flat-square">
  22. </a>
  23. <a href="https://github.com/Extelligence-ai/bagel/actions/workflows/publish.yaml">
  24. <img src="https://img.shields.io/github/actions/workflow/status/Extelligence-ai/bagel/publish.yaml?branch=main&label=publish&style=flat-square">
  25. </a>
  26. <a href="https://discord.gg/QJDwuDGJsH">
  27. <img src="https://img.shields.io/discord/1392632504908906506?label=Discord&style=flat-square">
  28. </a>
  29. </h1>
  30. <p align="center">
  31. <picture>
  32. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/hero_dark_mode.png">
  33. <img src="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/hero_light_mode.png" width="100%">
  34. </picture>
  35. </p>
  36. Bagel by Extelligence lets you ask questions about robotics, drone, and IoT data in plain English.
  37. Every calculation over your message data is DuckDB SQL, not model guesswork, and
  38. Bagel shows you the query so you can audit it.
  39. > Is my IMU sensor overheating?
  40. Bagel also has an intelligent edge data reduction pipeline: describe an event and
  41. Bagel runs the detection on the robot, keeping the windows that matter and dropping
  42. the rest. An MCP server puts all of it in your LLM's hands: Claude Code, Gemini,
  43. Cursor, or a fully local model.
  44. Bagel was the first MCP server to ship a real analysis toolkit for robotics data,
  45. and it keeps the LLM where it belongs: in front of your logs, never in your robot's
  46. control loop.
  47. ## 📦 Install
  48. Bagel is on PyPI as [`bagel-mcp`](https://pypi.org/project/bagel-mcp/). No Docker
  49. and no ROS install needed for recorded data.
  50. **Claude Code**, one line (needs [uv](https://docs.astral.sh/uv/getting-started/installation/)):
  51. ```bash
  52. claude mcp add bagel -- uvx --from "bagel-mcp[ros]" bagel-mcp --transport stdio
  53. ```
  54. **pip**, into any Python 3.10 to 3.12 environment:
  55. ```bash
  56. pip install "bagel-mcp[ros]"
  57. ```
  58. Then point your MCP client at the `bagel-mcp` command it installed (setup for
  59. Claude Desktop, Cursor and Codex is in the [Quickstart](#%EF%B8%8F-quickstart)).
  60. Open your agent and ask:
  61. > Summarize the bag "~/logs/run_42.mcap".
  62. The `ros` extra reads ROS 1 and ROS 2 bags. Flight logs, CAN / MDF4, live MQTT
  63. and the rest are [extras too](#-install-with-uvx-or-pip-no-docker). Live ROS
  64. robots (rosbridge) and fleet/edge pipelines run in [Docker](#-run-with-docker-live-robots-fleet-and-edge-distro-specific-ros).
  65. ### 🥯 Key Features
  66. - **Ask in plain language**: No deep domain expertise needed.
  67. - **Transparent calculations**: Deterministic SQL queries. No black-box LLM math.
  68. - **Natural-language pipelines**: "Keep 10s around every hard brake, drop the rest":
  69. one sentence becomes an auditable [pipeline](./doc/runbooks/pipelines.md): previewed
  70. before a byte is written, then run once, across a fleet, or standing at the edge.
  71. - **Broad LLM support**: Claude Code, Gemini, Cursor, Codex, Grok Build, Grok Bot, and more.
  72. - **Installs your way**: `pip` / `uvx` for recorded data, Docker images for live robots and the edge.
  73. - **Extensible capabilities**: Bagel can learn [new tricks](#-teach-bagel-a-new-trick).
  74. - **Wide format coverage**: Missing your data format? [Open a ticket](https://github.com/Extelligence-ai/bagel/issues).
  75. ## 🥯 Try it in 60 seconds
  76. No MCP client, no LLM, no config: run the same deterministic checks against a
  77. bundled sample log and get a robot-health report card straight to your
  78. terminal.
  79. ```bash
  80. docker run -it --rm ghcr.io/extelligence-ai/bagel/px4:latest demo
  81. ```
  82. ```
  83. sample.ulg - 41.5s, 2018 messages, 77 topics
  84. Power ⚠️ min 21.07V, largest drop 2.37V at ~t=+4.8s, end 23.45V (battery_status_0)
  85. IMU ✅ accel_z stddev 1.6x the log baseline at ~t=+36.8s (sensor_combined_0)
  86. GPS — skipped: no GPS topic
  87. Data gaps ✅ no gap > 1.05x median interval (checked battery_status_0, sensor_combined_0)
  88. ...
  89. ```
  90. The ROS2 images (`ros2-kilted`, `ros2-jazzy`, `ros2-iron`, `ros2-humble`) run
  91. `demo` the same way, against a lighter bundled sample (`px4` is the one that
  92. ships with a flight log rich enough to show every check). Point it at your
  93. own log with `demo /path/to/log` (mount it with `-v` first), or keep reading
  94. for the full MCP setup below.
  95. ## ⚡️ Quickstart
  96. Two ways to run Bagel. Pick by data:
  97. | You have | Run Bagel with |
  98. | --- | --- |
  99. | Recorded data: ROS 1 `.bag` and ROS 2 `.db3` / `.mcap` bags, flight logs (PX4, ArduPilot, Betaflight), CAN / MDF4, CSV / JSON / Parquet, ROS text logs; live MQTT robots | **`uvx` or `pip`**, below: no Docker, no ROS install |
  100. | Live ROS robots (rosbridge), fleet and edge deployments | **Docker**, further down: the images carry the ROS stacks and the standing-pipeline runtime |
  101. ### 🐍 Install with uvx or pip (no Docker)
  102. Your MCP client launches the server itself over stdio, so there is nothing to
  103. start or keep running. Pick `uvx` (nothing to manage: it fetches and caches
  104. Bagel on first use) or `pip` (a normal install you control).
  105. **With uvx.** Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
  106. (`curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS and Linux), then:
  107. Claude Code:
  108. ```bash
  109. claude mcp add bagel -- uvx --from "bagel-mcp[ros]" bagel-mcp --transport stdio
  110. ```
  111. Any client that takes a JSON MCP config (Claude Desktop, Cursor, Codex, ...):
  112. ```json
  113. {
  114. "mcpServers": {
  115. "bagel": {
  116. "command": "uvx",
  117. "args": ["--from", "bagel-mcp[ros]", "bagel-mcp", "--transport", "stdio"]
  118. }
  119. }
  120. }
  121. ```
  122. **With pip.** Python 3.10 to 3.12; a virtual environment keeps it tidy:
  123. ```bash
  124. python3 -m venv ~/.bagel-venv
  125. ~/.bagel-venv/bin/pip install "bagel-mcp[ros]"
  126. claude mcp add bagel -- ~/.bagel-venv/bin/bagel-mcp --transport stdio
  127. ```
  128. For a JSON config, use the full path as the command:
  129. `"command": "/Users/you/.bagel-venv/bin/bagel-mcp", "args": ["--transport", "stdio"]`.
  130. **Apple Silicon Macs:** use an ARM Python, not an Intel Python running through
  131. Rosetta. Check with `python3 -c "import platform; print(platform.machine())"`;
  132. it should print `arm64`. If it prints `x86_64`, create a separate native environment:
  133. ```bash
  134. uv venv --seed --python cpython-3.12-macos-aarch64-none ~/.bagel-arm-venv
  135. ~/.bagel-arm-venv/bin/python -m pip install "bagel-mcp[ros]"
  136. claude mcp add bagel -- ~/.bagel-arm-venv/bin/bagel-mcp --transport stdio
  137. ```
  138. This avoids the `cryptography` source build: [upstream removed Intel macOS
  139. support in version 49](https://cryptography.io/en/49.0.0/changelog/).
  140. Fresh installs currently select MCP 1.30.0, whose dependency chain is
  141. `bagel-mcp` → `mcp` → `pyjwt[crypto]` → `cryptography`. This applies to the
  142. base package and `bagel-mcp[ros]`, even without the `upload` extra.
  143. On an Intel Mac, if installation fails while building `cryptography`, use the
  144. Docker path below. Do not downgrade cryptography to restore an old wheel;
  145. its older releases miss security fixes.
  146. Format support comes as extras, so that a PX4 user never downloads the
  147. automotive parsers. List the ones you need, comma-separated:
  148. `uvx --from "bagel-mcp[ros,px4,automotive]" bagel-mcp --transport stdio`, or
  149. `pip install "bagel-mcp[ros,px4,automotive]"`. If you ask about a format whose
  150. extra is missing, Bagel's error names the exact command to add it.
  151. | Extra | Adds |
  152. | --- | --- |
  153. | `ros` | ROS 1 `.bag` and ROS 2 `.db3` bags (reading, and the reduce / snippet writers), in pure Python |
  154. | `px4` | PX4 `.ulg` |
  155. | `ardupilot` | ArduPilot `.bin` |
  156. | `betaflight` | Betaflight `.bbl` / `.bfl` |
  157. | `automotive` | CAN captures (`.blf`, `.asc` + DBC) and ASAM MDF4 |
  158. | `iot` | Live MQTT (incl. Sparkplug B) and InfluxDB sources |
  159. | `viz` | Rerun export |
  160. | `upload` | GCS and Azure Blob upload tasks |
  161. | `cloudini` | Cloudini point-cloud tasks |
  162. MCAP, CSV / JSON / Parquet, ROS text logs, PlotJuggler / Lichtblick / LeRobot
  163. exports and S3 upload need no extra.
  164. PX4 log parsing does not require Git. Git and network access are used only for
  165. optional field descriptions; pass `download_description: false` in the tool's
  166. `args` to skip fetching those descriptions.
  167. To upgrade, repeat the extras you installed with, so their dependencies
  168. update too. `uvx` picks up new releases on its own (force it with
  169. `uvx --refresh --from "bagel-mcp[ros,px4]" bagel-mcp --help`); with pip, run
  170. `pip install -U "bagel-mcp[ros,px4]"`, using your own list of extras.
  171. Then prompt, pointing at your own file:
  172. > Summarize the metadata of the MCAP bag "~/logs/run_42.mcap".
  173. > [!NOTE]
  174. > No ROS installation is needed for bag files: the `ros` extra reads and writes
  175. > them with the pure-Python [rosbags](https://pypi.org/project/rosbags/) library
  176. > (sqlite3 and MCAP storage, zstd / bz2 / lz4 compression, message types from the
  177. > bag itself or from the bundled interface definitions of every distro from Humble
  178. > on). Live ROS topics (rosbridge) and the fleet/edge runtime stay with Docker.
  179. ### 🐳 Run with Docker (live robots, fleet and edge, distro-specific ROS)
  180. > [!TIP]
  181. > **Already have Claude Code?** Just paste the link to this repo and tell Claude
  182. > what environment you want:
  183. >
  184. > > Set up https://github.com/Extelligence-ai/bagel for ROS2 Kilted.
  185. >
  186. > Claude will clone the repo, start Docker, and wire up the MCP connection for you.
  187. #### 📋 Prerequisites
  188. Install [Docker Desktop](https://docs.docker.com/get-started/get-docker/) and
  189. [Claude Code](https://docs.claude.com/en/docs/claude-code/quickstart) (or another MCP-enabled LLM).
  190. > [!NOTE]
  191. > **arm64 hosts (Apple Silicon, Raspberry Pi, Jetson, Graviton):** `ros2-kilted`
  192. > — the default service, and the one `server.json` pins — ships as a multi-arch
  193. > image, so Docker pulls a native arm64 build. No extra setup.
  194. >
  195. > The other services are published for **amd64 only**. Docker Desktop emulates
  196. > them automatically, so they run on Apple Silicon (slower, but they work). On
  197. > arm64 **Linux** with plain Docker Engine there is no emulation by default and
  198. > they fail immediately with `exec format error` — install QEMU/binfmt first:
  199. >
  200. > ```bash
  201. > docker run --privileged --rm tonistiigi/binfmt --install amd64
  202. > ```
  203. #### 1. Clone and start Bagel
  204. ```bash
  205. git clone https://github.com/Extelligence-ai/bagel.git && cd bagel
  206. docker compose run --service-ports ros2-kilted
  207. ```
  208. > [!TIP]
  209. > Port 8000 already in use? Set `MCP_SERVER_PORT` to something else, for example
  210. > `MCP_SERVER_PORT=8100 docker compose run --service-ports ros2-kilted`, and use
  211. > that port in step 2.
  212. Pick the service that matches your environment:
  213. | Service | Use case |
  214. | ----------------- | ----------------------- |
  215. | `ros2-kilted` | ROS2 Kilted (latest) |
  216. | `ros2-jazzy` | ROS2 Jazzy |
  217. | `ros2-jazzy-jev` | ROS2 Jazzy + on-robot decision model (GPU, beta) |
  218. | `ros2-iron` | ROS2 Iron |
  219. | `ros2-humble` | ROS2 Humble |
  220. | `ros1-noetic` | ROS1 Noetic |
  221. | `ros1-noetic-cv` | ROS1 Noetic + CV |
  222. | `px4` | PX4 flight logs |
  223. | `ardupilot` | ArduPilot flight logs |
  224. | `betaflight` | Betaflight flight logs |
  225. | `iot` | IoT / MQTT (live) |
  226. The `-jev` image *(beta)* adds PyTorch for running a decision model on the robot
  227. (`backend: local` in the [anomaly gate](./doc/runbooks/anomaly_detection.md)). Build any
  228. other service the same way with `--build-arg JEV_MODE=true`. CPU-only robots don't need
  229. it: the hosted Jev backend works in every image.
  230. > [!TIP]
  231. > To give Bagel access to your local files, edit `compose.yaml` before starting Docker:
  232. > uncomment and update the `volumes` section under your chosen service.
  233. Wait for this output:
  234. ```
  235. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
  236. ```
  237. #### 2. Connect Claude Code
  238. In a new terminal:
  239. ```bash
  240. claude mcp add --transport sse bagel http://localhost:8000/sse
  241. ```
  242. > [!NOTE]
  243. > The MCP endpoint is bound to `localhost` only (not exposed to the LAN) for security.
  244. > To share it with other machines, drop the `127.0.0.1` prefix in `compose.yaml` and
  245. > put an authenticated proxy in front: see [SECURITY.md](./SECURITY.md).
  246. #### 3. Prompt
  247. ```bash
  248. claude
  249. ```
  250. > Summarize the metadata of the ROS2 bag "./data/sample/ros2/mcap".
  251. That’s it: you’re chatting with your data.
  252. #### 🔒 Prefer fully offline?
  253. Swap step 2 for a local model: your data *and* your LLM stay on the machine:
  254. ```bash
  255. brew install ollama && ollama serve & # or ollama.com
  256. ollama pull qwen3:8b
  257. uvx ollmcp --mcp-server-url http://localhost:8000/sse --model qwen3:8b
  258. ```
  259. Model picks, expectations, and troubleshooting: [Local LLMs guide](./doc/runbooks/local_llm.md).
  260. <details>
  261. <summary>📚 Using a different LLM?</summary>
  262. Bagel works with any MCP-enabled LLM. Setup runbooks for tested alternatives:
  263. - [Claude Code](./doc/runbooks/setup/claude_code.md) (detailed guide)
  264. - [Gemini CLI](./doc/runbooks/setup/gemini_cli.md)
  265. - [Codex](./doc/runbooks/setup/codex.md)
  266. - [Cursor](./doc/runbooks/setup/cursor.md)
  267. - [Grok Build](./doc/runbooks/setup/grok_build.md)
  268. - [Grok Bot](./doc/runbooks/setup/grok_bot.md) (runs on Grok's cloud computer)
  269. - [Copilot](./doc/runbooks/setup/copilot.md)
  270. Can’t find your LLM? [Open a ticket](https://github.com/Extelligence-ai/bagel/issues).
  271. </details>
  272. ## 🔌 Agent plugins (Claude Code, Codex and Grok Build)
  273. Bagel ships an agent plugin: four skills that teach the agent when and how
  274. to drive the server (log triage, pipeline authoring, live sinks, visualization
  275. export). The same `plugin/` directory serves Claude Code, OpenAI Codex, Cursor
  276. and xAI Grok Build.
  277. Claude Code: install the plugin, then connect the server once. The plugin
  278. carries the skills only (the Claude plugin directory accepts servers that run
  279. on your machine only from Verified organizations).
  280. ```
  281. /plugin marketplace add Extelligence-ai/bagel
  282. /plugin install bagel@bagel
  283. claude mcp add bagel -- uvx bagel-mcp --transport stdio
  284. ```
  285. `uvx` needs [uv](https://docs.astral.sh/uv/); the first start downloads Bagel
  286. (about 15 s). Add a format's extra with
  287. `uvx --from "bagel-mcp[ros,px4]" bagel-mcp --transport stdio`. For live robots,
  288. start the Docker container for your data format (see Quickstart) and connect it
  289. by URL instead: `claude mcp add --transport http bagel http://localhost:8000/mcp`.
  290. Codex and ChatGPT users: install bagel from the
  291. [OpenAI Plugins Directory](https://chatgpt.com/plugins/plugins_6a8623a0fe288191833ee0ca3fa883e7)
  292. (one click), or clone the repo and add it as a plugin marketplace (the repo
  293. carries `.agents/plugins/marketplace.json`). Directory installs bundle the
  294. skills only (the directory accepts only public HTTPS MCP servers, and
  295. Bagel's runs on your machine), so also connect the server once with
  296. `codex mcp add bagel -- uvx bagel-mcp --transport stdio`, or for Docker
  297. `codex mcp add bagel --url http://localhost:8000/mcp`. Repo-marketplace Codex
  298. and Cursor installs start the server with `uvx` automatically.
  299. Grok Build users install straight from this repo and connect the server once:
  300. ```
  301. grok plugin install Extelligence-ai/bagel#plugin
  302. ```
  303. Maintainers build the OpenAI directory ZIP with
  304. `uv run python scripts/package_codex_directory.py`.
  305. Any other MCP client can discover the same workflows server-side via the
  306. `list_agent_capabilities` tool.
  307. ## Keep what matters, drop the rest
  308. A robot records more data than you can afford to move. Bagel turns a question into
  309. a detector, runs it where the data is recorded, and ships only the windows around
  310. real events.
  311. <p align="center">
  312. <picture>
  313. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/edge_reduce_dark_mode.svg">
  314. <img src="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/edge_reduce_light_mode.svg" width="80%">
  315. </picture>
  316. </p>
  317. Here it is in one conversation:
  318. <p align="center">
  319. <picture>
  320. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/nl_reduction_dark_mode.gif">
  321. <img src="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/nl_reduction_light_mode.gif" width="80%">
  322. </picture>
  323. </p>
  324. Don't know the event in advance? The [anomaly gate](./doc/runbooks/anomaly_detection.md)
  325. *(beta)* learns what normal looks like on the robot, asks
  326. [Jev](https://docs.typesafe.ai/models) to name whatever isn't, and keeps only those
  327. slices, each with a JSON label, for any bucket: S3, GCS, Azure, MinIO or R2.
  328. The session above: a 20-minute (1,200 s) recording and the prompt *"keep 10 seconds
  329. before and after every deceleration harder than −10 m/s²"*. The preview detects
  330. 7 events, merges them into 4 windows, and keeps 92 s of the 1,200 (7.6%); the run
  331. writes a 2.1 GB bag down to 161 MB. These figures are illustrative demo output, not
  332. a measured benchmark: the ratio is event-window duration over total duration, so it
  333. depends entirely on your workload.
  334. ### ✅ Supported Data Formats
  335. | Industry | Formats |
  336. | ------------ | ------------------------------ |
  337. | **Robotics** | ROS1, ROS2, MCAP (any profile), [Copper](./doc/runbooks/copper.md) (via MCAP export), ROS text logs (`~/.ros/log`) |
  338. | **Robot learning** | [Gantry Bench](https://github.com/ShaikZaidHaaris/gantry) evidence bundles — a dataset verdict's working (per-clip signal checks, robot-test ladder, findings) as queryable tables |
  339. | **Drones** | PX4, ArduPilot, Betaflight |
  340. | **Automotive** | ASAM MDF4 (`.mf4`), CAN captures (`.blf`/`.asc` + DBC) · *beta* |
  341. | **IoT** | MQTT (live, Sparkplug B), PostgreSQL / TimescaleDB, InfluxDB 3 |
  342. | **Hardware state** | [WaffleForm](./doc/runbooks/waffle.md) snapshots (`.waffleform.yaml`), auto-detected via waffle-iron · *beta* |
  343. ## 🆚 Bagel vs. the Tools You Already Use
  344. You already have `ros2 *`, PlotJuggler, and grep. Bagel doesn't replace them: it
  345. answers the questions they make you work for, then hands off to them:
  346. | You do this today | Ask Bagel instead |
  347. | --- | --- |
  348. | `ros2 bag info` for metadata | *"Summarize this bag"*: same prompt works on PX4, ArduPilot, MCAP, MQTT, Postgres |
  349. | `ros2 topic echo /imu` and eyeball raw values | *"What's the peak z-deceleration in /imu? Running average over 5 s?"* · real SQL underneath: peaks, running averages, percentiles, cross-topic correlations |
  350. | Scrub PlotJuggler timelines hunting for the event | *"Find every deceleration under −10 m/s² and cut ±30 s snippets"*: then open the result in PlotJuggler with a [pre-framed layout](./doc/runbooks/plotjuggler.md) |
  351. | `rqt_console`, or grep `~/.ros/log` | *"Read the ERRORs from ~/.ros/log and tell me what went wrong"*: tracebacks included, [no bag needed](./doc/runbooks/ros_text_logs.md) |
  352. | Echo two topics in two terminals, correlate in a spreadsheet | *"What's the correlation between current and voltage?"*: topics live in one SQL relation, so joins and `corr()` are one question |
  353. | `ros2 bag record -a` and babysit the disk | A [standing edge pipeline](./doc/runbooks/data_reduction.md): record continuously, keep only event windows, drop the rest |
  354. | A bash loop over 200 bags | *"Run this pipeline on every bag in the folder"*: [one pipeline, whole fleet](./doc/runbooks/data_reduction.md), with a combined report |
  355. | `scp`/`aws s3 sync` scripts to ship data off the robot | Upload to S3, GCS, or Azure as a pipeline step, checksum-skipping files already there |
  356. | A different viewer per format: FlightPlot for PX4, MAVExplorer for ArduPilot, Blackbox Explorer for Betaflight | The same conversation for all of them, and ROS, MCAP, MQTT, Postgres, InfluxDB |
  357. | Write a one-off pandas script per question | Ask the question; Bagel writes and runs the query |
  358. One sentence of plain language, one answer, instead of a pipeline of commands and
  359. a script you'll delete tomorrow.
  360. ## 💬 What Can I Prompt?
  361. You can ask Bagel almost anything. For example:
  362. > What’s the correlation between current and voltage in the `/spot/status/battery_states` topic?
  363. > I think the robot hit a pothole. Can you check for sudden deceleration on the z-axis to confirm?
  364. > Every time the drone decelerates harder than -10 m/s², keep 10 seconds before and after. Drop everything else.
  365. > Did anything change on this robot since last week?
  366. Time to put Bagel to the test: can it catch a drone doing barrel rolls? Spoiler: 🎉 It totally can.
  367. <p align="center">
  368. <picture>
  369. <img src="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/drone_rolls.gif" width="80%">
  370. </picture>
  371. </p>
  372. ## 💡 How Bagel Works
  373. When you ask a question, Bagel analyzes your data source’s **metadata** and **topics** to
  374. build a high-level understanding.
  375. <p align="center">
  376. <picture>
  377. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/high_level_dark_mode.png">
  378. <img src="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/high_level_light_mode.png" width="80%">
  379. </picture>
  380. </p>
  381. Based on your prompt, if further inspection is needed, Bagel identifies the most relevant topics
  382. and **interprets their meaning and structure**. Bagel then writes the relevant topic messages
  383. to an **Apache Arrow file** and uses **DuckDB** to generate and execute queries against it.
  384. <p align="center">
  385. <picture>
  386. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/llm_math_dark_mode.png">
  387. <img src="https://raw.githubusercontent.com/Extelligence-ai/bagel/main/doc/assets/llm_math_light_mode.png" width="80%">
  388. </picture>
  389. </p>
  390. This process is repeated as needed, running new queries until Bagel finds the best answer
  391. to your question.
  392. LLMs excel at language but struggle with math. Bagel overcomes this by generating **deterministic**
  393. DuckDB SQL queries. These queries are displayed for you to **audit**, and you can guide Bagel to
  394. correct any errors.
  395. ## 🐶 Teach Bagel a New Trick
  396. Bagel learns new capabilities through [POML](https://microsoft.github.io/poml/latest/)
  397. files: a structured set of instructions that describe a “trick,”
  398. such as [computing latency statistics](./bagel_mcp/agent/diagnose/latency.poml).
  399. #### ✍️ Create a .poml file
  400. For example, let’s define `./bagel_mcp/agent/examples/woof.poml`.
  401. ```poml
  402. <poml>
  403. <task>
  404. Count the topics in the data source.
  405. If the count is odd, say "woof", else say "meow".
  406. </task>
  407. <output-format>
  408. Return the sound, the topic count, and a few cute emojis. Nothing else.
  409. </output-format>
  410. </poml>
  411. ```
  412. #### 🗣️ Use the capability
  413. Prompt Bagel:
  414. > Run the POML capability "./bagel_mcp/agent/examples/woof.poml" on the ROS2 bag "./data/sample/ros2/mcap".
  415. Result:
  416. ```
  417. meow 🐱 4 topics 🐱💤🎯
  418. ```
  419. ### Teach it your own tricks (no rebuild)
  420. Bagel discovers your own capabilities from `~/.bagel/capabilities/`:
  421. - **In conversation:** do a workflow once, then say *"save that as a
  422. capability called battery-triage"* — Claude calls `save_agent_capability`
  423. and it's reusable in any future session.
  424. - **As a file:** drop a markdown file with your steps (or a
  425. [POML](https://github.com/microsoft/poml) file, if you want parameterized
  426. templates — see `bagel_mcp/agent/compose/pipeline.poml` for the house style)
  427. into `~/.bagel/capabilities/`.
  428. Either way it shows up in `list_agent_capabilities` as `user/<name>` and runs
  429. with `run_poml_capability` — from Claude Code, Claude Desktop, or any MCP
  430. client. Teams: keep the directory in your own git repo and sync it to every
  431. robot; it's just files. On Linux, run `mkdir -p ~/.bagel/capabilities` once
  432. before starting the container so the mount is owned by you, not root.
  433. ## 📚 Guides
  434. - [Natural-language pipelines](./doc/runbooks/pipelines.md) · the model: a cadence, gates,
  435. and tasks; preview → run → save → batch → standing at the edge
  436. - [Event-driven data reduction](./doc/runbooks/data_reduction.md) · detect events, keep
  437. windows around them (snippets or one reduced bag), batch across fleets, upload to the cloud
  438. - [Anomaly detection with Jev](./doc/runbooks/anomaly_detection.md) *(beta)* · learn normal on
  439. the robot, ask Jev to label what isn't, upload only those slices with a JSON label;
  440. `preview_anomalies` dry-runs the screen first
  441. - [Live ROS2 robots over rosbridge](./doc/tutorials/live_ros2_bridge.md) · a step-by-step tutorial
  442. - [ROS text logs](./doc/runbooks/ros_text_logs.md) · inspect `~/.ros/log` errors and warnings without opening a bag
  443. - [MQTT](./doc/runbooks/iot_mqtt.md) · live IoT topics, Sparkplug B, edge recording
  444. - [PostgreSQL / TimescaleDB](./doc/runbooks/iot_postgres.md) · every table is a topic
  445. - [InfluxDB 3](./doc/runbooks/iot_influxdb.md) · every measurement is a topic
  446. - [Automotive MDF4 & CAN](./doc/runbooks/automotive_mdf.md) *(beta)* · channel groups and DBC messages are topics; units ride along
  447. - [Local LLMs](./doc/runbooks/local_llm.md) · fully offline with Ollama: your data and your model never leave the machine
  448. ## 📦 Integrations
  449. - [Rerun](./doc/runbooks/rerun.md) · "show me that event in Rerun": any time window as a ready-to-open recording
  450. - [Lichtblick / Foxglove](./doc/runbooks/lichtblick.md) · event windows as MCAP + pre-framed layouts for either viewer
  451. - [PlotJuggler](./doc/runbooks/plotjuggler.md) · open Bagel's MCAP outputs directly; one-sentence pre-framed sessions, flattened CSV/Parquet exports
  452. - [Cloudini](./doc/runbooks/cloudini.md) · decode cloudini-compressed pointclouds, or compress a bag's PointCloud2 topics into CompressedPointCloud2
  453. - [Slack](./doc/runbooks/pipelines.md) · pipelines post to your ops channel when they fire: "🚨 hard brake on {asset}"
  454. - [LeRobot](./doc/runbooks/lerobot.md) *(beta)* · detected events become training episodes: a LeRobotDataset v3.0
  455. ## 🚧 Limitations
  456. Rough edges we know about, so you don't find them the hard way:
  457. - **Two formats are beta.** The automotive MDF4/CAN readers are verified against
  458. files we generate with the same libraries that read them (`asammdf`, `python-can`);
  459. real CANape/INCA/Vector-produced captures haven't crossed our test bench yet.
  460. LeRobot exports load-test clean with the real `lerobot` package, but no policy
  461. has been trained from a Bagel export yet.
  462. - **The Jev integration is beta, and stays beta while we learn from real
  463. deployments.** That covers the `anomaly` and `decide` gates (recorded logs and live
  464. subscriptions), `preview_anomalies`, the on-robot `local` backend and the
  465. `ros2-jazzy-jev` image. Its Jev backend has been run against live Jev through Vercel
  466. AI Gateway on a real drive, a synthetic fault log and a live MQTT stream; a direct
  467. TypeSafe key is not yet exercised, and detection quality has not been measured on
  468. logs with known incidents. On a live subscription the flagged window is kept as
  469. Parquet (`write_topics_to_file`); MCAP/rosbag snippets need a recorded log and are
  470. refused there. The baseline is learned per run and restarts with the
  471. process, so in screen mode the first minutes of each run are never flagged. Labels,
  472. settings and defaults may change between releases.
  473. - **Reduction ratios are workload-dependent, and unbenchmarked.** The ratio is
  474. event-window duration over total duration: quiet recordings reduce dramatically,
  475. eventful ones much less. The figures in this README are illustrative demo output,
  476. not a measured benchmark.
  477. - **No authentication on the MCP endpoint.** By design it binds to localhost only;
  478. treat it like a database socket and see [SECURITY.md](./SECURITY.md) before
  479. sharing it beyond your machine.
  480. - **Small local models struggle with multi-step pipelines.** A 4-8B model handles
  481. tool selection and simple SQL; event-windowed reduction and multi-topic joins
  482. want a bigger model. See the [Local LLMs guide](./doc/runbooks/local_llm.md).
  483. - **Live-database end-to-end tests run outside CI.** The InfluxDB and Postgres
  484. suites' pure tests run in CI; their live end-to-end cases only execute against
  485. an instance you point them at. Everything else, including the ROS bag write
  486. paths, runs in CI.
  487. ## 🫶 Contributing
  488. We’d love your help! The easiest way to support the project is by giving it a ⭐ on GitHub.
  489. Other great ways to contribute:
  490. - Request new features
  491. - Report bugs
  492. - Improve documentation
  493. - Add new capabilities
  494. Before contributing, please review the [guidelines](./CONTRIBUTING.md).
  495. Join the conversation in our [Discord server](https://discord.com/invite/QJDwuDGJsH).
  496. We hang out there regularly.
  497. ## 📄 License
  498. Bagel is open source under the [Apache License 2.0](./LICENSE).
  499. ## Agent discovery and reproducible workflows
  500. For maintainers: [discovery audits and evaluation](./docs/agent-discovery/README.md),
  501. [listing maintenance](./docs/agent-discovery/listings.md), and
  502. [reproducible user reports](./docs/agent-discovery/community.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.