> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The TestDriver Agent

> How the TestDriver agent behaves on GitHub issues, pull requests, and @mentions

The TestDriver agent is an AI teammate in your GitHub repository. It is
**code review that runs your app**. It does not only read a diff and guess
what can break. It starts a real sandbox, controls the real app, and reports what
really happens.

## Scope: it only builds and maintains tests

The agent has one purpose. It does one thing: it **writes, debugs, fixes, and keeps
automated tests** with TestDriver. It reviews pull requests. It writes and runs
a test against the change. It does not do work that is not in scope. It does not edit
your application code, fix product bugs, answer other programming questions, or
act as a general coding assistant.

## How it behaves depends on the surface

The agent reacts to three different GitHub surfaces. Its behavior is
different on each one.

| Surface                    | Trigger                | What it does                           |
| -------------------------- | ---------------------- | -------------------------------------- |
| **Pull request opened**    | Automatic (no mention) | Silent, evidence-based **code review** |
| **Issue opened**           | Automatic (no mention) | **Onboarding / test-building**         |
| **@mention** (issue or PR) | You mention the bot    | Interactive, chatty conversation       |

## Pull requests — automatic code review

When a pull request is **opened**, the agent reviews it automatically. Nobody has
to ask.

* **The review is the deliverable, not chatter.** No person asks for an automatic review.
  Thus the agent stays quiet while it works. It posts a **single review
  comment** at the end. It does not put many inline threads across the diff. It does not
  tell each step.
* **It runs the change when it can.** Its default first move is to start a session,
  work out what the PR changes from a user's point of view, and write and run a
  TestDriver test that exercises exactly that. A bug it *watched happen* is far
  more valuable than one it inferred.
* **Findings are labeled by how they were found.** Each finding is marked
  `observed` (proven by actually running the change) or `suspected` (reasoned out
  from reading the diff). If the installation isn't signed in to TestDriver, the
  agent can't run anything, so it reviews by reading and marks every finding
  `suspected`.
* **It focuses on real bugs.** Logic errors, regressions, broken edge cases,
  mishandled errors — not style, naming, or "consider extracting this."
* **Zero findings is a good review.** If the change looks correct, it says so in a
  sentence. If there's nothing worth reviewing (only lockfiles, generated files, or
  formatting), it posts nothing at all.
* **It comments, it never blocks.** The review is always a `COMMENT` — it never
  approves and never requests changes, so it can't gate a merge.

It also fires a native GitHub **Check Run** for the PR's TestDriver suite, and
re-runs that check on every push (not a full re-review — push more commits and
@mention the agent if you want it to review again).

<Note>
  The agent never reviews its own pull requests. PRs opened by the bot are skipped,
  so it won't wake itself up to review the tests it just committed.
</Note>

## Issues — onboarding and test building

When an issue is **opened**, the agent treats it as a cue to help you build a test.

* **If the issue describes a task**, it acts on the request — writing or debugging
  the test you asked for.
* **If the issue is empty**, it introduces itself, explains that it writes and
  debugs computer-use tests, and walks you through signing in to TestDriver and
  creating your first test.
* **It finishes by opening a pull request** with the test it wrote.

## @mentions — interactive conversation

Mentioning the bot (on either an issue or a PR) starts a **solicited**, interactive
turn. Because you asked directly, the agent is chatty: it posts progress updates,
shows you screenshots of what's happening in the sandbox, and answers follow-ups in
the thread.

On a PR, an @mention overrides the silent auto-review behavior — you'll see the full
play-by-play instead of just the final review comment.

You can also manage the agent from a comment:

* **`@bot logout`** (or "sign out") revokes the installation's shared TestDriver
  sign-in and tears down the live sandbox, so the next mention will prompt whoever
  responds to sign in again.

## Signing in

Reading a diff needs nothing, but **running** the app needs a TestDriver session,
which requires the installation to be signed in. Sign-in state doesn't decide
*whether* the agent reviews — it decides *how good* the review gets. A signed-out
install still gets its bugs caught from reading the code; signing in upgrades
findings from `suspected` to `observed`.