Coding agents

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 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 skillsCopy Anchor Link

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 CodeCopy Anchor Link

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:

/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.

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

CodexCopy Anchor Link

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:

[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:

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:

$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 clientsCopy Anchor Link

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:

{
  "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 timeoutCopy Anchor Link

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.mdCopy Anchor Link

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:

<!-- 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 runsCopy Anchor Link

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 knowCopy Anchor Link

• 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.