momentic ai - Momentic

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

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.

npx momentic ai classify --run-id <runIdOrUrl>
npx momentic ai classify --run-group-id <runGroupIdOrUrl>
npx momentic ai classify --git-commit <sha>

Options

--run-id <runIdOrUrl...>

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.

--run-group-id <runGroupIdOrUrl>

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>).

--git-commit <sha>

string

Classify every failed run recorded at the given git commit SHA, across all run groups.

--skip-classified

boolean

When targeting a run group or commit, skip runs that already have a saved classification. Useful for resuming a partially-completed batch.

-p, --parallel <parallel>

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.

--output-format <format>

string

Output format for the classification. Defaults to text. Use json to print only the structured payload to stdout.

--quiet

boolean

Suppress the agent’s streamed reasoning. Redundant when --output-format json is set.

--save

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.

--no-cache

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.

-i, --interactive

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.

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:

{
  "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:

[
  {
    "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.

`triage`

Runs the triage agent over a local results archive from momentic 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.

For a copy-paste CI setup and the different integration paths, see Auto-heal failing tests in CI.

Triage can take a while. When you only need to know which runs failed (not to repair them), use momentic results check over the same results folder. It reports the failed, canceled, and quarantined runs so you can decide what to do.

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

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.

Target and output

--run-group-id <runGroupIdOrUrl>

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.

--run-id <runIdOrUrl...>

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.

--git-commit <sha>

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.

--dry-run

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.

--on-heal-success <behavior>

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 for this run.

--on-heal-fail <behavior>

string

What happens to tests the agent cannot fix. Accepts warn, fail, or quarantine. Overrides the On failed heal Healing setting for this run.

--json

boolean

Suppress progress output and print the triage result as JSON.

-i, --interactive

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.

--no-upload

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.

Common flags

-c, --config <config>

string

Path to the Momentic configuration file. Defaults to momentic.config.yaml in the current directory.

-f, --filter <filter>

string

When using workspaces, load the project whose name matches the filter.

-p, --parallel <parallel>

string

Number of healing attempts to run in parallel. Each attempt opens its own browser session. Defaults to 1.

--limit <limit>

number

Abort when the number of healable failed runs exceeds this threshold. Must be a positive integer.

--exclude <excludePatterns...>

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.

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.

Environment

--env <env>

string

Environment to run replays in. Overrides any environment configured on the test itself.

--url-override <urlOverride>

string

Override the base URL of the test or environment during the replay.

--custom-headers <customHeaders...>

array

Custom headers to include in the replay. Specify multiple headers separated by spaces.

--input-csv <inputCsv>

string

CSV file containing input data for the replay. Each row is used as input for a separate run.

Browser

--browser <browser>

string

Override the browser used for replays. Accepts chromium, chrome, or chrome-for-testing.

--headful-browser [headfulBrowser]

boolean

Launch healing browser sessions headfully by default. Useful for visually watching the agent work. Env: MOMENTIC_HEADFUL_BROWSER.

--pixel-ratio <pixelRatio>

number

Device pixel ratio for the healing browser. Set to 2 on macOS Retina or other HiDPI displays.

Caching

--save-cache

boolean

Always save updated step caches after a successful heal, even on the main and other protected Git branches.

--disable-cache

boolean

Disable step caches entirely. Steps run without cached data and no caches are saved.

--regenerate-heal

boolean

Ignore previously cached heal solutions during triage so failures are healed from scratch. Newly successful heals are still saved; step caches are unaffected.

Quarantine

--only-quarantined

boolean

Only attempt to heal quarantined tests. Failed runs outside quarantine are ignored.

Setup

--start <start>

string

Command to run before the replay begins. Useful for booting a local dev server.

--wait-on <waitOn>

string

Resource to wait for before the replay begins. Accepts anything supported by wait-on.

--wait-on-proxy <waitOnProxy>

string

HTTP proxy used when polling --wait-on. Provide the full URL including protocol, optional credentials, host, and port.

--wait-on-timeout <waitOnTimeout>

number

Timeout (in seconds) for --wait-on. Defaults to 60. Triage fails if the resource is not reachable in time.

CI

--timeout-minutes <timeoutMinutes>

number

Maximum total triage time, in minutes. When reached, in-flight healing attempts stop and the current results are flushed.

--quiet

boolean

Suppress the agent’s streamed reasoning.

-y, --yes

boolean

Skip all confirmation prompts. Enabled by default when CI is set.

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.

`explore`

The explore agent is in beta and may change.

For the conceptual overview, see the Explore agent 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:

# 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.

npx momentic ai explore diff main...HEAD

[commitRange]

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.

explore diff accepts every shared option below.

--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.

`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.

npx momentic ai explore latest

explore latest accepts the same shared options as explore diff. It defaults to a 60-minute --timeout.

Shared options

These apply to both explore diff and explore latest.

--dry-run

boolean

Only discover and log journeys without building Momentic tests. Building is on by default. Defaults to false.

--prompt <text>

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.

--prompt-file <path>

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. Prefer this over the cloud setting so the prompt lives in your repo — see Configure the agent.

--granularity <level>

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.

--budget <tests>

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.

--no-code

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.

--json

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.

--timeout <minutes>

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.

--patch

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.

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 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.

Examples

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

npx momentic ai classify eed92602-7355-43dc-8d79-1c43029bec26 --output-format json

Classify an uploaded run by URL and persist the result:

npx momentic ai classify https://app.momentic.ai/runs/eed92602 --save

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

npx momentic ai classify https://app.momentic.ai/runs/eed92602 -i

Triage failed runs from the latest local results directory:

npx momentic ai triage ./test-results

Triage only quarantined failures with two parallel sessions:

npx momentic ai triage ./test-results --only-quarantined --parallel 2

Triage everything except a couple of known-flaky tests:

npx momentic ai triage ./test-results --exclude "checkout flow" "^Legacy "

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

npx momentic ai triage ./test-results --dry-run --no-upload

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

npx momentic ai explore diff main...HEAD --dry-run

Build tests for the journeys changed since the last commit:

npx momentic ai explore diff

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

npx momentic ai explore latest --prompt-file .momentic/explore-prompt.md

​classify

​Options

​Output

​Categories

​triage

​Arguments

​Target and output

​Common flags

​Environment

​Browser

​Caching

​Quarantine

​Setup

​CI

​Exit codes

​explore

​explore diff

​explore latest

​Shared options

​Output behavior

​Examples

`classify`

Options

Output

Categories

`triage`

Arguments

Target and output

Common flags

Environment

Browser

Caching

Quarantine

Setup

CI

Exit codes

`explore`

`explore diff`

`explore latest`

Shared options

Output behavior

Examples