Run your first Mo session - Momentic

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

Use your coding agent to set up Mo and run a session against your app, then review the test cases, verdicts, and reported bugs. This example checks a web storefront’s cart. You do not need to create test files or add code to your repository. The mo-qa skill prepares the brief, follows the session, and exports the report. You can also install the CLI and skills from your terminal or start in the app.

Prerequisites

For firewall rules and IP allowlists, see Configure network access.

Setup with coding agent

Open Claude Code, Cursor, Codex, Copilot, or another coding agent in your project directory and paste the prompt below. It installs the qa CLI and Mo skills, then asks for the target, access, and test boundaries before starting a session.

Copy the setup prompt

Help me set up Mo, Momentic's AI QA engineer, in this project.

Here are the docs: https://momentic.ai/docs/llms.txt

## What to do

1. Install the qa CLI: `npm install -g qa`, or `curl -fsSL https://cli.momentic.ai/qa | sh` without npm. The standalone installer writes to `~/.local/bin`; add it to PATH if `qa` is not found. Verify with `qa --version`. For a legacy `mo` installation, follow https://momentic.ai/docs/cli-reference/mo/overview#troubleshoot-the-install before continuing. Do not use `npx mo`; that npm package is a different project.
2. Authenticate. If `MOMENTIC_API_KEY` is set or `~/.momentic/auth.json` exists, use it — `qa doctor` validates the key against the server and reports `api key` as `valid` or `check failed`; a bad key also shows up as an auth error on `qa start`. If not, ask me to run `qa login` or paste a key from https://app.momentic.ai/settings/api-keys, then run `export MOMENTIC_API_KEY=<the key I give you>` — if your shell drops env vars between commands, prefix each `qa` command with `MOMENTIC_API_KEY=<the key>` instead. Never run the browser login yourself.
3. Install the Momentic skills: `qa skills -y` — installs mo-qa plus the maintain, spec, and triage skills.
4. Ask me what to bash: the target URL (a deploy preview or my local dev server), any credentials, and what counts as a bug. For a local target run `qa tunnel start <address>` and keep the `tunnelId` it prints.
5. Kick off the bash. Read the `mo-qa` SKILL.md where `qa skills` wrote it (`.claude/skills`, `.cursor/skills`, `.agents/skills`, `.github/skills`, or `.opencode/skills`, depending on your agent), write the brief (target URL, expected behavior, sign-in steps, test-data rules, out-of-bounds actions, acceptance criteria), and run `qa start "<brief>"` — add `--tunnel <tunnelId>` when the target is local. It prints JSON with `sessionId` and `webUrl` — keep both (parse with `jq` if you have it). Do not invent scope, credentials, or acceptance criteria.
6. A bash is a hosted session that typically runs 10-30+ minutes. `qa wait <session-id>` blocks indefinitely — it has no timeout flag, so prefer polling `qa status <session-id>` and `qa read <session-id> --from start --json`, or run `qa wait` in the background. Poll `displayState`: `qa status` and `qa read --json` expose it directly; the exported `report.json` stores it at `summary.displayState`; `sessionState` carries the lifecycle state and `state` is the legacy field. `qa report <session-id> --require-idle` errors with 'Report not ready' unless `displayState` is `ready` or `sleeping` — keep polling while Mo is working, ask me for input on `needs_you`, and report `failed_start`, `failed`, or `cancelled` instead of continuing to poll (without the flag it exports a partial snapshot mid-bash). Then show me the report before you call it done.

## Critical rules

- Never run an interactive command in a non-TTY shell — `qa login` opens a browser; ask me to run it, or use `MOMENTIC_API_KEY` (`--api-key` works on operational commands, not on `login`).
- If `MOMENTIC_API_KEY` disappears between shell commands, prefix each `qa` command with it instead of relying on `export`.
- Do not invent brief details — ask me for the URL, credentials, and boundaries first.
- Use the mo-qa skill and the qa commands in the docs — do not invent steps or flags.
- Show me the report before you tell me the bash is done.

Run qa skills to select your coding agents and install mo-qa (or use npx skills add https://github.com/momentic-ai/skills --skill mo-qa without the CLI). Then /mo-qa bug bash <scope> writes the brief, starts the session, follows it, exports the report, and can fix and recheck the bugs it finds. See install the Mo skill, use the Mo CLI, and the qa CLI reference.

Start from GitHub

Connect the Momentic GitHub App in Settings > Integrations, then connect your personal GitHub account in Settings > Profile. In a new comment on an open pull request, name Mo and the preview URL with a testing brief:

@momentic-ai please test checkout on https://preview.example.com.
Check discounts and failed payments. Do not submit an order.

Mo posts a session link, then updates the PR with findings and available recordings when testing finishes. Open the session to answer access questions and review the coverage. See the GitHub integration for repository context, label triggers, CLI starts, and commit checks.

Start from a terminal

Install the CLI and skills from your project root, then run Mo in your coding agent. This is the recommended terminal setup. The npm install requires Node.js 22.12 or later in the 22.x series, or Node.js 24 or later:

npm install -g qa
qa login
qa skills

Select your coding agent when qa skills asks. It installs mo-qa and adds a pointer to your agent’s project instructions. Open that project in your coding agent and paste this request, replacing the example URL with your app’s URL:

/mo-qa bug bash the cart on https://staging.example.com/cart.
Use a signed-out shopper. Check quantity changes, removal, totals,
and persistence after refresh. Do not place an order or submit payment.

The agent uses the skill to prepare the brief, start and follow the session, and export the report. Answer any questions about access, expected behavior, or boundaries before it continues. If your agent does not support slash commands, ask it to load the mo-qa skill and run the same brief. See install the Mo skill for the agent-specific paths.

Run CLI commands directly

Use these commands when driving a session yourself or writing a shell script. Replace the example URL with your app’s URL:

qa start "Test the cart on https://staging.example.com/cart.
Use a signed-out shopper. Check quantity changes, removal, totals,
and persistence after refresh. Do not place an order or submit payment."

qa start prints sessionId and webUrl; it returns before testing finishes. Open webUrl to follow the session. Replace SESSION_ID below with the returned ID to wait for the current work and export the report when it finishes:

qa wait SESSION_ID &&
  qa report SESSION_ID --require-idle --output mo-report

If Mo needs input, qa wait exits with code 2 and the export does not run. Answer in the session chat, then rerun the command. A stopped session exits with code 4; review its partial coverage in the app before resuming. Read mo-report/report.json and the finding files it lists. Compare the test cases and verdicts with your brief, then review each bug’s reproduction steps and available evidence. --require-idle checks readiness once; if it reports Report not ready, keep following the session before retrying the export. See use the Mo CLI for authentication without a browser and session reports for the exported fields.

Start in the app

  1. Open the composer

Open Mo in the Momentic app. For a web session, put the exact URL in your brief, including the path of the area you want checked. If mobile targets are available in your workspace, select iOS or Android and choose an uploaded build instead.

  1. Write a narrow brief

Name one area, the expected behavior, and the actions Mo must not take. For a storefront cart, replace the example URL below with your running app’s URL:

Test the cart on https://staging.example.com/cart as a signed-out shopper.
Add a product, change its quantity, and remove it. The item count and total
must update after each action and persist after refreshing the page.
Do not sign up, place an order, submit a payment, or change account settings.

For authenticated flows, provide the test account and sign-in instructions. To reuse that account, save its credentials in a workspace environment. See write a good brief for test data and scope boundaries. Send the brief with Send message to start the session.

  1. Watch the run

Test cases and bugs appear while Mo works. Answer any requests for access or missing test data in the session chat. Open a sub-agent’s transcript to see what it checked. Sending a text message while Mo is working steers its active turn between tool calls. Attachments and setup changes wait for the next turn.

  1. Read the report

When the session is ready for review, compare the test cases with your brief. Check each verdict: verified, issues found, or blocked. Review the expected behavior, actual behavior, and reproduction steps for each bug. Watch its recording when one is available. A blocked case is unverified coverage; a report with no bugs does not prove every requested flow was tested. Ask Mo to retry blocked cases after you provide access or missing test data. If a requested case is missing, ask Mo to add and check it. See session reports.

  1. Triage what it found

Accept a bug, or mark it as “works as intended” and give the reason. Review and accept the suggested knowledge base entry to make it available to later sessions. You can reject the entry or skip knowledge without changing the triage decision. After a fix is deployed to the target, ask Mo to rerun the reproduction. See triage and fix and recheck.