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

# AI Select

> Select the tests most likely to catch regressions from a code change, using your code index and App Graph.

AI Select reads a git diff and runs a focused set of Momentic tests that covers
the changed behavior. Use it in pull request CI when running every test would
take too long.

<Warning>
  AI Select is in alpha and may change. [Contact us](https://momentic.ai/sales)
  to join the waitlist.
</Warning>

## Run selected tests

Run AI Select from the root of your git repository:

```bash theme={null}
npx momentic run . --ai-select
```

In supported CI providers, Momentic detects the pull request base ref. Use
`--ai-select-base` when you need to set it explicitly:

```bash theme={null}
npx momentic run . --ai-select --ai-select-base origin/main
```

Tests added, renamed, or edited in the diff are always included. If AI Select
cannot build a safe selection, it runs the full in-scope test set instead.

## How selection works

AI Select combines three sources of evidence:

1. The git diff identifies the code and behavior that changed.
2. A local code index traces imports and downstream consumers in your
   repository.
3. The [App Graph](/docs/ai/app-graph) connects product journeys and UI states to the
   tests that exercised them in real runs.

The App Graph provides runtime relationships that static imports cannot express,
such as a backend change surfacing in a browser flow. Selection quality improves
as the graph observes more of your application and test suite.

Build-graph systems such as Bazel are effective at selecting work within a
declared dependency graph. Applying that approach to end-to-end tests requires
teams to manually define and maintain the relationship between build targets,
services, and tests. Code imports also stop at network and product boundaries:
they do not show that a frontend journey depends on an API, queue, data store,
or third-party integration. App Graph adds those observed runtime relationships
without requiring every cross-system dependency to be orchestrated by hand.

The test budget is a soft cap. AI Select can exceed it when more tests are
needed to cover distinct changed behavior.

```bash theme={null}
npx momentic run . --ai-select --ai-select-budget 10
```

## Use the code index in GitHub Actions

Check out full git history and install the code-index parsers before running AI
Select:

```yaml theme={null}
steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0
  - run: npx momentic install-codetools
  - run: npx momentic run . --ai-select
```

See the
[complete GitHub Actions example](https://github.com/momentic-ai/examples/blob/main/.github/workflows/test-ai-select.yml)
for setup, code-index caching, standalone selection output, test execution, and
result uploads.

## Preview a selection

Use shadow mode to compare a selection with the full test run before using it to
gate pull requests. Momentic still runs every in-scope test and records which
ones AI Select would have skipped.

```bash theme={null}
npx momentic run . --ai-select-dry-run
```

To inspect a selection without running tests, use `momentic ai select`:

```bash theme={null}
npx momentic ai select --base origin/main
npx momentic ai select --base origin/main --json
```

In GNU/Linux CI, pipe the JSON selection through `jq` when you want to inspect
or transform it before running the selected paths:

```bash theme={null}
npx momentic ai select --base origin/main --json \
  | jq -r '.selectedTests[].testPath' \
  | xargs -r npx momentic run
```

Use `momentic run --ai-select` when you do not need to customize the handoff; it
performs selection and execution in one command.

## Benchmark

The benchmark uses real code changes across frontend, backend, CLI,
shared-library, configuration, and non-behavioral scenarios. The GPT-5.5 Codex
baseline receives the same changes and candidate test files as AI Select, but
does not use the App Graph or AI Select's investigation workflow.

| Metric            | AI Select  | GPT-5.5 Codex baseline |
| ----------------- | ---------- | ---------------------- |
| Average precision | **100.0%** | 81.5%                  |
| Average recall    | **97.0%**  | 95.5%                  |
| Average F1        | **98.1%**  | 82.4%                  |
| Perfect cases     | **92%**    | 67%                    |
| Average latency   | **43.1s**  | 56.1s                  |

We can share the raw results and reproduction harness on request.

## Notes

* AI Select needs enough git history to resolve the base ref. Use
  `fetch-depth: 0` with `actions/checkout`.
* The code index currently analyzes TypeScript and JavaScript imports. App Graph
  evidence can still connect behavior across other boundaries.
* A budget limits selection size, not safety behavior. Edited tests are still
  included, and AI Select can fall back to running all tests.