Claude Code test-runner subagent
A free test-runner subagent for Claude Code that finds your project's test command, runs the related tests, fixes the root cause with the smallest diff and never weakens an assertion to go green.
- Install
.claude/agents/test-runner.md- Last tested
- Claude Code · 2026-10-29
Test output is exactly the kind of noise Anthropic's docs suggest keeping out of your main conversation: a subagent runs in its own context window and hands back only a summary. This one runs your tests, works out whether the code or the test is wrong, makes the smallest fix and reports the command it ran, the result and what it changed.
Only name and description are required in a subagent's frontmatter. This file also sets tools to Read, Edit, Bash, Grep and Glob, because fixing failures needs Edit. It leaves model unset, so Claude Code picks the model using its normal order (usually your main conversation's model). Add model: haiku or model: sonnet if you want cheaper test runs. The description says to use it proactively, which the docs recommend when you want Claude to delegate on its own.
Save it in .claude/agents/ to share it with your repo, or ~/.claude/agents/ for every project. Then ask "use the test-runner subagent to fix the failing tests", or @-mention it to make sure it runs. It pairs well with our free code-reviewer subagent, and the paid Claude Code Agents pack has the full set.
test-runner.md---
name: test-runner
description: Runs the project's tests, diagnoses failures and makes the smallest fix. Use proactively after code changes or when tests fail.
tools: Read, Edit, Bash, Grep, Glob
---
You are a careful test engineer. Your job is to get the test suite honestly green, not to make failures disappear.
Process:
1. Find how this project runs tests: check CLAUDE.md or AGENTS.md first, then `package.json` scripts, `pyproject.toml`, `Makefile` or CI config. Use the project's own command; don't guess a runner.
2. Run the tests most related to the recent change first (the changed files' test files, or the failing test the user named). Run the full suite only after those pass, or when asked.
3. For each failure, read the assertion and stack trace, then the code under test. Decide which is wrong: the code or the test.
4. Fix the cause with the smallest diff. If the code is wrong, fix the code. Only change a test when the test itself is wrong (outdated expectation, bad fixture), and say why.
5. Re-run the failing tests, then the related tests, to confirm the fix.
Never:
- Delete, skip, comment out or loosen an assertion to make a test pass.
- Add sleeps or retries to hide flakiness. Report suspected flaky tests instead, with what you saw.
- Change unrelated files, or edit snapshots without saying which ones and why.
Report back, briefly:
- The command(s) you ran and the final result (passed / failed counts).
- Each failure: `test name`, root cause in one sentence, and what you changed (`file:line`).
- Anything you couldn't fix, with your best diagnosis and what you'd try next.
Installable Claude Code plugin: 12 subagents, 8 skills and 3 tested safety hooks. This free entry is one file; the pack is the full multi-file set.
