---
title: "Pull request checks"
description: "See what every pull request does to the systems your agents touch, before it merges."
canonical: "https://agenttwin.si/docs/pull-request-checks/"
---

# Pull request checks

See what every pull request does to the systems your agents touch, before it merges.


Code review shows what a pull request changes in your code. The AgentTwin check shows what it changes in **your systems**: which writes to Stripe, Salesforce, Slack or Okta happen, how often, and what goes wrong when a service misbehaves. It runs on every pull request and reports the result on the pull request itself.

## What the check does

1. **Reruns your locked twin checks.** Each check you locked after fixing a bug runs again against the pull request. Its definition comes from the base branch, so a pull request cannot weaken its own check.
2. **Diffs the side effects.** For a check whose code changed, the same twin, data and injected failure run on the base and on the pull request. The report shows every system's record count before and after, so "Stripe payment intents 1 → 2" is visible at a glance.
3. **Flags untested writes.** New or changed code that reaches an external service with no twin check gets a warning on the exact line.
4. **Tells you why and where.** Failures name the injected fault, the likely cause, the money at risk and the lines that made the writes, and include a fix task for Claude Code, Codex or Cursor.

| Result | Meaning |
| --- | --- |
| Passed | Every twin check held. |
| Failed | A twin check failed. Merging would ship the failure; the check blocks if you require it. |
| Needs a check | Changed code reaches a service that no twin check covers yet. |
| Incomplete | A check could not run, for example because pull-request code needs an isolated runner. Never reported as a pass. |

## Add it to your repository

**With the GitHub App** (no GitHub Actions minutes): in the dashboard, open **Settings → Add AgentTwin to GitHub** and pick the repositories. The **AgentTwin** check then appears on every pull request, and the **Checks** tab shows results across all repositories.

**With GitHub Actions:**

```bash
npx agenttwin check install
```

This writes `.github/workflows/agenttwin.yml`. Commit it; the next pull request gets the check, an inline annotation on each failing line and one comment that updates on every push.

**Anywhere else**, run it in any CI or on your laptop before you push:

```bash
npx agenttwin check --base origin/main
```

Exit codes: `0` passed or needs a check, `1` failed, `2` incomplete. Use `--markdown report.md` for the report, or `--json` for the data.

## Where the code runs

Locked checks execute pull-request code. In GitHub Actions and on your machine, that is the same trust as your existing tests. The hosted GitHub App executes it only on an isolated runner with a digest-pinned image. Without one, it still maps changed lines to the services they reach and reports covered changes as incomplete.

Your code runs against twins with synthetic data; nothing reaches a real service. See [safety and limits](/docs/safety/).

## Create your first check

1. Run `npx agenttwin init` and prepare a workflow.
2. Run it with a fault until it fails, fix the code, and run it again. A run that passes after a failure is locked automatically as `.agenttwin/regressions/<name>.json`.
3. Commit the file. From then on, every pull request reruns it.