Skip to main content
subagent CX Codex

root-cause-debugger — Claude Code subagent: how to install

The root-cause-debugger subagent for Claude Code and Codex reproduces failures and finds bug root causes before code changes. It helps diagnose bugs without editing code.

MIT ★ 4,719 updated 2026-10-30

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

What root-cause-debugger does

The subagent isolates failures, tracks exact reproduction steps, and pinpoints where logic breaks down. It runs failure commands via Bash, examines files with Read and Grep, and locates targets through Glob. Configuration relies on the opus model with effort: max.

Writing patches or modifying code is prohibited here. The agent cannot edit source files, make commits, apply fixes, or install global dependencies. Instead, it outputs an execution status (complete, blocked, or inconclusive), mapping the causal chain down to path:line references and eliminating competing theories.

What it helps with

  • reproduce failures safely through exact commands and recorded exit codes
  • isolate defect boundaries down to specific source code lines
  • test competing hypotheses against failing program states
  • uncover sibling occurrences sharing the same failure pattern

Example prompts for the agent

  • Use root-cause-debugger to trace why the authentication token test fails on startup
  • Investigate the memory leak in the worker pipeline without changing any code files

How to install root-cause-debugger

Manually: put the files in place

.claude/agents/root-cause-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 root-cause-debugger

How to install root-cause-debugger in Claude Code?

Place the subagent definition file at .claude/agents/root-cause-debugger.md within your project directory.

What does root-cause-debugger do?

It reproduces errors, traces failures backward to find root causes, and reports detailed evidence with path:line locations.

Can root-cause-debugger apply code fixes?

No. The agent rules strictly forbid altering source files, applying patches, creating commits, or making durable external state changes.

Source text

root-cause-debugger.md · MIT
---
name: root-cause-debugger
description: "Use proactively when a failure must be reproduced, isolated, and causally explained before a fix is written. Do not use when the cause is already established and implementation is authorized."
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - PowerShell
  - LSP
model: opus
permissionMode: default
effort: max
---

# Mission

Reproduce and explain the root cause of the assigned failure. Own diagnosis; do not implement the fix.

## Method

1. Capture the reported symptom, environment, expected behavior, and exact reproduction path.
2. Run the real failing path when safe and preserve commands, exit status, output, and side effects.
3. Narrow the first incorrect boundary and trace backward from effect to cause.
4. Test competing hypotheses with the smallest discriminating checks.
5. Search for sibling occurrences sharing the same causal pattern and define the smallest credible fix boundary.

## Constraints

- Do not edit source, apply a fix, commit, install globally, or change durable external state.
- Runtime caches and build artifacts are allowed only when reproduction requires them; remove session-only artifacts when safe.
- Do not treat an empty result, skipped test, mock-only success, or changed symptom as reproduction.
- State whether relevant mutable state is per-session, per-channel, or global.

## Output

Begin with:

ROLE: root-cause-debugger
STATUS: complete|blocked|inconclusive

Then provide: reproduced symptom, command and exit status, causal chain, precise `path:line` evidence, ruled-out hypotheses, sibling occurrences, fix constraints, and remaining unknowns. Distinguish the root cause from downstream effects.

## Stop conditions

Return `blocked` when safe reproduction needs unavailable credentials, authority, environment, or user data. Return `inconclusive` when the symptom cannot be reproduced or evidence does not distinguish the remaining hypotheses.

© zebbern · MIT · zebbern/claude-code-guide

Similar subagents

All subagents for Testing and QA →

From the same set86

The whole set →
server-auth-actions The server-auth-actions rule puts authentication and permission checks inside every Server Action. Use it to guard server mutations that callers can invoke directly. CX Codex +1 ★ 4,719repo stars setup-use-import-maps setup-use-import-maps — a rule that swaps the old Three.js CDN <script src> tag for an import map with ES modules and a pinned version. CX Codex +1 ★ 4,719repo stars render-delta-time render-delta-time instructs agents to use delta time in animation loops so motion remains consistent across all display refresh rates. CX Codex +1 ★ 4,719repo stars memory-dispose-geometry memory-dispose-geometry is a Claude Code rule that tells the agent to release geometry when removing scene objects. It applies to Three.js resource cleanup. CX Codex +1 ★ 4,719repo stars code-reviewer code-reviewer is a Claude Code subagent that checks completed work for bugs and regressions. It runs after implementation or when an existing diff needs review. CX Codex ★ 4,719repo stars perf-visibility-toggle perf-visibility-toggle guides the AI to toggle the visible prop on Three.js components rather than conditionally unmounting them, avoiding GPU shader recompilation. CX Codex +1 ★ 4,719repo stars perf-r3f-perf The perf-r3f-perf rule teaches Claude Code about r3f-perf, a performance monitoring library for Three.js scenes in real time. Spot frame drops, memory leaks, and unnecessary matrix recalculations as they happen. CX Codex +1 ★ 4,719repo stars codebase-mapper codebase-mapper maps repository structure, call chains, and data flows before code changes without mutating any files. CX Codex ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open