Use Testlane from an Agent
An AI coding agent can review a pull request the way you do: check it out, start it, open the URL, read the logs, then stop it and clean up. It needs to know which commands to call and which fields to read, though. Without that, an agent guesses. Think of an agent that calls shell and waits forever for someone to type, one that runs a dev server with run and never gets its prompt back, or one that parses the progress lines on stderr instead of the JSON on stdout.
By the end of this guide, your agent can drive the whole loop on its own, and you'll know what it reads at each step.
Before you start
You'll need Testlane installed, at least one project configured and your agent connected, which Agents covers. The examples use a project called my-project with a dev command, and show real output. Your paths, ports and PIDs will differ. Testlane prints each JSON result on one line, and we've wrapped them here so they're easier to read.
Every step below also relies on three rules:
- Pass
--json, and read data from stdout only. Progress (→ …), warnings and errors always go to stderr. The output of the project's[setup]and hooks goes to stdout as well, unless you pass--json, which moves it to stderr. So pass--jsontocheckout,startandrm, the commands here that can run them, and stdout holds only the result. Script with Testlane explains the rest of this contract. - Always name the verb.
testlane my-project 42with no verb runs the project'sdefault_command, which iscodeunless the project ordefaults.tomlsets another, so it opens an editor. - Check the exit code before you read stdout. When a command in this guide fails, it exits non-zero and prints nothing on stdout. Handle a failure says what to do next.
Drive a workspace
List the projects
testlane projects --json
[
{
"name": "my-project",
"repo": "git@github.com:my-org/my-project.git",
"workspaces": 0,
"pathExists": false
}
]
name is what every other command takes as <project>. workspaces counts the workspaces Testlane has checked out for it, and pathExists is false until the first checkout clones the repository. An empty array means no project is configured, so ask the user to add one rather than writing a config file yourself.
Check out a ref and get its path
A ref is a PR number (42), a branch name (feat/login) or a full 40-character commit SHA. Refs lists every form.
testlane my-project feat/login checkout --json
{
"project": "my-project",
"slug": "feat-login",
"ref": "feat/login",
"kind": "branch",
"branch": "feat/login",
"path": "/home/you/dev/testlane/my-project/trees/feat-login",
"ports": [4153],
"created": true
}
path is the absolute path of the workspace, so run your own commands there. created is false when the workspace already existed, and the command is safe to repeat. For a PR, kind is "pr" and branch is "pr/42".
Note that checkout skips the project's [setup], like installing dependencies, unless you add --setup. start runs it for you.
Start a command and get its URL
testlane my-project feat/login start dev --json
{
"project": "my-project",
"slug": "feat-login",
"command": "dev",
"pid": 82622,
"port": 4153,
"url": "http://127.0.0.1:4153",
"log": "/home/you/dev/testlane/my-project/trees/.data/feat-login/process.log",
"startedAt": "2026-11-14T09:37:24.871Z",
"reused": false
}
start checks out the ref if it isn't already, runs [setup], starts the command in the background and returns once url accepts connections. The process keeps running after start exits. dev must be a name under [commands] in the project's config.
Keep in mind that start can take minutes, since [setup] usually installs dependencies first. After setup, it waits up to 300 seconds for the port, and --timeout <seconds> changes that wait. Give your own tool call enough time.
start is safe to repeat. When the same command is already running, it prints the same object with "reused": true.
Check what's running
testlane my-project ps --json
[
{
"slug": "feat-login",
"command": "dev",
"pid": 82622,
"port": 4153,
"status": "running",
"startedAt": "2026-11-14T09:37:24.871Z",
"log": "/home/you/dev/testlane/my-project/trees/.data/feat-login/process.log"
}
]
ps takes the project only, with no ref, and lists every process start left in it. status is running, or exited when the process died on its own, like after a crash. With nothing started, it prints [].
Read the logs
logs has no --json. It prints the process's log on stdout, as it is:
testlane my-project feat/login logs
listening on 4153
The log keeps growing while the process runs, so we recommend reading only its end, like testlane my-project feat/login logs | tail -n 50. Never pass -f or --follow: they keep printing until someone interrupts them, so your call never returns. With no log yet, logs exits 2.
Stop the process
stop has no --json. Read its exit code, which is 0 whether or not anything was running:
testlane my-project feat/login stop
stderr says what happened, like → dev stopped (pid 82622) or → not running: my-project/feat-login. The log stays, so you can still read it after stop.
Remove the workspace
rm asks for confirmation, so pass --yes. It prints no JSON, but pass --json anyway: it moves the output of the project's pre_clean hook to stderr, so stdout holds only the slugs rm removed.
testlane my-project feat/login rm --yes --json
feat-login
stdout names each slug it removed. rm stops a running process first, so you don't need stop before it. When stdin isn't a terminal, rm without --yes exits 2 instead of asking.
rm keeps the workspace when it has uncommitted changes, or when the project's pre_clean hook fails. Either way, it exits 0, prints nothing on stdout and warns on stderr with one of these lines:
warning: skipping feat-login: worktree is dirty (use --force)
warning: pre_clean hook failed for feat-login — skipping
So check that stdout names the slug. When the hook failed, report it to the user. When the workspace has uncommitted changes, --force removes it anyway and throws those changes away, and for a branch workspace it also deletes the local branch, so ask the user before you add it.
Handle a failure
Testlane exits 0 on success. Any other code means the command failed, and stderr ends with one error(E_…) line and sometimes a hint: line:
error(E_SETUP): 'dev' exited before 127.0.0.1:4164 accepted connections
hint: full log: /home/you/dev/testlane/my-project/trees/.data/pr-42/process.log
Report both lines to the user, and don't retry the same command unchanged, since it usually fails the same way. This is what each code usually asks of an agent:
| Code | Name | What to do |
|---|---|---|
1 | E_INTERNAL | Stop and report it, since it's a bug in Testlane |
2 | E_USAGE | Fix the command, like a missing --yes or a command name that isn't configured |
3 | E_CONFIG | Report it, and leave fixing the config to the user |
4 | E_RESOLVE | Check the ref, then ask the user which one they meant |
5 | E_GIT | Report it, since a git or gh command failed |
6 | E_SETUP | Read the lines above the error and logs, then report what failed |
Exit codes is the full reference.
A few cases come up often. start exits 2 when another command already runs in that workspace, and its hint names the stop to run first. It exits 6 when the command exits before its port is ready, when the port isn't ready within --timeout or when something else already holds the port. In each case it leaves no process behind.
Keep an agent away from these commands
These commands open something for a person and wait for them, so an agent's call never returns:
shellstarts an interactive shell in the workspace. Run your commands in thepathfromcheckoutinstead, or useexec, liketestlane my-project 42 exec -- npm test.codeopens the workspace in an editor. With a terminal editor likevim, it waits until someone closes it. Openpathwith your own tools.config editandconfig addopen a project's config file in an editor.addis another name foredit. Leave config changes to the user.
Two more need care. run waits until its command exits, which is right for run test and wrong for a dev server, so use start for anything that keeps running. And bare testlane <project> opens a picker that waits for a choice when it runs in a terminal, so use testlane <project> list --json to list workspaces.
Connect over MCP
If your agent speaks the Model Context Protocol (MCP), you can skip the shell
commands above. testlane mcp serves the same steps as typed tools, and each
tool returns the same JSON as its command's --json. Your MCP client starts the
server itself, so you only add it to the client's config once.
Agents shows how to add the server to Claude Code and to clients with a JSON config.
The server has twelve tools. projects, doctor and config_validate take no
parameters. The others take project, and the workspace tools also take ref,
plus an optional kind of pr, branch or path in place of
--pr, --branch and --path:
| Tool | Command | Returns |
|---|---|---|
projects | testlane projects --json | its JSON |
doctor | testlane doctor --json | its JSON |
config_validate | testlane config validate --json | its JSON |
list | testlane <project> list --json | its JSON |
ps | testlane <project> ps --json | its JSON |
info | testlane <project> <ref> info --json | its JSON |
checkout | testlane <project> <ref> checkout --json | its JSON |
start | testlane <project> <ref> start <command> --json | its JSON |
stop | testlane <project> <ref> stop | {exitCode, stdout, stderr} |
logs | testlane <project> <ref> logs, its last lines lines | {exitCode, stdout, stderr} |
diff | testlane <project> <ref> diff | {exitCode, stdout, stderr} |
rm | testlane <project> <ref> rm --yes | {exitCode, stdout, stderr, removed} |
A tool that fails returns isError: true. When the command threw an error, the
text is {"error": {"errCode", "exitCode", "message", "hint"}, "stderr"}, so read
it the way Handle a failure reads stderr. A few behaviours
differ from the shell:
checkoutandstarttake atimeout, in seconds (600 by default) for the whole call. When it runs out, the server stops the setup, hooks or server the call started and answers{"timedOut": true, ...}. While they run, they send progress for each step and at least every 5 seconds, when your client asks for progress.logsreturns the last 100 lines, or as many aslinesasks for, up to 1000. It never follows the log.diffreturns at most 1 MiB, with"truncated": truewhen there was more.rmreports a kept workspace as an error. When the workspace has uncommitted changes, or itspre_cleanhook failed,rmkeeps it and returns"removed": falsewithisError: true. The tool has noforce, so only the user can throw those changes away.
shell, code, exec, run, sync, clean and config edit aren't tools,
since they wait for a person, run any command or remove many workspaces at once.
The server never records trust in a repository's config for the user either.
ADR-003
gives the reason for each tool that's left out.
Where to go next
Here's where to go from here:
- Agent instructions has these rules as a short block to paste into
AGENTS.mdorCLAUDE.md. - Script with Testlane covers the JSON of
listandinfo, and patterns for shell scripts and CI. - Workspace verbs lists every flag of
checkout,start,stop,logsandrm. - Run dev servers in parallel
explains the ports
startserves on.
Troubleshooting
Find out what went wrong when a Testlane command fails, from the error it printed or the symptom you see, and how to fix it.
Ship a Config with Your Repo
Commit a .testlane.toml so everyone who adds your project gets working setup, env and commands, and see how users approve, override and keep up with it.