> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# agentcompass analysis

> Post-execution badcase detection, statistics, latency checks, and qualitative trajectory diagnosis.

`agentcompass analysis` re-runs analyzers on an existing AgentCompass result directory without re-running the agent:

```bash theme={"system"}
agentcompass analysis --input <run-directory> [OPTIONS]
```

Analyzers inspect trajectories, metrics, errors, latency, model output, and tool calls, then attach analyzer output under `analysis_result.<AnalyzerId>`.

Use analyzers when a benchmark score tells you what failed but not why it failed.

## What Analyzers Do

<CardGroup cols={2}>
  <Card title="Badcase detection" icon="badge-alert">
    Flag exceptions, truncation, JSON errors, repetition, empty outputs, latency spikes, and terminal misuse.
  </Card>

  <Card title="Statistics" icon="chart-no-axes-combined">
    Compute step counts, tool-call counts, durations, token lengths, value counts, and numeric summaries.
  </Card>

  <Card title="Qualitative diagnosis" icon="sparkles">
    Use LLM-backed analyzers to annotate trajectory phases, summarize behavior, and render reports.
  </Card>

  <Card title="Aggregation" icon="table">
    Aggregate analyzer output into `analysis_summary.json` and `analysis_summary.md`.
  </Card>
</CardGroup>

Analyzers do not rerun agents or rescore benchmark correctness. They read completed task results.

## Run With Evaluation

```bash theme={"system"}
agentcompass run \
  terminal_bench_2 \
  terminus2 \
  "$MODEL_NAME" \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["<task-id>"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --enable-analysis \
  --analysis-params '{"analyzers":["ExceptionAnalyzer","TruncationAnalyzer"]}'
```

Use this path when you know which analyzers should run as part of the evaluation.

## Re-run On Existing Results

```bash theme={"system"}
agentcompass analysis \
  --input results/terminal_bench_2/$MODEL_NAME/20260703_120000 \
  --analysis-params '{
    "analyzers": ["ExceptionAnalyzer", "QualitativeAnalyzer"],
    "QualitativeAnalyzer": {"render_mode": "file"}
  }' \
  --task_concurrency 8
```

By default, `analysis` copies the input run into a new timestamped sibling. Use `--output` to choose the copy destination or `--override` when you intentionally want in-place mutation.

## Options

| Option                         | Purpose                                                                                      |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| `INPUT` / `--input`            | Existing run directory containing `run_info.json` and `details/`. Required.                  |
| `--override`                   | Replace analyzer fields and summaries in the input directory. Disabled by default.           |
| `--output <path>`              | Copy the run to this path and analyze the copy. Used only when `--override` is disabled.     |
| `--task_concurrency <n>`       | Concurrent tasks during re-analysis; defaults to the original run's value.                   |
| `--analysis-params <json>`     | Select analyzers and supply analyzer-specific configuration.                                 |
| `--benchmark-params <json>`    | Limit re-analysis through `sample_ids`; other benchmark fields are not used by this command. |
| `--config <path>`              | Load an additional configuration override; repeatable.                                       |
| `--log-level <level>`          | Set console verbosity for the analysis operation.                                            |
| `--progress auto\|plain\|none` | Select the analysis progress renderer.                                                       |

The default copy protects the measured run from accidental mutation. Use `--override` only when replacing its existing
analysis data is intentional and no immutable archive depends on that directory.

## Selection Rules

| Field               | Meaning                                                                         |
| ------------------- | ------------------------------------------------------------------------------- |
| `analyzers`         | Whitelist. If set, only these analyzer ids are considered.                      |
| `exclude_analyzers` | Blacklist. Excluded analyzers are skipped even if otherwise compatible.         |
| `<AnalyzerId>`      | Per-analyzer config, such as thresholds or qualitative model settings.          |
| `only_incorrect`    | Analyzer config option that skips correct samples when supported by base logic. |

## Supported Families

Use `agentcompass list analyzer` to inspect the analyzers registered by the installed revision. Common families include:

| Family            | Examples                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Basic statistics  | `BasicMetricAnalyzer`, `TrajectoryTimeCostAnalyzer`, `CompletionLengthAnalyzer`                                                |
| Error detection   | `ExceptionAnalyzer`, `TerminalBench2ExceptionAnalyzer`, `TruncationAnalyzer`, `JSONErrorAnalyzer`, `EmptyContentAnalyzer`      |
| Efficiency        | `LLMInferLatencyAnalyzer`, `ToolExecutionLatencyAnalyzer`                                                                      |
| Behavior patterns | `ContentRepetitionAnalyzer`, `ReasoningRepetitionAnalyzer`, `NetworkOperationAnalyzer`, `TerminalBench2CommandRunningAnalyzer` |
| Qualitative       | `QualitativeAnalyzer`, `MultiQualitativeAnalyzer`                                                                              |

## Output Shape

Per-task details keep analyzer output under:

```text theme={"system"}
analysis_result.<AnalyzerId>
```

Aggregated summaries group analyzers by category and render:

* total analyzed tasks;
* badcase count and badcase ratio;
* average score when provided;
* value-count distributions;
* numeric min, max, mean, and p95 stats.

## Related Pages

* [Results](/en/user_guide/results)
* [`agentcompass summary`](/en/user_guide/cli/summary)
* [`agentcompass list`](/en/user_guide/cli/list)
* [CLI Overview](/en/user_guide/cli)
* [Configuration](/en/user_guide/overview#configuration-files-and-precedence)