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

# momentic ai

> AI-assisted classification and authoring for Momentic runs.

AI-powered subcommands that operate on existing test runs. Use these to triage
failures or attach AI-generated metadata to runs in CI.

```bash theme={null}
npx momentic ai classify <runIdOrUrl>
```

## `classify`

Classify the result of a test run. The agent inspects step results, screenshots,
and error details and returns a category with reasoning.

Only failed runs are classified; passing runs are skipped. Provide exactly one
selector: `--run-id` (one or more run IDs or URLs), `--run-group-id` (a run
group ID or URL), or `--git-commit`. Multiple failed runs are classified in
parallel with an aggregated summary.

```bash theme={null}
npx momentic ai classify --run-id <runIdOrUrl>
npx momentic ai classify --run-group-id <runGroupIdOrUrl>
npx momentic ai classify --git-commit <sha>
```

### Options

<ParamField path="--run-id <runIdOrUrl...>" type="string">
  Classify one or more runs by ID or full run URL (e.g.
  `https://app.momentic.ai/runs/<runId>`). Pass multiple space-separated values
  to classify several runs in one invocation. Passing more than one run cannot
  be combined with `--interactive`.
</ParamField>

<ParamField path="--run-group-id <runGroupIdOrUrl>" type="string">
  Classify every failed run in an uploaded run group, by run group ID or full
  run group URL (e.g. `https://app.momentic.ai/run-groups/<runGroupId>`).
</ParamField>

<ParamField path="--git-commit <sha>" type="string">
  Classify every failed run recorded at the given git commit SHA, across all run
  groups.
</ParamField>

<ParamField path="--skip-classified" type="boolean">
  When targeting a run group or commit, skip runs that already have a saved
  classification. Useful for resuming a partially-completed batch.
</ParamField>

<ParamField path="-p, --parallel <parallel>" type="number">
  Number of runs to classify in parallel when targeting a run group or commit.
  Defaults to `4`. The effective value is shown in the run banner.
</ParamField>

<ParamField path="--output-format <format>" type="string">
  Output format for the classification. Defaults to `text`. Use `json` to print
  only the structured payload to stdout.
</ParamField>

<ParamField path="--quiet" type="boolean">
  Suppress the agent's streamed reasoning. Redundant when `--output-format json`
  is set.
</ParamField>

<ParamField path="--save" type="boolean">
  Persist the classification into the run's metadata. For local runs, this
  updates the local run zip; for uploaded runs, it updates the dashboard run.
  When targeting a run group or commit, each run is saved as it finishes. New
  result-classification cache entries are only written when `--save` is set.
</ParamField>

<ParamField path="--no-cache" type="boolean">
  Ignore prior result-classification cache entries and do not write new cache
  entries. By default, classification can reuse prior classifications from the
  result-classification cache. If `--save` is also set, successful
  classifications can write new cache entries for future runs.
</ParamField>

<ParamField path="-i, --interactive" type="boolean">
  After classifying, stay in an interactive terminal chat with the
  classification agent. Useful for asking follow-up questions about the run (why
  a step failed, what the screenshots show, related runs, etc.) without
  re-running classification. Single-run only and requires a TTY; cannot be
  combined with `--run-group-id`, `--git-commit`, or `--output-format json`.
  Type `exit` (or Ctrl-C) to leave; Ctrl-C during a response cancels just that
  turn.
</ParamField>

### Output

By default, the classification is printed as plain text:

```
Classification: BUG
Reasoning: The checkout button was disabled due to a validation error that appeared after the address step...
Confidence: high
Recoverable: RECOVERABLE
```

Pass `--output-format json` to emit a machine-readable payload instead:

```json theme={null}
{
  "category": "BUG",
  "reasoning": "The checkout button was disabled due to a validation error...",
  "recoverable": "RECOVERABLE",
  "confidence": "high"
}
```

When targeting a run group or commit, the text output shows one row per run plus
an aggregated summary of category counts and any failures. The `json` payload is
an array, one entry per run; entries that failed to classify carry an `error`
field instead of a `classification`:

```json theme={null}
[
  {
    "runId": "<runId>",
    "testName": "Checkout",
    "classification": {
      "category": "BUG",
      "recoverable": "RECOVERABLE",
      "confidence": "high"
    }
  },
  { "runId": "<runId>", "testName": "Login", "error": "Run archive not found" }
]
```

Failures do not stop the batch; remaining runs are still classified and the
errors are reported in the summary. Re-run with `--skip-classified` to retry
only the runs that did not complete.

### Categories

<ResponseField name="NO_FAILURE" type="enum">
  No failures, all attempts passed.
</ResponseField>

<ResponseField name="APPLICATION_CHANGE" type="enum">
  The test is out of date because the application's flow or UI has changed.
  Updating the test to match the new behavior would permanently fix the failure.
</ResponseField>

<ResponseField name="BUG" type="enum">
  Something clearly went wrong in the application that shouldn't have, such as
  an unexpected error message appearing or expected content failing to render.
</ResponseField>

<ResponseField name="TEST_AUTHORSHIP" type="enum">
  The test can be permanently updated to prevent the failure while still
  validating its original intent, and a specific authorship change can be
  recommended. Timeouts, slow page loads, and any failure whose recommended fix
  is to wait longer or increase a timeout do not belong here. Those are `INFRA`,
  even when the test could technically be edited to wait longer.
</ResponseField>

<ResponseField name="TEST_SETUP" type="enum">
  Missing test data or files necessary to run the test, where the fix requires
  user action outside of the test itself (e.g. a missing file for a file upload
  step, or missing/incorrect credentials).
</ResponseField>

<ResponseField name="INFRA" type="enum">
  A failure unrelated to the application or application code that was caused by
  an infrastructure outage, long load times, or some other outside factor.
</ResponseField>

<ResponseField name="MOMENTIC_ISSUE" type="enum">
  An issue with Momentic's own execution (e.g. incorrect cache entries,
  unexpected locator redirects, obvious AI hallucinations).
</ResponseField>

<ResponseField name="OTHER" type="enum">
  The failure doesn't fit any of the other categories.
</ResponseField>

## `triage`

Runs the triage agent over a local results archive from
[`momentic run`](/cli-reference/momentic/commands/run) or an uploaded run group.
The agent investigates failures, groups them by shared fixes when possible,
attempts to update tests in place, and writes the outcome back to the run group.
`momentic ai heal` is an alias with the same behavior and flags.

When processing a local results archive, the command automatically uploads the
updated archive after processing so the dashboard and connected reporting
receive the final results and validation signal. Pass `--no-upload` to keep the
archive local. This automatic upload also runs after `--dry-run` triage.

<Note>
  For a copy-paste CI setup and the different integration paths, see [Auto-heal
  failing tests in CI](/guides/auto-heal/in-ci).
</Note>

<Tip>
  Triage can take a while. When you only need to know which runs failed (not to
  repair them), use [`momentic results
      check`](/cli-reference/momentic/commands/results#check) over the same results
  folder. It reports the failed, canceled, and quarantined runs so you can
  decide what to do.
</Tip>

```bash theme={null}
npx momentic ai triage [results]
npx momentic ai triage --run-group-id <runGroupIdOrUrl>
npx momentic ai triage --run-id <runIdOrUrl>
npx momentic ai triage --git-commit <sha>
```

Provide exactly one selector: a local `[results]` archive, `--run-group-id`,
`--run-id`, or `--git-commit`. When multiple runs are passed via `--run-id`,
they are triaged together in a single bucketing pass.

### Arguments

<ParamField path="<results>" type="string">
  Path to a local results archive directory written by `momentic run`. The
  directory must contain a run group metadata file. Omit when using
  `--run-group-id`, `--run-id`, or `--git-commit`.
</ParamField>

### Target and output

<ParamField path="--run-group-id <runGroupIdOrUrl>" type="string">
  Triage an already uploaded run group by ID or full run group URL (e.g.
  `https://app.momentic.ai/run-groups/<runGroupId>`) instead of a local results
  archive. Automatic upload does not apply because there is no local archive.
</ParamField>

<ParamField path="--run-id <runIdOrUrl...>" type="string">
  Triage one or more uploaded runs by ID or full run URL. Pass multiple
  space-separated values to triage several runs together in one bucketing pass.
  The run-group risk-summary write-back is skipped for this scope.
</ParamField>

<ParamField path="--git-commit <sha>" type="string">
  Triage every failed run recorded at the given git commit SHA, flat across all
  run groups. The run-group risk-summary write-back is skipped for this scope.
</ParamField>

<ParamField path="--dry-run" type="boolean">
  Group failed tests and generate a validation signal without attempting or
  applying repairs. A local results archive is still uploaded by default. Add
  `--no-upload` to skip the archive upload.
</ParamField>

<ParamField path="--on-heal-success <behavior>" type="string">
  How an accepted repair is delivered. Accepts `pull-request`,
  `draft-pull-request`, `direct-commit-except-main`, `patch` (print a git patch
  to stdout), or `nothing` (leave the changes on disk). Overrides the **On
  successful heal** [Healing setting](https://app.momentic.ai/settings/healing)
  for this run.
</ParamField>

<ParamField path="--on-heal-fail <behavior>" type="string">
  What happens to tests the agent cannot fix. Accepts `warn`, `fail`, or
  `quarantine`. Overrides the **On failed heal** [Healing
  setting](https://app.momentic.ai/settings/healing) for this run.
</ParamField>

<ParamField path="--json" type="boolean">
  Suppress progress output and print the triage result as JSON.
</ParamField>

<ParamField path="-i, --interactive" type="boolean">
  After triaging, stay in an interactive terminal chat with the triage agent so
  you can ask follow-up questions. This cannot be combined with `--json`.
</ParamField>

<ParamField path="--no-upload" type="boolean">
  Do not automatically upload the local results archive after processing. The
  generated validation signal may still update connected pull request reporting.
  This flag has no effect when using `--run-group-id`.
</ParamField>

### Common flags

<ParamField path="-c, --config <config>" type="string">
  Path to the Momentic configuration file. Defaults to `momentic.config.yaml` in
  the current directory.
</ParamField>

<ParamField path="-f, --filter <filter>" type="string">
  When using [workspaces](/configuration/workspace), load the project whose name
  matches the filter.
</ParamField>

<ParamField path="-p, --parallel <parallel>" type="string">
  Number of healing attempts to run in parallel. Each attempt opens its own
  browser session. Defaults to `1`.
</ParamField>

<ParamField path="--limit <limit>" type="number">
  Abort when the number of healable failed runs exceeds this threshold. Must be
  a positive integer.
</ParamField>

<ParamField path="--exclude <excludePatterns...>" type="array">
  Exclude tests whose name or project-relative file path matches any of the
  provided regex patterns from the triage queue. Provide multiple patterns
  separated by spaces. A pattern only needs to match part of the name or path
  for that test to be skipped.
</ParamField>

<ParamField path="--share-diagnostics" type="boolean">
  Emits high fidelity diagnostics for the triage agent to enable Momentic to
  help you debug your agent's failure. Do not default to turning this on.
</ParamField>

### Environment

<ParamField path="--env <env>" type="string">
  Environment to run replays in. Overrides any environment configured on the
  test itself.
</ParamField>

<ParamField path="--url-override <urlOverride>" type="string">
  Override the base URL of the test or environment during the replay.
</ParamField>

<ParamField path="--custom-headers <customHeaders...>" type="array">
  Custom headers to include in the replay. Specify multiple headers separated by
  spaces.
</ParamField>

<ParamField path="--input-csv <inputCsv>" type="string">
  CSV file containing input data for the replay. Each row is used as input for a
  separate run.
</ParamField>

### Browser

<ParamField path="--browser <browser>" type="string">
  Override the browser used for replays. Accepts `chromium`, `chrome`, or
  `chrome-for-testing`.
</ParamField>

<ParamField path="--headful-browser [headfulBrowser]" type="boolean">
  Launch healing browser sessions headfully by default. Useful for visually
  watching the agent work. Env: `MOMENTIC_HEADFUL_BROWSER`.
</ParamField>

<ParamField path="--pixel-ratio <pixelRatio>" type="number">
  Device pixel ratio for the healing browser. Set to `2` on macOS Retina or
  other HiDPI displays.
</ParamField>

### Caching

<ParamField path="--save-cache" type="boolean">
  Always save updated step caches after a successful heal, even on the main and
  other protected Git branches.
</ParamField>

<ParamField path="--disable-cache" type="boolean">
  Disable step caches entirely. Steps run without cached data and no caches are
  saved.
</ParamField>

<ParamField path="--regenerate-heal" type="boolean">
  Ignore previously cached heal solutions during triage so failures are healed
  from scratch. Newly successful heals are still saved; step caches are
  unaffected.
</ParamField>

### Quarantine

<ParamField path="--only-quarantined" type="boolean">
  Only attempt to heal quarantined tests. Failed runs outside quarantine are
  ignored.
</ParamField>

### Setup

<ParamField path="--start <start>" type="string">
  Command to run before the replay begins. Useful for booting a local dev
  server.
</ParamField>

<ParamField path="--wait-on <waitOn>" type="string">
  Resource to wait for before the replay begins. Accepts anything supported by
  [`wait-on`](https://www.npmjs.com/package/wait-on).
</ParamField>

<ParamField path="--wait-on-proxy <waitOnProxy>" type="string">
  HTTP proxy used when polling `--wait-on`. Provide the full URL including
  protocol, optional credentials, host, and port.
</ParamField>

<ParamField path="--wait-on-timeout <waitOnTimeout>" type="number">
  Timeout (in seconds) for `--wait-on`. Defaults to `60`. Triage fails if the
  resource is not reachable in time.
</ParamField>

### CI

<ParamField path="--timeout-minutes <timeoutMinutes>" type="number">
  Maximum total triage time, in minutes. When reached, in-flight healing
  attempts stop and the current results are flushed.
</ParamField>

<ParamField path="--quiet" type="boolean">
  Suppress the agent's streamed reasoning.
</ParamField>

<ParamField path="-y, --yes" type="boolean">
  Skip all confirmation prompts. Enabled by default when `CI` is set.
</ParamField>

### Exit codes

`triage` is the final status for a run group: a non-zero exit code means
something still needs your attention.

* **`0`** - every failure was either successfully healed or, when **On failed
  heal** is `warn`, logged as a warning. A successful heal does not fail the run
  on its own; the delivered fix (e.g. a pull request) is yours to review and
  merge.
* **`1`** - a test could not be healed and **On failed heal** is `fail` or
  `quarantine`, or delivering an accepted repair failed (e.g. opening the pull
  request errored), or the triage run itself errored out.

Configure **On failed heal** in
[Settings > Healing](https://app.momentic.ai/settings/healing).

## `explore`

<Warning>The explore agent is in beta and may change.</Warning>

For the conceptual overview, see the [Explore agent](/ai/explore) guide.

The explorer agent identifies user-facing changes (including backend changes
that surface to the user), reports the user journeys they touch, and by default
opens a live browser session to author or edit Momentic tests covering them,
reusing existing tests where they already partially cover a journey. Pass
`--dry-run` to only discover and log journeys.

`explore` has two subcommands:

```bash theme={null}
# Explore a diff window
npx momentic ai explore diff

# Seed coverage across the whole app
npx momentic ai explore latest
```

### `explore diff`

Explore a git diff window: the agent diffs a commit range and reports the
journeys that changed.

```bash theme={null}
npx momentic ai explore diff main...HEAD
```

<ParamField path="[commitRange]" type="string">
  Commit or commit range to explore. Uses `git diff` range semantics:
  `base...head` diffs the merge-base of the two refs against `head`,
  `base..head` diffs `base` directly against `head`, and a single `commit` diffs
  that commit against its first parent (`commit^`). A missing endpoint defaults
  to `HEAD`. When omitted, defaults to the current pull request's diff window in
  CI (GitHub Actions, CircleCI, GitLab, Buildkite, Azure DevOps); otherwise
  `HEAD~1..HEAD`.
</ParamField>

`explore diff` accepts every [shared option](#shared-options) below.

<Note>
  `--base <sha>` and `--head <sha>` are deprecated — pass a commit range argument
  instead (e.g. `main...HEAD`). `--seed` is deprecated; use `momentic ai explore
      latest`.
</Note>

### `explore latest`

Seed coverage for the entire app instead of a diff. The explorer maps the whole
product and self-replicates into child explorers, one per surface, so a new
project can go from zero to a baseline of coverage without a diff to anchor on.
Output is labeled as discovered journeys rather than changed journeys.

```bash theme={null}
npx momentic ai explore latest
```

`explore latest` accepts the same [shared options](#shared-options) as
`explore diff`. It defaults to a 60-minute `--timeout`.

### Shared options

These apply to both `explore diff` and `explore latest`.

<ParamField path="--dry-run" type="boolean">
  Only discover and log journeys without building Momentic tests. Building is on
  by default. Defaults to `false`.
</ParamField>

<ParamField path="--prompt <text>" type="string">
  Custom additional prompt appended to the explorer agent's instructions.
  Overrides `--prompt-file` when both are provided. Takes precedence over the
  default custom prompt in [Settings >
  Explore](https://app.momentic.ai/settings/explore).
</ParamField>

<ParamField path="--prompt-file <path>" type="string">
  Path to a file whose contents are appended to the explorer agent's
  instructions. Overridden by `--prompt` when both are provided. Takes
  precedence over the default custom prompt in [Settings >
  Explore](https://app.momentic.ai/settings/explore). Prefer this over the cloud
  setting so the prompt lives in your repo — see [Configure the
  agent](/ai/explore#custom-instructions).
</ParamField>

<ParamField path="--granularity <level>" type="string">
  How specific the proposed test plans should be: `low` covers the happy path of
  the main flows plus important failure states (e.g. a failed login), `medium`
  covers the happy path of every interaction plus important failure states, and
  `high` covers every flow in depth including the happy path and its different
  failure modes. Overrides the project config. Defaults to the config value
  (`medium` if unset). Cannot be combined with `--budget`.
</ParamField>

<ParamField path="--budget <tests>" type="number">
  Maximum number of tests to generate: the explorer targets at most this many
  test plans, prioritising the most important journeys, and stops discovering
  flows once the budget is filled. Cannot be combined with `--granularity`.
</ParamField>

<ParamField path="--no-code" type="boolean">
  Remove the explorer's git and filesystem access (`git log`/`diff`, read-file,
  grep, find-file). The explorer grounds its analysis in the running app through
  a live browser session instead.
</ParamField>

<ParamField path="--json" type="boolean">
  Print the explorer result as JSON to stdout instead of the human-readable
  summary. The payload includes changed or discovered journeys, test plans, and
  any potential product bugs the agent found. The live streaming UI is
  suppressed. Defaults to `false`.
</ParamField>

<ParamField path="--timeout <minutes>" type="number" default="15 (60 for latest)">
  Maximum number of minutes to run before aborting. On timeout the explorer
  stops and emits partial results; build and edit sub-agents are each capped at
  two-thirds of this. Defaults to 15 minutes for `explore diff` and 60 minutes
  for `explore latest`.
</ParamField>

<ParamField path="--patch" type="boolean">
  Print a `git apply`-ready patch of the authored tests to stdout instead of
  applying the configured **On successful explore** delivery. Handy for
  forked-PR runs that cannot open a pull request.
</ParamField>

The standard `-c, --config`, `-f, --filter`, and `-p, --parallel` flags apply as
they do for `triage`.

### Output behavior

When the agent writes tests, the **On successful explore** behavior in
[Settings > Explore](https://app.momentic.ai/settings/explore) decides what
happens to them: open a pull request, open a draft pull request, commit directly
(except on `main` or protected branches), print a git patch, or leave the
changes on disk. Pull requests are pushed to a `momentic-explore/` branch.

To run explore on every pull request, see
[Author tests from a diff in CI](/guides/explore/in-ci).

## Examples

Classify a local run by ID and print JSON for downstream tooling:

```bash theme={null}
npx momentic ai classify eed92602-7355-43dc-8d79-1c43029bec26 --output-format json
```

Classify an uploaded run by URL and persist the result:

```bash theme={null}
npx momentic ai classify https://app.momentic.ai/runs/eed92602 --save
```

Classify a run, then keep the chat open for follow-up questions:

```bash theme={null}
npx momentic ai classify https://app.momentic.ai/runs/eed92602 -i
```

Triage failed runs from the latest local results directory:

```bash theme={null}
npx momentic ai triage ./test-results
```

Triage only quarantined failures with two parallel sessions:

```bash theme={null}
npx momentic ai triage ./test-results --only-quarantined --parallel 2
```

Triage everything except a couple of known-flaky tests:

```bash theme={null}
npx momentic ai triage ./test-results --exclude "checkout flow" "^Legacy "
```

Preview the triage plan without changing tests or uploading the local archive:

```bash theme={null}
npx momentic ai triage ./test-results --dry-run --no-upload
```

Discover the user journeys changed by a branch, without building tests:

```bash theme={null}
npx momentic ai explore diff main...HEAD --dry-run
```

Build tests for the journeys changed since the last commit:

```bash theme={null}
npx momentic ai explore diff
```

Seed a baseline of coverage across the whole app, steered by a committed prompt
file:

```bash theme={null}
npx momentic ai explore latest --prompt-file .momentic/explore-prompt.md
```