subagent

test-runner — Claude Code subagent: what it does, how to install

Q: How to install test-runner in Claude Code?

Execute `npx claude-code-templates@latest --agent development-team/test-runner` or place the agent definition directly in `.claude/agents/test-runner.md`.

Q: Why doesn't test-runner edit the code directly?

The agent has no `Write` or `Edit` tools in its environment. This guardrail prevents it from modifying source files or weakening assertions just to force tests to pass.

Runs project test suites, isolates failure causes, and suggests fixes. The agent never modifies code directly, returning a diagnostic report instead.

Install into Claude Code · claude-code-templates All methods and platforms ↓

npx claude-code-templates@latest --agent development-team/test-runner

Open on GitHub

What test-runner does

The agent detects test frameworks across your project, handling tools like Jest or Pytest. It runs checks through shell commands. Exit codes serve as ground truth. When tests break, the subagent traces stack traces against the source code. This pinpoints whether the issue comes from application logic or environment mismatches.

By design, the agent lacks Write and Edit tools. Because of this restriction, it cannot touch project files or weaken test assertions to force a green run. Flaky tests receive special treatment. The subagent reruns them in isolation two or three times to catch intermittent timing issues. You get exact line references and actionable code fixes ready to apply.

What it helps with

pinpoint the root cause of failing local or CI test runs
verify intermittent test failures through repeated isolated runs
generate concrete patch proposals without risking deleted assertions
distinguish real logic regressions from faulty mocks or environment issues

Example prompts for the agent

Run the test suite and diagnose why test_payment_retry failed
Check if the new checkout logic broke any tests and pinpoint the causes
Investigate the CI failure log and test whether that failure is flaky

How to install test-runner

1claude-code-templates

npx claude-code-templates@latest --agent development-team/test-runner

2Manually: put the files in place

.claude/agents/test-runner.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Manually: put the files in place

.codex/agents/test-runner.toml

Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

Manually: put the files in place

.cursor/agents/test-runner.md

Cursor also reads .claude/agents/

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about test-runner

How to install test-runner in Claude Code?

Execute npx claude-code-templates@latest --agent development-team/test-runner or place the agent definition directly in .claude/agents/test-runner.md.

What does the test-runner subagent do?

It identifies your test setup, executes test commands, and analyzes failures. The output provides a clear diagnosis with specific code fixes for each broken assertion.

Why doesn't test-runner edit the code directly?

The agent has no Write or Edit tools in its environment. This guardrail prevents it from modifying source files or weakening assertions just to force tests to pass.

Similar subagents

All subagents for Testing and QA →

code-reviewer official Anthropic Reviews code changes against CLAUDE.md project rules and flags material defects. Run it before a commit or pull request. 31,050installs code-reviewer official Anthropic This subagent checks code changes for bugs, security issues, and project-rule violations. Use it when a review should focus on findings that matter. 31,050installs test-engineer official Anthropic This subagent captures legacy behavior in tests and compares it with a rewritten implementation. Use it before changing existing modules. 9,715installs code-reviewer VoltAgent Community Reviews code changes for bugs, security flaws and maintenance issues. Use it before merging complex work or auditing a project. 31,050installs fullstack-developer VoltAgent Community This subagent carries a feature across the database, API, and frontend layers. Use it when one change needs a consistent end-to-end implementation. 18,117installs prompt-engineer VoltAgent Community This subagent designs, tests, and improves prompts for LLM production systems. Use it when prompts need evaluation, metrics, or cost tracking. 16,078installs

From the same set495

The whole set →

market-research-analyst A Claude subagent that gathers market and competitor data through web search and returns it as a structured research report. 851installs mcp-security-auditor Audits Model Context Protocol servers for vulnerabilities, configures OAuth 2.1 flows, and designs RBAC. Useful before deploying MCP tools to production. 851installs accessibility-auditor Audits web interfaces for accessibility issues and suggests fixes for WCAG, ARIA, keyboard access, and screen-reader use. 846installs content-curator This subagent audits Obsidian notes, spots duplicates and stale material, and suggests cleanup work. Use it when a vault needs regular content review. 846installs create-onboarding-guide Scans your project repository to generate tailored onboarding documentation for new team members. It extracts stack details and workflows directly from config files. 835installs data-feeds This skill turns URLs from 40+ websites into structured JSON through Bright Data. Use it for products, profiles, reviews, posts, or comments. 816installs supabase-backup-manager A Claude slash command that runs Supabase database backups: takes snapshots, validates restores and manages the schedule. 812installs nosql-specialist Models schemas, builds aggregation pipelines, and tunes indexing for MongoDB, Redis, Cassandra, and graph stores. Useful when structuring NoSQL data layers. 808installs