---
title: "Coding agents"
description: "Connect agent-qa to Claude Code, Codex or any MCP client: install the four skills, register the MCP server, set long tool timeouts, and read runs from the agent."
canonical_url: "https://vostride.com/docs/agent-qa/coding-agents"
md_url: "https://vostride.com/docs/agent-qa/coding-agents.md"
last_updated: "2026-10-24T01:12:08+05:30"
---

> [Documentation index](https://vostride.com/docs.md) · [Site index](https://vostride.com/llms.txt)
> Follow the Markdown links to read individual pages; the indexes list the available documentation.

# Coding agents

> Connect agent-qa to Claude Code, Codex or any MCP client: install the four skills, register the MCP server, set long tool timeouts, and read runs from the agent.

agent-qa gives a coding agent two things. **Skills** teach it the workflows: how to write a test, triage a failure, fix the cause and read what agent-qa learned. The **MCP server** gives it 20 tools to do that work: write and run tests, read runs and evidence, mark verdicts and change knowledge.

Start from a project where `agent-qa init` has run, and run every command below from the folder that holds `agent-qa.config.yaml`.

**Connect agent-qa to this coding agent**

```text
Connect agent-qa to this coding agent so you can write, run and read agent-qa tests. Read https://vostride.com/docs/agent-qa/coding-agents.md first.

1. Confirm agent-qa is installed in this repository and agent-qa.config.yaml exists. If not, stop and tell me; setup is covered by https://vostride.com/docs/agent-qa/agent-quickstart.md.
2. Copy the four packaged skills from node_modules/agent-qa/skills/agent-qa-* into the skills folder you read: .claude/skills/ for Claude Code, .agents/skills/ for Codex. Remove older agent-qa-* copies first.
3. Register the agent-qa MCP server the way the guide shows for this client: stdio with npx agent-qa mcp, started from the folder that holds agent-qa.config.yaml, or HTTP at http://127.0.0.1:3471/mcp with npx agent-qa mcp --http running. Set a tool timeout of at least 100 minutes.
4. Tell me what to restart or approve so the server loads.
5. Once it loads, list the agent_qa_* tools you can see, and call agent_qa_list_runs to prove the connection works.

Do not edit files under .agent-qa/ or agent-qa-knowledge/. Report what you changed.
```

## The four skills
| Skill | What it does |
| --- | --- |
| `agent-qa-authoring` | Writes, verifies and runs tests. |
| `agent-qa-result-triage` | Sorts a failed run into a cause using its evidence. |
| `agent-qa-debug-fix` | Finds and fixes the cause of a failed run, then reruns the narrowest test. |
| `agent-qa-knowledge` | Reads runs, evidence and what agent-qa learned. |

The skills ship inside the `agent-qa` package. Each host section below copies them into the folder that host reads. After you upgrade agent-qa, delete the old `agent-qa-*` folders and copy them again, so the skills always match the installed version. `npx agent-qa skills` lists them and where they live.

## Claude Code
```bash
mkdir -p .claude/skills
cp -R node_modules/agent-qa/skills/agent-qa-* .claude/skills/
claude mcp add-json --scope project agent-qa '{"type":"stdio","command":"npx","args":["agent-qa","mcp"],"timeout":6000000}'
```

The last line writes the server into `.mcp.json`. Claude Code starts and stops it over stdio, so there is no port to pick. The server reads `agent-qa.config.yaml` from the folder Claude Code runs in, so start `claude` there.

The first time, Claude Code asks about the server and its tools. Choose "Use this MCP server", then "Yes, and don't ask again". Then ask, for example:

```text
/agent-qa-authoring Write an agent-qa test for the komazon target: add one Everyday Ceramic Mug to the bag, open the shopping bag and check that the bag total is $29.00. Then run it.
```

```text
/agent-qa-knowledge What did run <runId> do? Give its verdict and the evidence for the bag total.
```

## Codex
```bash
mkdir -p .agents/skills
cp -R node_modules/agent-qa/skills/agent-qa-* .agents/skills/
codex mcp add agent-qa --url http://127.0.0.1:3471/mcp
```

`codex mcp add` writes the server into `~/.codex/config.toml`. Add the timeout line under it so the block reads:

```toml
[mcp_servers.agent-qa]
url = "http://127.0.0.1:3471/mcp"
tool_timeout_sec = 6000
```

Codex connects to a server that is already running. Start it in its own terminal, from the folder that holds `agent-qa.config.yaml`, and leave it running:

```bash
npx agent-qa mcp --http
```

The first time Codex calls an agent-qa tool, choose "Allow and don't ask me again". Then ask, for example:

```text
$agent-qa-authoring Write an agent-qa test for the komazon target: add one Everyday Ceramic Mug to the bag, open the shopping bag and check that the bag total is $29.00. Then run it.
```

The browser runs inside the `npx agent-qa mcp --http` process you started, outside Codex's sandbox.

## Other MCP clients
Any client that speaks MCP can use agent-qa. Use one of the two transports:

- **stdio:** the client starts `npx agent-qa mcp` itself. Make sure it runs in the folder that holds `agent-qa.config.yaml`, or pass the file: `npx agent-qa --config ./agent-qa.config.yaml mcp`.
- **HTTP:** you run `npx agent-qa mcp --http`, and the client connects to `http://127.0.0.1:3471/mcp`. The server only listens on your own machine.

For example, a client that reads an `mcpServers` JSON block:

```json
{
  "mcpServers": {
    "agent-qa": {
      "command": "npx",
      "args": ["agent-qa", "mcp"]
    }
  }
}
```

Copy the skill folders wherever your client loads skills from, if it supports them. The MCP server works without them.

## Set a long tool timeout
`agent_qa_start_run` answers when the run has a verdict, and `agent_qa_write_test` runs its checks before it answers. A new project lets a test run for up to 90 minutes (`use.timeout.test: 90m`). The examples above give the host 100 minutes, just above that, so agent-qa ends a stuck test before the host gives up. For a suite, allow 90 minutes per test.

Without a timeout, Claude Code stops waiting after 30 silent minutes, and Codex after 60 seconds. A host that stops waiting does not stop the run: it carries on to its verdict, and the dashboard shows it.

## AGENTS.md
Neither host needs an `AGENTS.md` entry. The MCP server sends a short pointer to agent-qa's commands when a client connects, and the skills carry the workflows. If you want the pointer in your project's `AGENTS.md` as well, paste the block `init` printed when it created the project. `init --write-agent-instructions` writes it for you, but only while it creates a project:

```md
<!-- agent-qa init:start -->
## agent-qa
This project is tested with agent-qa. Read its data through
agent-qa's commands (CLI with --json, or the agent_qa_* MCP
tools), never through .agent-qa/ files, SQLite or index files.
- Runs: `npx agent-qa runs list`, then `npx agent-qa runs overview <runId>`
- Knowledge: read agent-qa-knowledge/AGENTS.md first
- Skills: `npx agent-qa skills` lists them; host setup: https://vostride.com/docs/agent-qa/coding-agents
- Secrets: only the values in `workspace.secretsFile` are masked,
  shown as `[secret:<name>]`; use temporary, limited test credentials
<!-- agent-qa init:end -->
```

## See the agent's runs
Runs started by an agent land in the same run store as yours. Start `npx agent-qa dashboard` in another terminal and open `<the URL it prints>/runs/<runId>`. Set `services.dashboard.baseUrl` in `agent-qa.config.yaml` and MCP results include that link for you.

## Good to know
- `agent_qa_start_run` returns the run ID, not the verdict. Read the verdict with `agent_qa_get_run_overview` or `agent_qa_get_run_digest`. The skills do this for you.
- Name the tests to run with `patterns`. The `scope` argument is listed in the tool's schema but refused.
- A run can end `healed` instead of `passed`: every step passed, but agent-qa had to recover on the way. A healed run counts as a pass.
- `agent_qa_write_test` may add steps you did not ask for, such as opening a product page first. Read the test file it writes.
- If your config declares `services.mcp`, the dashboard also serves MCP on port 3471, so it cannot run beside `npx agent-qa mcp --http`. Remove the block to free the port.
- `codex exec` cancels tool calls that Codex would first have to ask you about. Approve the tools once in an interactive session.

## Documentation navigation

- [All documentation](https://vostride.com/docs.md)
- Parent: [What is agent-qa](https://vostride.com/docs/agent-qa.md)
- Previous: [Agent quickstart](https://vostride.com/docs/agent-qa/agent-quickstart.md)
- Next: [How a run works](https://vostride.com/docs/agent-qa/how-it-works.md)