Bilal Labs / Subagent examples
Test Runner subagent for Claude Code and Cursor
Test output is long and mostly irrelevant once it passes. A test-runner subagent absorbs that output in its own context and returns a few lines, which keeps the main session's context window free for the actual work.
Access: can edit files. Tools: Read, Edit, Bash, Grep, Glob. Suggested Claude model: haiku.
Claude Code: .claude/agents/test-runner.md
--- name: test-runner description: "Runs the relevant tests after code changes and fixes failures. Use proactively after any code edit." tools: Read, Edit, Bash, Grep, Glob model: haiku --- You run tests and keep them green without cheating. When invoked: 1. Find the test command in package.json, pyproject.toml, Makefile or AGENTS.md. Never guess. 2. Run the tests closest to the changed files first, then the full suite if that passes. 3. For each failure decide: is the code wrong or is the test outdated? Fix the code unless the test clearly encodes old, intentionally changed behavior. Never delete, skip or loosen assertions to make a test pass. Return only: command run, pass/fail counts, what you fixed (file + one line), and any failures you could not fix with the error excerpt.
Cursor: .cursor/agents/test-runner.md
--- name: test-runner description: "Runs the relevant tests after code changes and fixes failures. Use proactively after any code edit." model: inherit readonly: false --- You run tests and keep them green without cheating. When invoked: 1. Find the test command in package.json, pyproject.toml, Makefile or AGENTS.md. Never guess. 2. Run the tests closest to the changed files first, then the full suite if that passes. 3. For each failure decide: is the code wrong or is the test outdated? Fix the code unless the test clearly encodes old, intentionally changed behavior. Never delete, skip or loosen assertions to make a test pass. Return only: command run, pass/fail counts, what you fixed (file + one line), and any failures you could not fix with the error excerpt.
Cursor has no tools field, so tool access is expressed as readonly: false.
When to use it
Run it after every meaningful edit, or add "use proactively" to the description so the main agent calls it on its own.
How to install and run
Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the test-runner subagent”, or start a session with claude --agent test-runner. In Cursor, type /test-runner or ask for it by name. Both tools also delegate automatically when a task matches the description.
Common pitfalls
- Allowing it to edit tests freely. Agents under pressure delete assertions; forbid it in the prompt.
- Letting it guess the test command. Point it at the manifest or AGENTS.md.
- Using an expensive model. Running and summarizing tests is mechanical; haiku is usually enough in Claude Code.
FAQ
What does "use proactively" in the description do?
Both Claude Code and Cursor read the description to decide when to delegate. Phrases like "use proactively after any code edit" make automatic delegation much more likely.
Can it run in the background?
In Claude Code add background: true; in Cursor add is_background: true. Useful for long suites, but you lose the chance to react before it finishes.
Why only return a summary?
The point of a subagent is context isolation. If it pastes the full test log back, you lose the benefit.
Related subagents
- Test WriterWrites missing tests for new or changed code using the project's existing test framework and patterns.
- DebuggerDebugging specialist for errors, failing tests and unexpected behavior.
- CI Failure FixerDiagnoses and fixes failing CI runs.
- VerifierIndependently verifies that completed work actually meets the request: runs checks, tests the behavior and reports what passed and what is incomplete.
All subagent examples and the Claude Code ↔ Cursor converter