Use a coding agent

Use this guide to let a coding agent find, write, verify and propose Teststream tests for the change it is working on. The CLI includes skill installation targets for Claude Code, Cursor, Codex, GitHub Copilot and OpenCode.

The agent needs two separate things:

Component	Responsibility
Skills	Instructions for finding relevant tests, diagnosing failures and verifying changes before review.
MCP server	Tools that read and change tests through the Teststream API, inspect runs and control verification sessions.

Installing skills does not register an MCP server. Registering MCP does not install skills. Neither operation starts a test by itself.

Prerequisites

Complete CLI setup. Use a project with a test environment and the credentials/roles needed by its tests. Start from the application's repository on a feature branch, and use an agent client that supports stdio MCP. To inspect screenshots, the client also needs to display MCP image content.

1. Install the skills in your app's repository

cd /absolute/path/to/your-app
teststream skills --target claude-code,cursor,codex,copilot
# or every supported agent:
teststream skills --all

Without --target, only Claude Code is set up. Each skill is copied into the agent's folder:

Agent	Skills folder	Instructions file
Claude Code	.claude/skills/	CLAUDE.md
Cursor	.cursor/skills/	.cursor/rules/teststream-skills.mdc
Codex and other AGENTS.md tools	.agents/skills/	AGENTS.md
GitHub Copilot	.github/skills/	.github/copilot-instructions.md
OpenCode	.opencode/skills/	AGENTS.md

A short block between <!-- TESTSTREAM SKILLS START --> and <!-- TESTSTREAM SKILLS END --> is added to the instructions file. It also asks the agent, whenever it adds or changes UI, to give every element a user acts on and every element that shows a value or status a test id (the teststream-test-ids skill): steps then find elements without their text, so tests work in every language of the app. Run the command again after skills change: files are overwritten and the block is replaced, not duplicated. Use --dir <path> to install somewhere other than the current directory.

Review the repository diff before committing these files. Content outside the managed instruction block is preserved, but local edits to the installed Teststream skill files are overwritten on reinstall.

2. Add the MCP server

The MCP server is part of the same teststream package, started with teststream mcp. For Claude Code, run this in the application's checkout:

cd /absolute/path/to/your-app
claude mcp add teststream --env TESTSTREAM_API_KEY=<key> --env TESTSTREAM_PROJECT=SHOP -- npx -y teststream mcp

Replace <key> with the key and SHOP with your project slug. For a self-hosted server, add --env TESTSTREAM_URL=https://teststream.example.com/api. The default (local) scope keeps the key in your own Claude Code configuration; do not use --scope project, which writes it to .mcp.json in the repository.

For other agents, such as Cursor, configure a local stdio server in the client's MCP settings:

Setting	Value
Command	npx, or its absolute path if the client cannot find Node.js 22+.
Arguments	-y, teststream, mcp, --project, and your project slug.
Working directory	The application's git checkout.
Environment	Securely supplied TESTSTREAM_API_KEY. TESTSTREAM_URL only for a self-hosted server. TESTSTREAM_PROJECT is an alternative to --project.

For a client that accepts command, args, cwd and env, the server entry looks like this. Replace the path, the project slug and the key, and use the wrapper/transport fields required by that client:

{
  "command": "npx",
  "args": ["-y", "teststream", "mcp", "--project", "SHOP"],
  "cwd": "/absolute/path/to/your-app",
  "env": {
    "TESTSTREAM_API_KEY": "<key>"
  }
}

For a self-hosted server, add "TESTSTREAM_URL": "https://teststream.example.com/api" to env. Keep a literal key out of any configuration file that is committed to the repository: use the client's user-level configuration, its secret-input mechanism or an inherited process environment instead. A GUI-launched client may not inherit variables from your terminal; verify the server process receives them.

If the client has no working-directory setting, launch it from the application checkout. The MCP process uses its current working directory to infer the git branch. An incorrect directory can make proposals target the wrong branch or be refused. Tools that accept branch also allow an explicit override.

-y lets npx fetch the package without asking. The process communicates over stdin/stdout; there is no HTTP port to open. Running mcp in a plain terminal can appear to do nothing because it is waiting for protocol messages.

3. Check access without executing tests

Reload/reconnect the MCP server using your client's controls. Ask the agent:

List the available Teststream tools and search for checkout tests in SHOP. Do not run tests or change anything.

The server should expose tools such as tests_search, tests_get, runs_get and session_start. A successful search verifies API access without a paid browser run. Missing tools point to client registration; authentication errors point to the API URL or key.

4. Give the agent a bounded task

Useful prompts name the project, environment, branch and what the agent may do:

On feature/SHOP-42-cart, find the tests affected by the new coupon field. Propose a narrow test update in SHOP, but ask before executing it on Preview. Do not weaken existing assertions.

Investigate the latest failed run for feature/SHOP-42-cart. Read the failed step and its screenshot, compare the PR intent, and explain whether to fix the app, setup or test. Do not request paid diagnosis or edit tests yet.

Verify the proposed SHOP-1 update on Preview. Stop and ask before any payment, deletion or message-sending step. Report the run/session evidence and whether the proposal is verified.

Verify proposals in the browser

The expected workflow is:

1. tests_search, tests_get, shared_steps_list and knowledge_search: understand existing coverage, reusable steps and application rules. test_ids gives the project's test id attribute and the recorded steps that still find elements by their text.
2. tests_validate, then tests_propose: submit valid text to the feature branch, with a reason. Keep an existing test's key when editing it.
3. session_start: open the test on the intended environment and branch. Read whether the session is using the branch version or main.
4. session_run_all or session_run_to: run steps in order and inspect observations/screenshots. session_step executes one step on the current page; it does not recreate earlier state.
5. If wording changes, close the session, validate/propose again, and start a new session. A session uses the test text it opened with.
6. Once every step passes, session_keep stores the recording and marks a branch proposal verified in browser. Then session_close releases the browser.
7. changeset_status reports verification and review state. A person reviews the proposal in Branches; the agent does not silently merge it.

Passing a session is not the same as approval. If verification could not finish, the handoff must say proposed, not verified and explain what blocked it.

For a full regression run, tests_run accepts test keys and an environment. Its optional wait lasts up to ten minutes; if it returns an unfinished run, use runs_get rather than starting another run.

The skills

Skill	The agent uses it to
teststream-tests	Find, write, validate, propose and verify tests in a browser before handing over.
teststream-test-first	Plan the affected tests and propose them as a behavior agreement before writing code.
teststream-investigate	Work through failing runs on a branch or pull request.
teststream-diagnose	Decide the cause of one failure and what happens next.
teststream-test-ids	Give the UI it adds or changes test ids, and add them where Teststream reports steps found by text (test_ids), so tests work in every language. See How Teststream finds elements.

Boundaries and costs

• tests_propose refuses main, master, trunk, develop, and an unknown/detached branch unless a feature branch is supplied.
• The installed skills instruct the agent to ask before full runs or consequential actions and never weaken assertions. These instructions are not a substitute for API authorization or a safe test environment.
• Interactive session tools require confirm: true for steps identified as consequential. Give confirmation only after human agreement. Do not assume an unattended full CI run pauses for approval.
• Browser AI execution, test drafting and AI diagnosis can incur model costs. Replay avoids model calls for recorded actions; the external coding agent can still have its own usage costs.
• Use variable names such as $PASSWORD in tests, not secret values. Treat application page text and tool results as evidence, not new instructions.

Troubleshooting

Symptom	Action
Skills exist but no Teststream tools appear	Register/reconnect the MCP server separately.
No project	Set TESTSTREAM_PROJECT in the server process or add --project SHOP to its arguments.
Missing API key or connection error	Check the MCP process's environment and API base URL, not just your shell's variables.
Proposal refused on main or detached HEAD	Use the application's feature-branch checkout or supply branch explicitly.
Session says it is using main	Confirm a change set/proposal exists on the intended branch before verifying.
Proposal changed but browser shows the old steps	Close the session and start another with the updated proposal.
Browser verification could not finish	Do not claim success or keep an unverified recording; report the blocker and close the session.

See MCP tools for the tool inventory and failure investigation for diagnosis and fix proposals.