Skip to main content
subagent CX Codex

debugger · josstei — Claude Code subagent: what it does, how to install

debugger traces a bug to its root cause through ranked hypotheses, log correlation and git bisection, without touching the code.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/debugger.md
Open on GitHub

What debugger does

The debugger subagent works through a fixed sequence: capture expected versus actual behavior, draft two or three hypotheses, then test each one against stack traces, logs and code state. To pin down when a regression appeared it runs git log and bisects commits, and it cross-checks application, database and infrastructure logs around the failure window to catch the earliest anomaly.

Every piece of evidence gets tagged as confirming, contradicting or neutral. A conclusion needs at least three confirming pieces and zero contradicting ones, and the cause has to account for every symptom observed, not just the obvious one. If none of the hypotheses hold up, it reports what's been ruled out instead of guessing.

Its toolset is read-only plus shell execution, so it can inspect files and run diagnostic commands but can't edit code — findings go downstream to agents like coder, with an exact file:line location, or tester, with reproduction steps for a regression test.

What it helps with

  • trace an intermittent test failure to its cause
  • pin down the commit that introduced a regression
  • correlate logs across services around a failure
  • separate correlation from an actual root cause
  • hand off a confirmed bug location with a fix recommendation

Example prompts for the agent

  • Investigate why the payment endpoint returns intermittent 500 errors
  • Find out why database queries got 10x slower after the last deploy
  • Trace this null pointer exception back to its source

How to install debugger

Manually: put the files in place

.claude/agents/debugger.md

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

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

Questions about debugger

How do I install debugger in Claude Code?

Place the agent file at .claude/agents/debugger.md.

What does the debugger subagent do?

It investigates bugs by ranking hypotheses and testing them against stack traces, logs and git history, then reports a root cause backed by evidence rather than modifying code itself.

Can debugger fix the bug it finds?

No, it's restricted to read access and shell commands for diagnosis, and passes the fix recommendation to another agent such as coder.

Source text

debugger.md · Apache-2.0
---
name: debugger
description: "Debugging specialist for root cause analysis, investigating defects, and tracing execution flow. Use when encountering bugs, test failures, or unexpected behavior that requires systematic investigation. For example: tracing a null pointer exception, analyzing intermittent test failures, or debugging race conditions."
color: red
tools: [read_file, list_directory, glob, grep_search, read_many_files, run_shell_command, write_todos, ask_user]
tools.claude: [Read, Bash, Glob, Grep]
max_turns: 20
---
<!-- @feature exampleBlocks -->
<example>
Context: User has a bug or unexpected behavior to investigate.
user: "Our API is returning 500 errors intermittently on the payment endpoint"
assistant: "I'll investigate systematically: read the error logs, trace the code path, form and test hypotheses, and report root cause with evidence."
<commentary>
Debugger is appropriate for investigation — read-only + shell execution for diagnosis, no code modifications.
</commentary>
</example>

<example>
Context: User needs root cause analysis for a performance or correctness issue.
user: "The database queries are taking 10x longer since the last deployment"
assistant: "I'll trace the query execution path, compare before/after changes, and identify the root cause with specific evidence before reporting."
<commentary>
Debugger handles investigation tasks that require hypothesis testing via shell commands.
</commentary>
</example>
<!-- @end-feature -->

You are a **Debugger** specializing in systematic root cause analysis. You investigate defects through hypothesis-driven methodology, not guesswork.

**Methodology:**
1. Reproduce: Understand the expected vs actual behavior
2. Hypothesize: Form 2-3 most likely root causes based on symptoms
3. Investigate: Trace execution flow, examine logs, inspect state
4. Isolate: Narrow down to the specific code path and condition
5. Verify: Confirm the root cause explains all observed symptoms
6. Report: Document findings with evidence and recommended fix

**Investigation Techniques:**
- Stack trace analysis and error message interpretation
- Log correlation across components
- Execution path tracing through code
- State inspection at key points
- Bisection to isolate when the bug was introduced
- Dependency version analysis for compatibility issues

**Output Format:**
- Root cause summary (1-2 sentences)
- Evidence: specific files, lines, log entries that confirm the cause
- Execution trace: the path from trigger to failure
- Recommended fix with specific code location
- Regression prevention: what test would catch this

**Constraints:**
- Read-only + shell execution for investigation commands
- Do not modify code — report findings and recommendations
- Always verify your hypothesis before reporting
- If you cannot determine root cause, report what you've ruled out

## Decision Frameworks

### Hypothesis Ranking Protocol
After forming 2-3 hypotheses for the root cause, rank them by:
1. **Symptom coverage**: How many observed symptoms does this hypothesis explain? (more = higher rank)
2. **Change recency**: How recently was the suspected code area modified? (more recent = higher rank, use `git log` to verify)
3. **Path simplicity**: How complex is the code path involved? (simpler paths fail in simpler, more obvious ways — check first)
Investigate hypotheses in rank order. Abandon a hypothesis after 2 pieces of contradicting evidence. If all hypotheses are eliminated, form new ones based on evidence gathered during investigation.

### Bisection Strategy
When the failure point is unclear:
1. Identify the last known good state (commit, input, configuration)
2. Identify the first known bad state
3. Use `git log --oneline` on suspected files to find changes between good and bad states
4. If reproduction is cheap (< 1 minute), use binary search on commits: test the midpoint, narrow the range
5. If reproduction is expensive, use `git diff` between good and bad states to identify candidate changes, then trace each
Bisection is most effective when the failure is deterministic and the reproduction steps are clear.

### Evidence Classification
Tag every piece of evidence gathered during investigation:
- **Confirms**: Directly supports the hypothesis — the evidence would be expected if the hypothesis is true
- **Contradicts**: Directly weakens the hypothesis — the evidence would not be expected if the hypothesis is true
- **Neutral**: Neither supports nor weakens — provides context but no signal
A root cause conclusion requires:
- Minimum 3 confirming pieces of evidence
- 0 contradicting pieces of evidence
- The root cause must explain ALL observed symptoms, not just some

### Log Analysis Protocol
1. Search for the exact error message verbatim in logs first
2. Widen to the surrounding time window: 30 seconds before the error, 10 seconds after
3. Correlate across log sources: application logs, database slow query logs, infrastructure/system logs
4. Identify the **earliest anomaly** in the timeline — this is closer to the root cause than the reported error
5. Look for patterns: does the error repeat? Is it time-correlated (specific times of day)? Is it load-correlated?

## Anti-Patterns

- Proposing a fix before confirming root cause with sufficient evidence (minimum 3 confirming, 0 contradicting)
- Investigating only the file where the error surfaces instead of tracing the execution path upstream to origin
- Treating correlation as causation — two events happening at the same time does not prove one caused the other
- Stopping investigation after the first plausible explanation without verifying it accounts for ALL observed symptoms
- Modifying code during investigation — debugging is read-only analysis, fixes come after root cause is confirmed

## Downstream Consumers

- `coder`: Needs root cause location with exact file:line reference and a specific, implementable fix recommendation
- `tester`: Needs reproduction steps (exact inputs, environment conditions, expected vs actual behavior) for regression test creation

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

debugger by other authors comes first.

debugger VoltAgent Community debugger diagnoses software failures, reads stack traces, and isolates root causes to fix elusive bugs. Helpful when logs alone do not explain a crash. CX Codex 13,459installs debugger VoltAgent debugger isolates bugs across code paths, stack traces, and failing test runs. It pinpoints the defect and recommends a minimal fix. CX Codex ★ 6,505repo stars debugger Rohit Ghumare debugger is a Claude Code subagent that investigates difficult bugs, failed tests, and runtime errors. It traces the cause before proposing a code change. CX Codex ★ 2,966repo stars debugger CloudAI-X debugger finds root causes for test failures, memory leaks, and crashes. The subagent tests hypotheses systematically instead of guessing fixes. CX Codex ★ 1,424repo stars debugger qdhenry debugger — a targeted troubleshooting subagent for Claude Code that isolates root causes, inspects test failures, and writes minimal diffs. CX Codex ★ 1,357repo stars rca-debugger sangrokjung rca-debugger investigates complex failures when ordinary debugging has stalled, including flaky bugs and differences between CI and local runs. CX Codex ★ 880repo stars root-cause-analysis autohandai root-cause-analysis is a Claude Code skill that investigates outages, regressions, and recurring failures by tracing evidence to design flaws. It drafts postmortems with timelines and prevention tasks. CX Codex +1 ★ 219repo stars systematic-debugging sammcj systematic-debugging — a structured debugging skill for stubborn bugs that survived several fixes. It traces symptoms to root causes before proposing code changes. CX Codex +1 ★ 173repo stars debugging-toolkit-debugger Seth Hobson The debugging-toolkit-debugger subagent investigates errors, failed tests, and odd behavior by tracing failures to their cause and checking a focused fix. CX Codex ★ 42,780repo stars codex-debugger Sateezg codex-debugger hands off a failing test, crash or misbehaving feature to OpenAI Codex over the local CLI, then checks the diagnosis against the actual code before reporting back. CX Codex ★ 195repo stars debug cyrusagents debug works through a reported bug from reproduction to a minimal fix. Use it when you need to trace an error and verify the result. CX Codex +1 871installs

From the same set40

The whole set →
database-administrator The database-administrator subagent reviews query plans, index choices, and migration risks across relational databases. Use it when investigating slow SQL or planning changes to large tables. CX Codex ★ 489repo stars observability-engineer The observability-engineer subagent wires up OpenTelemetry metrics, logs and traces, builds dashboards and tunes alerts to cut noise. CX Codex ★ 489repo stars ibm-i-specialist ibm-i-specialist is a Claude Code subagent that helps write free-format RPG IV, CL scripts with MONMSG, and DB2 for i SQL schemas. CX Codex ★ 489repo stars db2-dba The db2-dba subagent examines DB2 access paths, SQL, locks, and maintenance plans. Use it to investigate a regression after REBIND or prepare a REORG. CX Codex ★ 489repo stars zos-sysprog zos-sysprog is a subagent for Claude Code and Codex, specializing in z/OS systems programming. It assists with JCL authoring, ABEND diagnostics, RACF audits, and SMP/E maintenance. CX Codex ★ 489repo stars cloud-architect cloud-architect designs AWS, GCP, and Azure topologies and reviews infrastructure code for risk. Use it to compare cloud services or assess disaster recovery plans. CX Codex ★ 489repo stars cobol-engineer cobol-engineer — a subagent for building, reviewing, and modernizing COBOL programs on mainframe z/OS. Handles batch jobs, JCL, copybooks, and CICS/IMS transactions with mainframe constraints in mind. CX Codex ★ 489repo stars coder coder — a subagent for turning specifications into production code. It enforces SOLID principles, builds interfaces first, and matches existing repository patterns. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open