> ## 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. > ## Agent Instructions > The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file. > For an unattended setup, first check whether Claude Code already has the Momentic plugin. With the plugin, run `npx --yes @momentic/wizard@latest -y --platform web --editor-tools none` and ignore any CLI skills-install suggestion in its output. Otherwise, run `npx --yes @momentic/wizard@latest -y --platform web --editor-tools skills`. Use `--platform ios` or `--platform android` for mobile. Never run an interactive command in a non-TTY shell. > Mo is the AI QA engineer, separate from repository YAML tests. With the Momentic plugin, use bundled mo-qa and hosted OAuth by default. Without the plugin, install only mo-qa with `npx -y qa skills --target `. Keep the requested interface. Otherwise, use hosted tools for web or mobile, including private web targets with an existing Connector. Run sessions that need a new tunnel with the qa CLI. If you can't run commands on the machine that reaches the target, ask the user to start the tunnel there, then use hosted tools unless you lack them or the CLI was requested. For a requested hosted session, use an online Connector and pass its name as access, not a CLI tunnel ID. If none is online, ask the user to run `npx -y qa tunnel start --name
` on a machine that reaches the target and wait. Do not run login or tunnel commands for them. For a requested hosted session, report unavailable tools or authentication failures without starting a CLI session. For coding-agent bridge setup, ask the user to complete `npx -y qa login`, then add momentic-hosted as a stdio server running `npx -y qa mcp`. Plugin users must explicitly opt in and disable their hosted plugin entry before adding the bridge. Claude.ai/ChatGPT connectors keep https://mcp.momentic.ai with OAuth. After hosted testing completes, read the report and summarize findings and uncovered requirements. Call `momentic_mo_stop_session` only when the user asks or agrees. For CLI sessions, unless the user wants more testing, export the report, run `qa stop --subagents` even if export fails, then summarize. The CLI is qa, not mo. Docs: https://momentic.ai/docs/mo/quickstart.md. > Ask the user to complete browser sign-in. For local CLI tools, use the exact MOMENTIC_API_KEY environment variable. If it is absent, ask the user to create a key at https://app.momentic.ai/settings/api-keys and set it in the agent's environment. Never print the key or ask the user to paste it into chat. > Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Claude Code users with the Momentic plugin should use its bundled skills and skip CLI skills installation. Otherwise, run `npx momentic skills -y --target ` or `npx momentic-mobile skills -y --target `. Both install momentic-test, momentic-maintain, and momentic-spec with web/mobile references. Use the running agent's target. The Momentic plugin also includes mo-qa; qa skills installs only mo-qa. > Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags. > Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. # Failure classification > How Momentic classifies a failed run, triages it, and picks heal, warn, or fail. Configure failure classification to categorize failed runs and choose whether to heal, warn, or fail. Review or override the diagnosis, then use AI triage to investigate and repair the test. ## AI classification Classification explains the evidence behind each category and the configured **heal**, **warn**, or **fail** action. Review the reasoning in the run viewer and override the category when the evidence supports a different diagnosis. ![Momentic classification showing Healed and Test authorship labels with reasoning about a transient UI race](https://mintcdn.com/momentic-docs/SZGi8yiMYy_JzZIR/images/reliability/test-authorship-classification.jpg?fit=max\&auto=format\&n=SZGi8yiMYy_JzZIR\&q=85\&s=2f83c5fb20b0835fbbd78eef24c30677) Classification identifies a test-authorship race and routes it to healing Configure classification in [`ai.classification`](https://momentic.ai/docs/configuration/ai#ai-classification). Category actions and project-specific guidance live in [Classification settings](https://app.momentic.ai/settings/classification). When classification puts a failure in an application bug category and your workspace has [Linear connected](https://momentic.ai/docs/mo/integrations/issue-trackers.md#file-bugs), the run viewer's **Create Linear issue** opens an issue draft whose description is a prompt for your coding agent, with the run link, the classification reasoning, and the error. It also includes the test link, branch, commit, root cause, and steps before the failure when they're available. ## AI triage The `momentic-mobile` CLI has no `ai classify` or `ai triage` commands. For mobile failures, use the [`momentic-maintain` skill](https://momentic.ai/docs/coding-agents/skills#maintenance) with the [hosted Momentic MCP server](https://momentic.ai/docs/coding-agents/mcp-server.md) for run history and quarantines and the [mobile MCP server](https://momentic.ai/docs/cli-reference/momentic-mobile/commands/mcp.md) for run artifacts. Run tests into a results directory, then triage failures from that directory: ```bash theme={null} npx momentic run --output-dir test-results npx momentic ai triage test-results --yes --timeout-minutes 10 ``` Triage can also revise a classification while it works. If live browser evidence disproves the original diagnosis, it saves the corrected category whether or not the repair succeeds, unless you pass `--no-save`. Triage never overwrites a category you set by hand in the run viewer. A failure that was transient or came from outside your test can end with **No test change**: a successful outcome that keeps the test as it is. Triage delivers a repair only when it changes the test or a module, so it does not open a pull request when those files are unchanged. A failing `run` identifies the failed step and suggests the triage command: ```text theme={null} [2/2] ✘ slow-nav.test.yaml (38s) 1) slow-nav.test.yaml Assertion failure An AI check failed for a legitimate reason, such as a missing element, a change in the page structure, or an unexpected state (e.g. loading state). Failed at: 5 | - click: the Submit button > 6 | - assert: 7 | that: The error message "Your password is invalid!" is visible https://app.momentic.ai/runs/cef3a8f6-8347-406d-b496-ac43c71d627f Tests 2 failed | 0 passed (2) Duration 67s Run momentic ai triage to attempt automatic fixes · https://momentic.ai/docs/reliability/failure-classification#ai-triage ``` Triage reads the failing runs, tests candidate fixes in a live browser, and reports each repair with its reasoning: ```text theme={null} $ npx momentic ai triage test-results --yes --timeout-minutes 10 Momentic CLI v3.57.0 Healing 2 tests · 1 worker source ./test-results Triage [tool call] momentic_get_run(runId: 06189c5d-...) [tool call] momentic_get_step_result(runId: 06189c5d-..., includeAiInput: true) [tool call] preview_step(step: --step-type TYPE --description "the Username input" ...) [tool call] run_step(fromStep: ..., toStep: ...) ✓ wrong-assert.test.yaml (1m03s) Proposed solution: replace the unsupported greeting assertion with the minimum positive-login journey. The main flow now fills the Username input with student, fills the Password input with Password123, clicks Submit, and retains a single semantic AI assertion confirming a successful login. ✓ slow-nav.test.yaml (53s) Proposed solution: insert two focused TYPE steps before the existing Submit action: fill the Username input with student, then fill the Password input with incorrectPassword. The existing assertion was retained unchanged. Tests 2 healed (2) ``` The `slow-nav` repair was written to disk as: ```diff slow-nav.test.yaml theme={null} steps: + - fill: + text: student + into: the Username input + - fill: + text: incorrectPassword + into: the Password input - click: the Submit button - assert: The error message "Your password is invalid!" is visible ``` The test previously submitted an empty form, so the page showed the username-invalid error and the password-invalid assertion could never pass. Triage restored the intended login flow instead of weakening the assertion. For an interactive investigation, install the [coding agent skills](https://momentic.ai/docs/coding-agents/skills.md) and the [MCP server](https://momentic.ai/docs/coding-agents/mcp-server.md), then invoke `momentic-maintain` with the run ID. To keep CI passing while a heal is pending, see [Let the verdict gate CI](#let-the-verdict-gate-ci). For CI, make sure triage runs even when the test step fails. Each repair attempt starts a browser, so if browsers run locally, size the runner for up to one browser per `--parallel` worker (one by default): ```yaml .github/workflows/momentic.yml theme={null} - name: Run tests continue-on-error: true run: npx momentic run --output-dir test-results - name: Triage failing tests if: always() run: npx momentic ai triage test-results --yes --timeout-minutes 10 ``` The complete [auto-heal workflow](https://github.com/momentic-ai/examples/blob/main/.github/workflows/test-ai-heal-demo.yml) includes authentication, permissions, checkout, and browser setup. See the [GitHub Actions guide](https://momentic.ai/docs/running-tests/ci/github-actions.md) or another [CI integration](https://momentic.ai/docs/running-tests/ci/custom-setups.md) for runner setup. The [`momentic ai` reference](https://momentic.ai/docs/cli-reference/momentic/commands/ai#triage) covers alternative run selectors, queue filters, parallelism, delivery overrides, and exit codes. ## Classify during the run In-flow classification runs the classification agent inside `momentic run`, when a run exhausts its retries. The CLI includes a category, reasoning, and triage action when the run exits, so CI does not need a separate classification step. Prefer this over invoking [`momentic ai classify`](https://momentic.ai/docs/cli-reference/momentic/commands/ai#classify) afterwards. ### Enable it Turn it on in `momentic.config.yaml`: ```yaml momentic.config.yaml theme={null} ai: classification: true ``` The toggle is versioned with your tests and applies to local and CI runs. See the [AI configuration reference](https://momentic.ai/docs/configuration/ai.md#ai-classification) for every field. ### What happens on a failure When a run fails after all retries, the CLI shows a `Classifying failure` step and the agent inspects the failed step, screenshots, error details, evidence from past runs, and git context when available. The CLI writes the verdict into the run's results: * The category, reasoning, confidence, and recoverability appear in the CLI output and in the run viewer's failure details. * The category's configured action (`heal`, `warn`, or `fail`) is attached to the run, so downstream steps such as [`momentic ai triage`](#ai-triage) and [`momentic results check`](https://momentic.ai/docs/cli-reference/momentic/commands/results) can act on it without re-classifying. * With [transient failure recovery](https://momentic.ai/docs/reliability/auto-maintenance.md#failure-recovery) enabled, a failure the classifier judges one-time recoverable triggers an in-run recovery attempt guided by its reasoning. Failure categories, their actions, and the optional custom prompt stay cloud-managed in [Settings > Classification](https://app.momentic.ai/settings/classification). ### Let the verdict gate CI By default the classifier only records a category. Every failed test still fails CI. Set `overrideExitCode: true` so failures routed to `heal` or `warn` exit `0`. The job passes while the failure is repaired or reported. Failures routed to `fail` (for example `BUG`) still exit `1`. ```yaml momentic.config.yaml theme={null} ai: classification: enabled: true overrideExitCode: true ``` To opt in for a single invocation instead, pass [`--classify-override-exit-code`](https://momentic.ai/docs/cli-reference/momentic/commands/run) to `momentic run`. To skip classification for one invocation, pass `--no-classify`. ### In-flow vs `momentic ai classify` `momentic ai classify` runs the same agent as a separate command against already-finished runs. Prefer the config-driven in-flow setup for CI: * The in-flow setup needs no separate CI command or run selector. The verdict is part of the run result when `momentic run` exits. * The exit-code override can only be applied while the run is still deciding its exit code, so `overrideExitCode` works only in-flow. * The CLI saves the verdict automatically; `ai classify` persists only with `--save`. Reach for `ai classify` when you want to re-classify a past run, classify runs from an older CLI version, batch-classify a run group or commit, or ask follow-up questions with `--interactive`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.