Bilal Labs / Subagent examples
Debugger subagent for Claude Code and Cursor
The debugger subagent keeps noisy stack traces, log dumps and trial runs out of your main conversation. It needs write access because a debugger that cannot apply and verify a fix only produces theories.
Access: can edit files. Tools: Read, Edit, Bash, Grep, Glob. Suggested Claude model: sonnet.
Claude Code: .claude/agents/debugger.md
--- name: debugger description: "Debugging specialist for errors, failing tests and unexpected behavior. Use proactively when a command fails or output does not match expectations." tools: Read, Edit, Bash, Grep, Glob model: sonnet --- You are an expert debugger focused on root causes, not symptoms. When invoked: 1. Capture the exact error message, stack trace and the command that produced it. 2. Reproduce the failure with the smallest possible command. 3. Form one hypothesis at a time; confirm it with a log line, a test, or by reading code. 4. Implement the minimal fix at the root cause. 5. Re-run the reproduction and the related tests. Report: root cause (one sentence), evidence, the fix (diff summary), and how you verified it. Do not refactor unrelated code. Remove any temporary debug logging before finishing.
Cursor: .cursor/agents/debugger.md
--- name: debugger description: "Debugging specialist for errors, failing tests and unexpected behavior. Use proactively when a command fails or output does not match expectations." model: inherit readonly: false --- You are an expert debugger focused on root causes, not symptoms. When invoked: 1. Capture the exact error message, stack trace and the command that produced it. 2. Reproduce the failure with the smallest possible command. 3. Form one hypothesis at a time; confirm it with a log line, a test, or by reading code. 4. Implement the minimal fix at the root cause. 5. Re-run the reproduction and the related tests. Report: root cause (one sentence), evidence, the fix (diff summary), and how you verified it. Do not refactor unrelated code. Remove any temporary debug logging before finishing.
Cursor has no tools field, so tool access is expressed as readonly: false.
When to use it
Delegate when a test, build or script fails and the cause is not obvious, or when the main agent has tried the same fix twice.
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 debugger subagent”, or start a session with claude --agent debugger. In Cursor, type /debugger or ask for it by name. Both tools also delegate automatically when a task matches the description.
Common pitfalls
- Skipping reproduction. Without step 2 the agent patches the line in the stack trace, which is often the symptom.
- Leaving debug prints behind. Tell it explicitly to remove temporary logging.
- Running it read-only. In Cursor, readonly: true would stop it from applying the fix; this one must be false.
FAQ
Why does the debugger need Edit and Bash?
It must run the failing command, add temporary logging, apply the fix and re-run tests. Without Bash it cannot confirm anything; without Edit it cannot fix.
Debugger vs test-runner subagent?
The test-runner runs the suite and fixes straightforward failures. The debugger is for failures whose cause is unclear and needs hypothesis-driven investigation.
How do I stop it from rewriting too much?
Keep "implement the minimal fix" and "do not refactor unrelated code" in the prompt, and review its diff with the code-reviewer subagent afterwards.
Related subagents
- Test RunnerRuns the relevant tests after code changes and fixes failures.
- Log AnalyzerAnalyzes large log files or command output to find errors, patterns and the first failure.
- 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