# Agents

> Point your coding agent at Testlane with one prompt, a block for AGENTS.md or CLAUDE.md, or Testlane's MCP server.

With Testlane, your coding agent can run a change instead of only reading it. It checks out a branch or pull request into a workspace of its own, starts its dev server, reads the logs, stops it and removes the workspace, through commands built for scripts: most print JSON, and each kind of failure exits with a code of its own.

There are three ways to connect an agent, and you can use any of them on its own:

- **The prompt:** one message that installs Testlane and adds your project.
- **Agent instructions:** a block for the instructions file your agent reads every session.
- **MCP:** Testlane's tools, served to any client that speaks the Model Context Protocol.

## The prompt

Let's start with the quickest way. Paste this prompt into any agent, like Claude Code, Codex or Cursor:

```text
Set up Testlane, a CLI that runs any branch or pull request of my project in a workspace of its own, so you can run and check changes for me.

1. Install it with `npm i -g @uxfront/testlane`, then check that `testlane version` prints a version.
2. Read https://testlane.dev/raw/docs/getting-started/agents.md and follow its agent instructions from now on.
3. Add my repository as a project: `testlane setup --name <project> --repo <clone URL> --detect`, with its origin URL and a short lowercase name. Don't pass `--yes`.
4. If setup says the repository's `.testlane.toml` is not trusted, show me the commands it printed and ask me. Only if I agree, run `testlane config trust <project> --yes`.
5. If setup drafted a config, show me each line marked `# guess:` or `# note:`, so I can check it.
```

The page it reads is this one, as Markdown, so your agent picks up the [agent instructions](#agent-instructions) below. Keep in mind that a repository can ship a `.testlane.toml` with commands Testlane runs on your machine, so Testlane asks before it trusts one. Off a terminal, `setup` prints the file and stops with an error instead, and `--yes` would answer for you. That's why the prompt tells your agent to leave `--yes` off and ask you before it runs `testlane config trust`.

## Agent instructions

Now let's look at an agent you use every day. Put Testlane's rules in the instructions file it reads at the start of each session, like `AGENTS.md` or `CLAUDE.md`, so it never has to guess which commands wait for a person. Copy this block into it:

```md
## Testlane

Testlane checks out a ref of a project into its own workspace and runs it.
Always name the verb and check the exit code first. Pass `--json` to
`checkout`, `start` and `rm`, so stdout holds only the result.

- List projects: `testlane projects --json`. Use a `name` as `<project>`.
- Check out a ref (PR number, branch or full SHA):
  `testlane <project> <ref> checkout --json`. Work in its `path`.
- Start a server: `testlane <project> <ref> start <command> --json`.
  Open its `url`. It can take minutes, since it installs dependencies first.
- See what runs: `testlane <project> ps --json`. `status` is `running` or `exited`.
- Read logs: `testlane <project> <ref> logs | tail -n 50`.
  Never pass `-f` or `--follow`.
- Stop: `testlane <project> <ref> stop`.
- Remove: `testlane <project> <ref> rm --yes --json`. stdout names each
  removed slug. Empty stdout means it kept the workspace, because it has
  uncommitted changes or the `pre_clean` hook failed (stderr says which).
  Ask the user before you add `--force`, which throws those changes away.

Never run these, since they wait for a person or never return:
- `testlane <project> <ref>` with no verb, which opens an editor by default
- `shell`, `code`, `config edit` or `config add`
- `run` for a server (use `start`), or bare `testlane <project>`

When a command exits non-zero, stop and report its `error(E_…)` and `hint:`
lines from stderr. Don't retry it unchanged. Codes: 1 internal, 2 usage,
3 config, 4 ref, 5 git, 6 setup or start.
Don't edit Testlane's config files unless the user asks.
With the `testlane` MCP server connected, call its tools instead. They
return the same JSON, and `rm` reports a kept workspace as an error.
```

## MCP

Finally, if your agent speaks the Model Context Protocol (MCP), you can connect Testlane's server instead of the shell commands. We recommend it for clients that call tools more readily than they run commands, since each tool takes typed parameters and returns the same JSON as its command's `--json`.

For Claude Code, run:

```bash
claude mcp add testlane -- testlane mcp
```

To use another config directory, put `--config-dir` before `mcp`, like `claude mcp add testlane -- testlane --config-dir ~/work/testlane mcp`.

Other clients, like Cursor or Claude Desktop, read a JSON config with an `mcpServers` entry:

```json
{
  "mcpServers": {
    "testlane": {
      "command": "testlane",
      "args": ["mcp"]
    }
  }
}
```

## Where to go next

[Use Testlane from an agent](https://testlane.dev/docs/guides/use-testlane-from-an-agent) goes deeper, with each command's JSON fields, the exit codes and what to do about each one, the commands an agent should avoid and the table of MCP tools.
