> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cerulion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hindsight

> Point Hindsight at a robot recording and find the moment the run went sideways, with every claim cited to a real topic and timestamp. Not open source — contact Cerulion for access.

<Badge icon="lock" color="orange" shape="pill">Early access · Not open source</Badge>

<Info>
  Hindsight is not open source and has no public download. [Book 15 minutes with us](https://calendly.com/lakshay-cerulion/demo?utm_source=docs\&utm_medium=book) to get access. Recording and replay stay in the [open-source CLI](https://github.com/cerulion-inc/cerulion) — `cerulion bag record`, `bag play`, and `bag play --resim all --verify` work without Hindsight.
</Info>

<Frame>
  <img src="https://mintcdn.com/cerulion-5327fd47/_4rLpGxBaFwuQJ1X/images/hindsight-hero.webp?fit=max&auto=format&n=_4rLpGxBaFwuQJ1X&q=85&s=fd823535c0800e171e5f2e3f08c83d15" alt="Conceptual recording timeline where one signal diverges at a highlighted moment as a robot stumbles in the background." width="1672" height="941" data-path="images/hindsight-hero.webp" />
</Frame>

Hindsight answers the question you ask after a bad run: **what went wrong, and when?** Point it at a robot recording (an MCAP bag). It indexes the recording on your machine, finds the anomalies, and names the moment the run went sideways. Each finding cites a real topic and timestamp from the recording, so you can check it.

## What Hindsight does

<CardGroup cols={2}>
  <Card title="Indexes a recording" icon="database" color="#0080FF">
    Builds a read-only index of an MCAP bag on your machine, and reuses it while the bag is unchanged.
  </Card>

  <Card title="Gives a debrief" icon="clipboard-list" color="#0080FF">
    A deterministic summary of gaps, dropouts, and latency spikes, and the time the run went sideways. It runs offline.
  </Card>

  <Card title="Finds anomalies" icon="triangle-exclamation" color="#0080FF">
    Lists what it detected, worst first, each at the exact time it happened.
  </Card>

  <Card title="Cites every claim" icon="quote-left" color="#0080FF">
    Each finding points at a topic and a timestamp in the recording, so you can check it against the messages.
  </Card>
</CardGroup>

A citation names the topic and the message's log time in integer nanoseconds, exactly as recorded:

```text theme={null}
[/percep/detector/detections @ t=9933017792]
```

## In Studio

In [Cerulion Studio](/cerulion/studio), open the Hindsight screen (<kbd>⌘</kbd> <kbd>D</kbd>) and pick an `.mcap` bag. Hindsight indexes it and Studio shows a headline — the time the run went sideways, or that nothing did — and one item per moment. Click a moment to see the messages it cites.

<Frame caption="The Hindsight screen on a recording: the run went sideways at 8.0 s, when the /scan topic went silent for 3 seconds. Each finding has a severity, and the cited messages show the last scan before the gap.">
  <img src="https://mintcdn.com/cerulion-5327fd47/_4rLpGxBaFwuQJ1X/images/app-hindsight-pane.webp?fit=max&auto=format&n=_4rLpGxBaFwuQJ1X&q=85&s=79031c4b1409b9a84c92ec9bc1a1ba96" alt="Cerulion Studio Hindsight screen: a went-sideways headline at 00:08.000, tiles for duration, topics, messages, rate and anomalies, a /scan moment with gap, dropout and latency-spike findings, and five cited /scan messages." width="1600" height="1071" loading="lazy" decoding="async" data-path="images/app-hindsight-pane.webp" />
</Frame>

Ask Studio's agent dock about the recording, and it answers with Hindsight's tools. Studio checks that each claim cites a real message, and it refuses an answer it cannot ground.

<Frame caption="The agent dock answers a question about the recording. It runs Hindsight's tools, cites topics and timestamps, and says what the recording cannot show.">
  <img src="https://mintcdn.com/cerulion-5327fd47/_4rLpGxBaFwuQJ1X/images/app-hindsight-agent.webp?fit=max&auto=format&n=_4rLpGxBaFwuQJ1X&q=85&s=bb7bfa33e7d47d1811daeaebb0bb2638" alt="Cerulion Studio agent dock answering why /scan went silent at 0:08.0, with the tool calls it ran and cited /scan messages." width="940" height="1360" style={{ maxWidth: "440px", margin: "0 auto" }} loading="lazy" decoding="async" data-path="images/app-hindsight-agent.webp" />
</Frame>

The Hindsight screen runs the `hindsight` binary, which is not inside the Studio app. Studio looks for it on your `PATH` and in the usual install folders, such as `~/.cargo/bin` and `/opt/homebrew/bin`.

## With your AI agent

Hindsight also runs as an MCP (Model Context Protocol) server over stdio, so Claude Code, Cursor, or Claude Desktop can investigate a recording for you. Your client runs the agent loop; the server itself needs no model and no cloud credentials. With the `hindsight` binary on your `PATH`, register it in Claude Code:

```bash theme={null}
claude mcp add --transport stdio hindsight -- hindsight mcp
```

The server gives the agent eight tools. All of them are read-only except `open_bag`, which writes the index beside the bag:

| Tool | What it does |
| - | - |
| `open_bag` | Opens a recording and builds its index on first open. |
| `get_debrief` | Returns the deterministic summary and the went-sideways time. |
| `find_anomalies` | Lists the detected anomalies, worst first, with their log times. |
| `scrub` | Shows per-second signals for chosen topics in a time window. |
| `query_index` | Runs a read-only SQL `SELECT` over the index. |
| `sample_messages` | Returns the messages on a topic nearest a timestamp. |
| `list_topics` | Lists what was recorded. |
| `get_foxglove_link` | Turns a cited moment into a Foxglove link, when the bag has a public URL. |

This is a separate server from `cerulion_mcp`, the open-source server in [Connect an MCP client](/cerulion/guides/connect-an-mcp-client). You can register both.

## Gotchas

* **MCAP only.** Hindsight reads `.mcap` recordings. Convert a ROS 1 `.bag` or a ROS 2 `.db3` first with the `mcap` CLI: `mcap convert recording.bag recording.mcap`.
* **The first open of a large bag takes time.** Indexing a multi-GB bag takes 1–2 minutes. If your MCP client has a short tool timeout, raise it, or the build is cut off mid-way.
* **Claude Desktop does not inherit your shell `PATH`.** Give it the absolute path to the `hindsight` binary, and set `HINDSIGHT_BAG_DIR` to your recordings folder so `open_bag` with no argument finds a bag.
* **The index lives next to the bag.** Hindsight writes `<bag>.duckdb` and a zero-byte `<bag>.duckdb.lock` beside the recording, so the folder must be writable. Leave the lock file in place.
* **Hindsight finds what the recording holds.** It reads only the topics you recorded. Record the topics you want to investigate — see [Record and replay a run](/cerulion/guides/record-and-replay).

## Get access

Hindsight is available to teams by request. Bring a recording of a run that went wrong, and we'll show you where.

<CardGroup cols={1}>
  <Card title="Request access to Hindsight" icon="calendar" href="https://calendly.com/lakshay-cerulion/demo?utm_source=docs&utm_medium=book" color="#0080FF">
    Book 15 minutes. We'll set you up.
  </Card>
</CardGroup>