Debugger subagent

The debugger subagent is a short Markdown file in Claude Code's documentation. Add it to .claude/agents/ and Claude can hand failures to a specialist that captures the error, narrows down the failing spot, makes the smallest fix it can and checks that the fix works, all in its own context window. Unlike the code reviewer, it can edit files. We checked the docs on 31 October 2026.

Quick facts

The docs introduce it as "a subagent that can both analyze and fix issues", and contrast it with the reviewer: "Unlike the code reviewer, this one includes Edit because fixing bugs requires modifying code. The prompt provides a clear workflow from diagnosis to verification."

The file, in full

From Claude Code's docs:

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

How it works

The frontmatter

No model is set. Per the docs, when you leave it out Claude Code uses its model order: the CLAUDE_CODE_SUBAGENT_MODEL setting if you have one, otherwise generally the main conversation's model. If you run an expensive model in the main thread, the debugger will too, unless you set model: sonnet or similar.

Notice what is missing from the tool list: Write. The tools reference describes Edit as making targeted edits to specific files, and Write as the tool for creating files. A fix that needs a new file, such as a regression test, would have to go through Bash, or you add Write. For a debugger we think you want a regression test, so consider adding Write.

The workflow

The prompt gives five steps, and they are the part worth keeping:

1. Capture the error message and stack trace. Evidence first.
2. Identify reproduction steps. If you cannot reproduce it, you cannot verify a fix.
3. Isolate the failure location. Narrow before you change.
4. Implement the minimal fix. Small diffs are easier to review and less likely to break something else.
5. Verify. Run the thing again.

Then a process list: read logs and errors, check recent changes, form and test hypotheses, add strategic debug logging and inspect variable states. This is how experienced developers debug. It also keeps a model from guessing at a fix on the first plausible theory.

The output format

For each issue it must report the root cause, the evidence, a specific code fix, a testing approach and prevention advice. The line "Focus on fixing the underlying issue, not the symptoms" is the key instruction. Without it, models tend to wrap the failing line in a try-catch and call it done. With it, the agent is asked to explain why the bug happens, and to show evidence.

Where it differs from the reviewer

Both appear on the same docs page and both say "use proactively" or "use immediately", which means Claude may delegate without being asked. See the code reviewer subagent for the other half.

Install it

Claude Code

mkdir -p .claude/agents
$EDITOR .claude/agents/debugger.md

Paste the file above. Put it in .claude/agents/ and commit it, so your team shares it. Use ~/.claude/agents/debugger.md for a personal copy across projects. Claude Code watches both folders and picks up an edit within a few seconds. A restart is needed for the first agent file in a brand-new agents directory.

Priority matters if names clash. The docs order sources as managed settings, the --agents flag, project agents, user agents and plugin agents. A project debugger beats a user one with the same name.

For a quick session-only version, the docs show the --agents flag with JSON:

claude --agents '{
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

That one gives no tools field, so it inherits every tool available to subagents. It is the broadest version, which is worth knowing before you use it.

If the file does not load, run claude --debug and search the log. Claude Code skips a file with no name or no description, and the reason appears only in the debug log.

Codex

Codex uses TOML files in .codex/agents/ or ~/.codex/agents/, each with name, description and developer_instructions. Codex ships built-in agents named default, worker and explorer, and its docs describe worker as "execution-focused agent for implementation and fixes", which is close to this role. Our adaptation, in .codex/agents/debugger.toml:

name = "debugger"
description = "Debugging specialist for errors, test failures and unexpected behavior."
model_reasoning_effort = "high"
developer_instructions = """
You are an expert debugger focused on root cause analysis.
1. Capture the error message and stack trace.
2. Identify reproduction steps.
3. Isolate the failure location.
4. Implement the minimal fix.
5. Verify the fix by re-running the failing command.
Report: root cause, evidence, the fix, how you tested it, and how to prevent a repeat.
Fix the underlying issue, not the symptoms.
"""

Codex's docs say custom agents inherit the parent's permissions, provider and MCP servers, and that sandbox and approval settings in an agent file do not override the parent's. So how much this agent can change is decided by your Codex session, not the file.

OpenCode

OpenCode reads Markdown agents from .opencode/agents/ or ~/.config/opencode/agents/. The file name becomes the agent name. Our adaptation, in .opencode/agents/debugger.md:

---
description: Debugging specialist for errors, test failures and unexpected behavior
mode: subagent
temperature: 0.1
---
You are an expert debugger. Capture the error and stack trace, find the reproduction
steps, isolate the failing code, make the smallest fix and verify it by re-running.
Report the root cause, evidence, the fix, how you tested it and how to prevent a repeat.
Fix the cause, not the symptom.

A low temperature suits debugging, and OpenCode's docs list temperature as an option, with values from 0.0 to 1.0. OpenCode's permission block can allow or ask for edit and bash. OpenCode's permissions page says each rule resolves to allow, ask or deny. For a debugger we would set both to ask at first.

Antigravity and Cursor

Antigravity CLI describes subagents as concurrent background agent sessions, managed with /agents. We found no documented file format for defining a custom one, in Antigravity or in the Cursor pages we read, so check their docs. If your agent lacks custom subagents, paste the prompt body into the project rules file and ask for the workflow by name.

Making it better

The example is generic. Ideas that fit its structure:

1. Add Write, or at least allow new test files, so the agent can leave a regression test.
2. Name your test commands. "Run npm test -- --runInBand" beats "verify solution works".
3. Limit what it can run. Use permission rules so Bash can run tests and read logs but not deploy, push or delete.
4. Pick a model. A strong model finds subtle causes. A cheaper model may do for routine failures. Set it in model.
5. Cap turns. maxTurns stops a spiral of retries. The docs say the output returns marked as partial and Claude can resume it. That marking needs Claude Code v2.1.246 or later.
6. Isolate it. isolation: worktree runs it in a temporary git worktree, so experiments never touch your working tree.
7. Give it memory. The memory field lets it keep notes across sessions, such as a flaky test's known cause.
8. Add hooks. A PostToolUse hook after Edit can run your linter, for instance.
9. Include a stop rule. Add "If you cannot reproduce the failure after three attempts, stop and report what you tried." Models keep going without one.
10. Add stack knowledge. PHP warnings, Node async errors and Python tracebacks all have their own patterns. Put the ones you meet most in the prompt.

What it costs

The file costs nothing. The agent's requests count against the same usage limits as your main conversation, per the docs. Debugging can be token-heavy, because logs and stack traces are long and the agent loops through run, read, edit and re-run. Two habits help: give it the exact failing command, and let the subagent hold the noisy logs, so only the summary returns to your main thread. That second point is a main reason to use a subagent at all. The docs say to use one when a side task "would flood your main conversation with search results, logs, or file contents you won't reference again".

Example requests

Security notes

• It can change code and run commands. Edit plus Bash is broad. Run it in a branch, or with worktree isolation, and read the diff before you merge.
• It inherits your permissions. Per the docs, a subagent inherits the parent's permission rules. Tighten them for risky repos.
• Untrusted logs. Error messages, log lines and issue text can contain instructions. A log written by an attacker, such as a crafted user agent string, could try to steer the agent. Treat log content as data.
• Secrets in logs. Stack traces and environment dumps often hold tokens. Anything the agent reads goes to the model provider. Redact before you paste, and avoid asking it to print the environment.
• Debug logging it adds. The prompt says to add strategic debug logging. Make sure those lines do not ship, and that they never log secrets.
• Production. Do not point it at production systems with write access. Debug against a copy.
• Proactive trigger. The description says "Use proactively when encountering any issues". Claude may hand off a failure you wanted to look at yourself. Edit the description if that is not what you want.

Limits and known issues

• It cannot ask you questions mid-run, since the docs list AskUserQuestion among tools removed from subagents.
• A fix that passes the failing test can still be wrong. Review the root-cause claim and the evidence.
• It cannot see what it cannot reach: production logs, other machines, third-party services.
• Heisenbugs and race conditions need more than a prompt. Reproduction is the hard part.
• Flaky tests can lead it to fix the wrong thing. Ask for several runs.
• A misspelled frontmatter field is ignored without an error. Field names are camelCase.

Alternatives

Pair this subagent with an error source. A debugger is only as good as the evidence it can reach, and Sentry or browser tooling gives it real traces.

Our take

The strength of this example is the workflow, not the file format. Capture, reproduce, isolate, minimal fix, verify is what a careful developer does, and writing it down stops a model from skipping to a guess. The closing line about symptoms versus causes is the best sentence in it.

We would change three things before using it. Add a regression-test path, so a fix leaves proof. Narrow Bash with permission rules, since Edit plus Bash is a lot of power. And add a stop rule, so a stuck agent reports instead of looping. Then read each diff the way you would read a junior developer's pull request.

This is our reading of the documentation, not a hands-on test.

A short setup checklist

1. Create .claude/agents/debugger.md with the example.
2. Decide whether to add Write for test files.
3. Set a model and a maxTurns limit.
4. Add your real test command to the prompt.
5. Restrict Bash through permission rules.
6. Consider isolation: worktree.
7. Commit the file so your team shares it.
8. Try it on a known failing test and read the diff.

See also the Claude Code cheat sheet.

Frequently asked questions

What is the debugger subagent?

A Markdown file that defines a debugging specialist for Claude Code, with a diagnose-fix-verify workflow.

How is it different from the code-reviewer subagent?

The debugger can edit files. The reviewer cannot.

Where do I put it?

In .claude/agents/ for a project or ~/.claude/agents/ for all projects.

Does it set a model?

No. Claude Code picks one by its model order.

Can it run my tests?

Yes, through Bash. Restrict Bash if the repo is sensitive.