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

# Insights

> See where agents got stuck in each run, what Insights read, and how those problems become your project's frictions.

While [Evals](https://docs.oqoqo.ai/evaluation/evals.md) grade whether a run passed, **Insights** examine how the agent worked—surfacing failed tool calls, missing context, detours, and wasted retries—and group them into your project's [frictions](https://docs.oqoqo.ai/evaluation/frictions.md).

```mermaid theme={null}
flowchart LR
  R["Finished runs"] --> I["Insights model<br/>reviews each run"]
  I --> E["Experiment insights model<br/>groups problems"]
  E --> F["Frictions"]
  F --> B["Brief"]
```

Two models collaborate on Insights: the **Insights model** analyzes each individual run, and the **Experiment insights model** clusters findings into project-wide frictions and writes the [Brief](https://docs.oqoqo.ai/evaluation/comparisons.md#brief) on **Comparisons**. Insights do not inspect changed files or alter Evals verdicts.

## Turn on Insights

**1. Assign Insights models**

Set your **Insights model** and **Experiment insights model** under [**Organization settings → Oqoqo AI defaults**](https://docs.oqoqo.ai/setup/oqoqo-ai.md).

**2. Enable Insights on an experiment**

Keep **Insights** toggled on when you [launch](https://docs.oqoqo.ai/experiments/launch.md), or select **Run insights** on a finished experiment.

**3. Review frictions**

View grouped problems on the experiment's **Frictions** tab, **All frictions**, and inline on each run's **Traces**.

## Choose a mode

By default, Insights run in **Standard** mode (one fast pass per run). If your organization has enabled [**Agent mode**](https://docs.oqoqo.ai/evaluation/agent-mode.md) (private beta), you can switch to **Agent** at launch or when rerunning so Oqoqo's insights agent reads the full run and adds [What the runs did differently](https://docs.oqoqo.ai/evaluation/agent-mode.md#what-the-runs-did-differently) to **Comparisons**. See [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md#standard-and-agent-modes) for trade-offs and model rules.

## What Insights read

Your **Insights model** reads each run's recorded trajectory steps. If a run exceeds the model's context window in Standard mode, a note above the **Timeline** on **Traces** (and in **Compare**) reports any summarized steps, shortened long steps, truncated friction signals, or traces over the 32 MB limit.

No coverage note means the model read the entire run (older runs before coverage tracking show no note). If a run fails to fit even after condensing, assign an **Insights model** or **Experiment insights model** with a larger context window and rerun Insights.

## Which models ran

Each Insights attempt records the **Insights model** and **Experiment insights model** used at runtime. You can inspect them above a run's **Timeline**, via the help icon beside **Frictions**, on the experiment's **Frictions** tab, in the experiment info popover, in CLI and plugin attempt reads, and in the `insights` and `frictions` datasets of `oqoqo data query`.

## Pending frictions

Frictions populate as runs finish and cluster:

* While Insights are still clustering, the experiment's **Frictions** tab shows **Warming up**, and per-run frictions appear on individual run **Traces** until grouping completes.
* **Rerun Insights** replaces each run's previous frictions while preserving stable `frc_` IDs across experiments.
* In the CLI and plugin, [`oqoqo results analyze`](https://docs.oqoqo.ai/cli/runs#oqoqo-results-analyze) and [`oqoqo frictions list`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-list) report `coverage` counts so you know whether an empty list is final or still pending.

## Run Insights again

Rerun Insights anytime to re-analyze existing trajectories—for example, after switching to a newer Insights model—without spending agent runs. Oqoqo regenerates the experiment [Brief](https://docs.oqoqo.ai/evaluation/comparisons.md#brief) when Insights finish.

> [tab] Dashboard
>
> Open the experiment and select **Rerun Insights** (or **Run insights**), optionally overriding the **Insights model**, **Experiment insights model**, or mode.

> [tab] CLI
>
> ```bash theme={null}
> oqoqo insights preview exp_8f2c41d0
> oqoqo insights trigger exp_8f2c41d0
> ```
>
> See [`oqoqo insights trigger`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-trigger) for all flags.

> [tab] Plugin (MCP)
>
> Ask your AI assistant to rerun Insights; it calls **Start Insights for an experiment** ([`trigger_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#trigger_insights)) after your approval.

## From the CLI and the plugin

| Task | CLI | Plugin (MCP) |
| - | - | - |
| Preview Insights eligibility | [`oqoqo insights preview`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-preview) | [`preview_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#preview_insights) |
| Run or rerun Insights | [`oqoqo insights trigger`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-trigger) | [`trigger_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#trigger_insights) |
| List Insights attempts | [`oqoqo insights list`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-list) | [`list_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#list_insights) |
| Read per-run Insights status | [`oqoqo insights get`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-get) | [`get_insights_results`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_insights_results) |
| List grouped frictions | [`oqoqo frictions list`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-list) | [`list_frictions`](https://docs.oqoqo.ai/mcp-server/frictions#list_frictions) |
| Read the Brief | [`oqoqo experiments brief`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-brief) | [`get_experiment_brief`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_experiment_brief) |

## Next steps

> [card] [Frictions](https://docs.oqoqo.ai/evaluation/frictions.md)
>
> Rank problems by unrecovered runs and see where to fix them.

> [card] [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md)
>
> Enable deep run-pair comparisons and verified frictions.

> [card] [Run details](https://docs.oqoqo.ai/evaluation/traces.md)
>
> Jump straight to the trace steps cited by frictions.

> [card] [oqoqo evals and insights](https://docs.oqoqo.ai/cli/evals-and-insights.md)
>
> Full CLI reference for Insights commands.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.