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

# Explore agent

> Discover the user journeys changed by a diff and author tests to cover them, from the CLI or in CI.

The explore agent reads a git diff and determines what changed for users, then
proposes (or builds) Momentic tests to cover it. Reach for it to keep coverage
current with the product without someone remembering to write a test for every
pull request.

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

## What it does

Given a base and head ref, the agent:

* Diffs the two refs and identifies user-facing changes. These are not always
  frontend edits: a backend change that surfaces to the user counts, and the
  agent reasons about which parts of the app are affected and how.
* Maps each change to the user journeys it touches.
* Checks existing tests for coverage. When a test already partially covers a
  journey, it proposes an edit to that test rather than a brand-new sibling.
* Surfaces potential product bugs it finds while exploring, including severity,
  ordered reproduction steps, and supporting evidence.
* By default, opens a live browser session and authors or edits the tests,
  drawing on your [knowledge base](/docs/ai/knowledge-base) for terminology and
  flows. Pass `--dry-run` to skip this and only discover journeys.

The agent's analysis is read-only with respect to your application code. It
describes observable behavior and the test-coverage implication; it does not
propose product code changes.

## Commands

`explore` has two subcommands:

* **`momentic ai explore diff [commitRange]`**: explore a git diff window and
  cover the journeys that changed.
* **`momentic ai explore latest`**:
  [seed coverage for the whole app](#seed-coverage-for-the-whole-app) instead of
  a diff.

## Build vs. discover

By default, the agent authors or edits tests for each discovered journey:

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

The commit range follows `git diff` 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 parent.

With `--dry-run`, it only discovers and logs the changed journeys without
writing tests, which is useful for inspecting what it would do:

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

When run in CI (GitHub Actions, CircleCI, GitLab, Buildkite, Azure DevOps), the
commit range defaults to the current pull request's diff window, so you usually
run `momentic ai explore diff` with no range. See
[Author tests from a diff in CI](/docs/guides/explore/in-ci) for a ready-to-use
workflow. If your tests live in a separate repo from your application code, see
[Explore a code diff into a separate test repo](/docs/guides/explore/poly-repo-diff)
or
[Seed a separate test repo against a running app](/docs/guides/explore/poly-repo-seed).

## Configure the agent

### Custom instructions

Give the agent project-specific guidance through a **custom prompt**: a freeform
text block appended to the agent's built-in instructions. Use it to describe how
to access your app, which flows matter most, and any conventions the generated
tests should follow.

Keep the custom prompt in a file in your repository and pass it with
`--prompt-file`:

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

A committed file is version-controlled, reviewed alongside your code, and stays
in sync with the same repo the agent explores. Use `--prompt` for a quick
one-off override:

```bash theme={null}
npx momentic ai explore diff \
  --prompt "All tests should start by signing in with the Log in module."
```

You can pass `--prompt` and `--prompt-file` multiple times. The combined
instructions are all `--prompt-file` contents followed by all `--prompt` values,
each in the order you pass them. So you can, for example, combine a committed
repo-overview file with a bug-bash-specific instructions file:

```bash theme={null}
npx momentic ai explore diff \
  --prompt-file .momentic/repo-overview.md \
  --prompt-file .momentic/bug-bash.md \
  --prompt "Focus on the new checkout flow."
```

To apply guidance without passing a flag, or to share it with the
result-classification and triage agents, commit an [agent skill](/docs/ai/skills).
Skills that target `explore` are applied automatically and stack on top of
`--prompt` and `--prompt-file`.

### Write a good prompt file

The prompt is appended to the agent's built-in instructions, so treat it as the
project-specific layer on top: focus on what the agent cannot infer from the
code and the running app. A good prompt file is concise, concrete, and stable
across runs: a page or two of Markdown that a new teammate could also follow.

Cover the things that reliably improve generated tests:

* **Access and auth.** How to reach the app and sign in: which
  [auth module](/docs/guides/auth/overview) to call and where (e.g. "start every test
  by calling the `log-in` module in the `before` section"), which test accounts
  or roles to use, and any environment or feature-flag setup a flow depends on.
* **Where to focus.** Areas of the product that matter most, and areas to skip
  entirely (admin-only screens, third-party embeds, destructive actions).
* **Domain terminology.** Product-specific names for surfaces, states, and
  actions so the agent describes journeys the way your team does.
* **Conventions for generated tests.** Naming, folder placement, and any
  patterns the tests should follow (reuse existing modules, prefer a given
  assertion style).
* **Guardrails.** Data or actions the agent must never touch: do not send real
  emails, do not delete records, do not touch production billing.

### Knowledge base

The agent also draws on your [knowledge base](/docs/ai/knowledge-base). Add entries
for product terminology, navigation shortcuts, or domain rules that should
influence the tests it writes. The agent retrieves relevant items automatically
during a run.

## Seed coverage for the whole app

A diff is the usual starting point, but you can also explore the entire product
at once with `momentic ai explore latest`. Instead of a commit range, the agent
maps the whole app 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. Its output is labeled as discovered user journeys instead of changed
journeys.

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

## Control how deep it goes

`--granularity` sets how specific the proposed test plans are:

| Level    | Coverage                                                                         |
| -------- | -------------------------------------------------------------------------------- |
| `low`    | Happy path of the main flows, plus important failure states (e.g. failed login). |
| `medium` | Happy path of every interaction, plus important failure states. The default.     |
| `high`   | Every flow in depth: the happy path and its different failure modes.             |

The flag overrides the per-project default; leave it unset to use the project
config (`medium` if not configured).

For a hard cap on output, pass `--budget <tests>` instead: the agent targets at
most that many test plans, prioritising the most important journeys, and stops
discovering flows once the budget is filled. `--budget` and `--granularity`
cannot be combined.

`--timeout` caps the wall-clock budget for a run (default 15 minutes, or 60
minutes for `explore latest`). On timeout the agent stops and emits whatever
partial results it has rather than running indefinitely, which keeps a stuck
build from consuming a full CI job. Build and edit sub-agents each receive
two-thirds of the overall timeout, so one child agent cannot consume the whole
budget.

## Output

The human-readable output lists discovered or changed journeys, proposed test
plans, and any potential product bugs the agent found. Potential bugs include a
title, severity, summary, reproduction steps, and evidence, so you can decide
whether to fix the product or adjust the generated tests.

Pass `--json` to print the same result as a single JSON object and suppress the
streaming UI:

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

Every run also appears on the
[Explorations page](https://app.momentic.ai/explorations) in the dashboard, with
the discovered journeys, test plans, and potential bugs, including each bug's
reproduction steps and screen recording. When Slack notifications are configured
for explore, potential bugs are also included in the org-channel notification
and the author DM.

To run the agent as a bug hunter that actively verifies each discovered journey
in a live browser, see
[Bug bash with the explore agent](/docs/guides/explore/bug-bash).

## What happens to the tests

When the agent writes tests, the **On successful explore** behavior in
[Settings > Explore](https://app.momentic.ai/settings/explore) decides the
outcome:

| Behavior               | What it does                                                           |
| ---------------------- | ---------------------------------------------------------------------- |
| **Pull request**       | Opens a pull request with the new and edited tests.                    |
| **Draft pull request** | Opens a draft pull request.                                            |
| **Direct commit**      | Commits and pushes, except on `main` or a protected branch (draft PR). |
| **Patch**              | Prints a git patch to stdout to apply with `git apply`.                |
| **Leave on disk**      | Writes the changes without committing or opening a pull request.       |

Pull requests are pushed to a `momentic-explore/` branch. Because the output is
a reviewable PR, generated coverage lands in the same review flow as any other
change rather than appearing silently.

## Related

* [What is AI-native testing?](/docs/get-started/ai-native-testing#author-with-product-context)
* [Author tests from a diff in CI](/docs/guides/explore/in-ci) for a ready-to-use
  workflow
* [Bug bash with the explore agent](/docs/guides/explore/bug-bash) to hunt for
  product bugs instead of building tests
* [`momentic ai explore` CLI reference](/docs/cli-reference/momentic/commands/ai#explore)
* [Post-run heal agent](/docs/reliability/auto-maintenance#permanent-healing) for
  repairing failing tests
* [App graph](/docs/ai/app-graph) for tracking coverage of discovered journeys