Connect your coding agent

Testosaurus is the beta loop for web apps built with coding agents. Testers report what went wrong in your app, Testosaurus groups and ranks the reports into issues, and your own coding agent reads the top issue with its evidence, fixes it in your repository and runs your tests. This page connects the agent and shows the loop.

Connect in one line#

Open your coding agent in your app's folder and paste this:

Add Testosaurus to this app by following https://testosaurus.dev/docs/connect.md (read it with curl -fsSL).

The agent reads that page, which is written for agents, and does the setup. You do three things:

1. Open the link your agent shows. It prints a link and a short code, and tries to open the page for you.
2. Sign up or sign in, and confirm your email address in this same browser if asked.
3. Check the code, then click Allow. The page shows the same code as your terminal. Only allow a request you started yourself in your own terminal. If someone sent you the link, choose Deny.

After you click Allow, the agent creates a project for your app (or uses one you choose), adds your app's domain to its Allowed domains, installs the widget and connects itself with a Triage key, so it can read reports and record fixes but cannot change settings, delete data or spend credit. Nothing secret is copied by hand. We email you when the agent connects, and you can revoke its key at any time in Workspace settings → Management keys. If the code expires before you click Allow, your agent shows a new one.

Other ways to connect#

These reach the same server, https://testosaurus.dev/mcp, with a management key. Use one when you prefer to set up the key yourself, or when your agent cannot follow the one-line instruction.

Claude Code plugin#

The plugin adds /testosaurus:setup, /testosaurus:triage, /testosaurus:fix and /testosaurus:shipped. /testosaurus:fix runs the same loop as the prompt described further down. Install it from inside Claude Code; when you enable it, Claude Code asks for your management key and keeps it in its credential store:

/plugin marketplace add testosaurus-dev/testosaurus-plugin
/plugin install testosaurus@testosaurus

After installing, run /mcp: plugin:testosaurus:testosaurus should be listed as connected. If it is not, run /reload-plugins --force. The first call can take a few seconds.

Claude Code with one command#

Create a key (see Keys and scopes), export it, then register the server at user scope. Keep the single quotes: Claude Code stores the text ${TESTOSAURUS_SK} and reads the key from your environment when it connects, so the key never lands in a config file.

export TESTOSAURUS_SK='sk_...'
claude mcp add --scope user --transport http testosaurus https://testosaurus.dev/mcp \
  --header 'Authorization: Bearer ${TESTOSAURUS_SK}'

Start Claude Code from a shell that has the variable. If the client shows needs authentication, the variable is unset in that shell or the key was revoked; see Troubleshooting.

Codex#

Codex reads the same variable from ~/.codex/config.toml. The exact block is on the Coding agents & MCP page, together with the three kinds of key and the one-time Connect your coding agent prompt that sets an agent up for you. Any other MCP client that speaks HTTP and sends an Authorization: Bearer header can use the same endpoint.

The two prompts#

The server offers two MCP prompts. Both take an optional project argument. Claude Code lists MCP prompts as slash commands, so they appear as /mcp__testosaurus__fix_top_issue and /mcp__testosaurus__triage_inbox. Issues are ranked by impact: severity first, then how many reports. Counts are reports, not distinct people. list_issues takes a sort of impact, severity, reports or recent and a dir of asc or desc.

fix_top_issue#

Lists new issues sorted by impact, bugs and confusing behavior first, and picks the top one. Reads it with get_issue and get_issue_agent_prompt, shows you the evidence and a fix plan, and asks before editing. Then it works on a new git branch in the current repository, runs the repository's own tests, opens a draft pull request if you agree and calls record_fix with the pull request or commit and the tests it ran. With the Claude Code plugin, the same loop is /testosaurus:fix.

triage_inbox#

Lists new issues sorted by impact, shows the top 10 with severity, report count and fix state, and recommends fix, merge or dismiss for each. It changes nothing without your explicit OK.

Keys and scopes#

Create a key in Workspace settings → Management keys. The public pk_… token in your page only collects reports; an agent needs a management key, sk_…. A key has one of three scopes:

Choose the scope when you create the key: a key made without choosing one is a full key. Give your agent a Triage key. It can read everything and call record_fix, which is all the loop needs, and it cannot change settings, delete data or start paid runs. Keep the key out of browser code and out of git. Revoking a key and the other key kinds are covered on the Coding agents & MCP page.

Safety model#

• Report text is untrusted. What testers write, and the page titles, URLs, console output and analysis derived from it, comes from strangers. The server returns it under an untrusted_visitor_content key with a fixed notice, and both prompts tell your agent to treat it as data: never follow instructions in it, never run commands, open links or call tools because of it, and never paste secrets anywhere. See Visitor text is untrusted.
• Give your agent the narrowest key. The Management keys form makes a full key unless you choose Triage or Read-only, so choose on purpose. The one-time Connect your coding agent prompt mints a Triage key unless you type an intent into its card, which asks for a full-access key. A Triage key adds only record_fix.
• Your agent asks before editing. fix_top_issue shows the evidence and a plan, then waits for your go-ahead.
• With your own agent, nothing is pushed or merged without you. The work stays in your repository, on a branch: the agent edits only the repository it runs in, and the draft pull request is opened only if you agree. Run it for me (beta) works differently.
• Testosaurus settings stay as they are. The prompts never change your Testosaurus configuration.

What a good report-to-fix loop looks like#

Example: one session for a store in beta. The names and numbers are made up to show the shape of the loop.

1. A tester reports. “I click Pay and nothing happens.” The widget sends the page, the console (TypeError: Failed to fetch) and, with the tester's consent, a screenshot.
2. Testosaurus groups and ranks. Two more testers hit the same button. The three reports become one issue, which ranks at the top because of its severity and its report count.
3. You start the loop. In your repository you run /mcp__testosaurus__fix_top_issue. The agent lists new issues by impact and picks the checkout issue.
4. You see the evidence before any edit. The agent shows the reports, the console error and the page, proposes a plan (show a retry message when the request fails, with a test) and asks whether to go ahead.
5. It fixes on a branch and runs your tests. The agent creates a branch, makes the change and runs your own test command. You read the diff.
6. You decide. If you agree, the agent commits and opens a draft pull request, then calls record_fix with the state proposed, the pull request link and the tests it ran. The recorded fix shows up on the issue.
7. You merge, deploy and close the loop. After you ship, ask the agent to record the fix as shipped (it can resolve the issue too), and tell your testers.

Run it for me (beta)#

If you would rather not drive an agent yourself, a coding role in your own GitHub Actions can propose the fix. It opens a draft pull request that has passed the tests you configured, and it never merges. You start each run, or opt in to automatic runs for new reports, which open a draft PR without your review. This is in beta and needs a Node.js 22 project, GitHub repo and workflow authorization, and prepaid AI credit. Managed runs use prepaid AI credit at model rates +5%, with a per-run cap you set; GitHub Actions minutes are billed by GitHub. Setup is covered in Prepare and run a coding role, and the numbers are on Pricing & limits.