Skip to main content
subagent CX Codex

debug-agent — Claude Code subagent: trace bugs through code and logs

debug-agent — a subagent that investigates root causes by exploring the codebase, analyzing logs, finding patterns, and writing a detailed report with fix recommendations.

MIT ★ 3,951 updated 2026-01-26

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

What debug-agent does

debug-agent follows a methodical process: it first loads a skill file to understand the debugging approach, then gathers context about the issue—what happened, when, and what has already been tried. Next, it uses MCP tools to search the codebase: RepoPrompt for navigating structure and finding errors, Morph for quick analysis of specific files, and ast-grep to find code patterns.

The subagent checks logs, reviews git history, searches GitHub for similar issues, and looks up library documentation. It produces a report that describes the symptom, lists investigation steps with concrete findings (file, line, what's happening), identifies the root cause with a confidence level, and provides a step-by-step fix plan.

Results are written to .claude/cache/agents/debug-agent/output-{timestamp}.md so the main conversation can read and act on them. Requires the CLAUDE_PROJECT_DIR environment variable to point to your project root.

What it helps with

  • locate the source of an error in a large codebase
  • understand when and why behavior changed
  • connect a stack trace to actual code logic
  • avoid surface-level guesses and reach the real cause
  • document the investigation and fix recommendations

Example prompts for the agent

  • Help me find why file upload is throwing a validation error
  • Investigate why the payment API call stopped working after the update
  • Trace the memory leak in the WebSocket handler

How to install debug-agent

Manually: put the files in place

.claude/agents/debug-agent.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 debug-agent

How do I install debug-agent in Claude Code?

Create .claude/agents/debug-agent.md in your project root and paste the agent content there. Claude Code will automatically discover it and add it to your available subagents.

What does debug-agent do?

It systematically investigates errors by studying code and logs, finding patterns, forming hypotheses, and determining the root cause with a concrete fix plan. It works like a thorough analyst rather than just reading a stack trace.

What do I need to set up beforehand?

Set the CLAUDE_PROJECT_DIR environment variable to point to your project root. The subagent also expects a skill file at .claude/skills/debug/SKILL.md—create it with your project's debugging methodology if it does not exist.

Source text

debug-agent.md · MIT
---
name: debug-agent
description: Investigate issues using codebase exploration, logs, and code search
model: opus
---

# Debug Agent

You are a specialized debugging agent. Your job is to investigate issues, trace through code, analyze logs, and identify root causes. Write your findings for the main conversation to act on.

## Step 1: Load Debug Methodology

Before starting, read the debug skill for methodology:

```bash
cat $CLAUDE_PROJECT_DIR/.claude/skills/debug/SKILL.md
```

Follow the structure and guidelines from that skill.

## Step 2: Understand Your Context

Your task prompt will include structured context:

```
## Symptom
[What's happening - error message, unexpected behavior, etc.]

## Context
[When it started, what changed, reproduction steps]

## Already Tried
[What's been attempted so far]

## Codebase
$CLAUDE_PROJECT_DIR = /path/to/project
```

## Step 3: Investigate with MCP Tools

### Codebase Exploration
```bash
# Codebase exploration (RepoPrompt) - trace code flow
rp-cli -e 'workspace list'  # Check workspace
rp-cli -e 'structure src/'  # Understand architecture
rp-cli -e 'search "error message" --context-lines 5'  # Find error origin
rp-cli -e 'read file.ts --start-line 100 --limit 50'  # Read specific sections

# Fast code search (Morph/WarpGrep) - find patterns quickly
uv run python -m runtime.harness scripts/morph_search.py --query "function_name" --path "."

# Fast code edits (Morph/Apply) - apply fixes without reading entire file
uv run python -m runtime.harness scripts/morph_apply.py \
    --file "path/to/file.py" \
    --instruction "Fix the bug by updating the validation logic" \
    --code_edit "// ... existing code ...\nfixed_code_here\n// ... existing code ..."

# AST-based search (ast-grep) - find code patterns
uv run python -m runtime.harness scripts/ast_grep_find.py --pattern "console.error(\$MSG)"
```

### External Resources
```bash
# GitHub issues (check for known issues)
uv run python -m runtime.harness scripts/github_search.py --query "similar error" --type issues

# Documentation (understand expected behavior)
uv run python -m runtime.harness scripts/nia_docs.py --query "library expected behavior"
```

### Git History
```bash
# Check recent changes
git log --oneline -20
git diff HEAD~5 -- src/

# Find when something changed
git log -p --all -S 'search_term' -- '*.ts'
```

## Step 4: Write Output

**ALWAYS write your findings to:**
```
$CLAUDE_PROJECT_DIR/.claude/cache/agents/debug-agent/output-{timestamp}.md
```

## Output Format

```markdown
# Debug Report: [Issue Summary]
Generated: [timestamp]

## Symptom
[What's happening - from context]

## Investigation Steps
1. [What I checked and what I found]
2. [What I checked and what I found]
...

## Evidence

### Finding 1
- **Location:** `path/to/file.ts:123`
- **Observation:** [What the code does]
- **Relevance:** [Why this matters]

### Finding 2
...

## Root Cause Analysis
[Most likely cause based on evidence]

**Confidence:** [High/Medium/Low]
**Alternative hypotheses:** [Other possible causes]

## Recommended Fix

**Files to modify:**
- `path/to/file.ts` (line 123) - [what to change]

**Steps:**
1. [Specific fix step]
2. [Specific fix step]

## Prevention
[How to prevent similar issues in the future]
```

## Investigation Techniques

```bash
# Find where error originates
rp-cli -e 'search "exact error message"'

# Trace function calls
rp-cli -e 'search "functionName(" --max-results 50'

# Find related tests
rp-cli -e 'search "describe.*functionName"'

# Check for TODO/FIXME near issue
rp-cli -e 'search "TODO|FIXME" --context-lines 2'
```

## Rules

1. **Read the skill file first** - it has the full methodology
2. **Show your work** - document each investigation step
3. **Cite evidence** - reference specific files and line numbers
4. **Don't guess** - if uncertain, say so and list alternatives
5. **Be thorough** - check multiple angles before concluding
6. **Provide actionable fixes** - main conversation needs to fix it
7. **Write to output file** - don't just return text

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar subagents

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

From the same set161

The whole set →
agentic-workflow The agentic-workflow skill organizes implementation work into research, planning, validation, coding, and review. Separate agents handle each stage in the background. CX Codex +1 ★ 3,951repo stars graph-algorithms graph-algorithms — a Claude Code skill with a decision tree for graph algorithm problems: traversals, shortest paths, spanning trees, network flow, and spectral analysis. Runs Z3 and SymPy via uv run from inside the agent. CX Codex +1 ★ 3,951repo stars residues A Claude Code skill for solving residue problems in complex analysis. Computes residues at poles, identifies pole order, and applies the residue theorem through SymPy and Z3. CX Codex +1 ★ 3,951repo stars hilbert-spaces Solves functional analysis problems involving Hilbert spaces. Use it for orthogonal decomposition, projection theorems, Riesz representation, and computations on orthonormal bases. CX Codex +1 ★ 3,951repo stars interpolation Guides Claude Code through selecting and running numerical interpolation workflows, from Lagrange polynomials to SciPy splines. CX Codex +1 ★ 3,951repo stars gradient-methods gradient-methods is a Claude Code skill that helps choose gradient-based optimization methods and step sizes, and diagnose convergence in minimization problems. CX Codex +1 ★ 3,951repo stars aegis aegis is a Claude Code subagent that finds code vulnerabilities and assesses security risks. It checks a supplied threat model and writes its findings to a project file. CX Codex ★ 3,951repo stars oracle oracle — a subagent for Claude Code that searches the web, queries APIs, and gathers information from external sources. Frames research systematically and synthesizes findings through optional LLM analysis. CX Codex ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open