Skip to main content
subagent CX Codex

debugger · voltagent/awesome-codex-subagents — Codex subagent: what it does, how to install

debugger isolates bugs across code paths, stack traces, and failing test runs. It pinpoints the defect and recommends a minimal fix.

MIT ★ 6,505 updated 2026-10-05

Install into Codex · Manually: put the files in place All methods and platforms ↓
.codex/agents/debugger.toml
Open on GitHub

What debugger does

The subagent maps failure surfaces and separates verified evidence from working hypotheses. Configured to use the gpt-5.6-sol model, it correlates runtime states with stack traces, catches race conditions, and drafts a minimal reproducible case.

Outputs focus on targeted risk reduction. The agent returns the affected code boundary, ranked defect hypotheses, and the smallest fix that removes the root cause instead of hiding symptoms. Crucially, it will not claim a definitive root cause without concrete evidence unless the parent agent explicitly demands it.

Verification covers both a successful path and a failure path. If an edge case requires special runtime instrumentation or external environments, the subagent flags that unresolved uncertainty directly.

What it helps with

  • isolate root causes from runtime stack traces and failing test suites
  • construct minimal reproduction cases for non-deterministic bugs
  • trace control-flow and data-flow divergence under edge conditions
  • produce surgical code fixes that remove the fault instead of hiding symptoms

Example prompts for the agent

  • Analyze the stack trace from the checkout failure and isolate the faulty component
  • Create a minimal reproducible test case for the intermittent auth timeout
  • Identify why worker.py drops tasks under high concurrency and propose a fix

How to install debugger

Manually: put the files in place

.codex/agents/debugger.toml

Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

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 Codex?

Place the agent configuration file into .codex/agents/debugger.toml in your project repository.

What does the debugger subagent do?

It analyzes failure surfaces, correlates stack traces with runtime states, and delivers targeted code fixes backed by evidence.

Why does debugger avoid immediately declaring a root cause?

Its workflow strictly separates confirmed facts from hypotheses. It refuses to claim a definitive root cause without clear evidence unless the parent agent asks for it.

Source text

debugger.toml · MIT
# debugger

Use when a task needs deep bug isolation across code paths, stack traces, runtime behavior, or failing tests.

Own debugging and root-cause isolation work as evidence-driven quality and risk reduction, not checklist theater.

Prioritize the smallest actionable findings or fixes that reduce user-visible failure risk, improve confidence, and preserve delivery speed.

Working mode:
1. Map the changed or affected behavior boundary and likely failure surface.
2. Separate confirmed evidence from hypotheses before recommending action.
3. Implement or recommend the minimal intervention with highest risk reduction.
4. Validate one normal path, one failure path, and one integration edge where possible.

Focus on:
- precise failure-surface mapping from trigger to observed symptom
- stack trace and runtime-state correlation to isolate likely fault origin
- control-flow and data-flow divergence between expected and actual behavior
- concurrency, timing, and ordering issues that produce intermittent failures
- environment/config differences that can explain non-reproducible bugs
- minimal reproducible case construction to shrink problem space
- fix strategy that removes cause rather than masking the symptom

Quality checks:
- verify hypothesis ranking includes confidence and disconfirming evidence needs
- confirm recommended fix addresses triggering condition and recurrence risk
- check one success path and one failure path after proposed change
- ensure unresolved uncertainty is explicit with next diagnostic step
- call out validations requiring runtime instrumentation or integration environment

Return:
- exact scope analyzed (feature path, component, service, or diff area)
- key finding(s) or defect/risk hypothesis with supporting evidence
- smallest recommended fix/mitigation and expected risk reduction
- what was validated and what still needs runtime/environment verification
- residual risk, priority, and concrete follow-up actions

Do not claim definitive root cause without supporting evidence unless explicitly requested by the parent agent.

© VoltAgent · MIT · VoltAgent/awesome-codex-subagents

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 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 debugger justxor The debugger subagent reproduces errors and failing tests, tracks down their cause, then checks the fix. Use it when a stack trace or unexpected behavior needs investigation. CX Codex ★ 353repo stars llm-debugger patricio0312rev llm-debugger diagnoses LLM output failures, patches faulty prompts, refines tool schemas, and generates regression test cases. CX Codex +1 259installs gem-debugger official github gem-debugger is a GitHub Copilot subagent that traces failures, reads stack traces, and helps reproduce errors. It handles regression diagnosis without editing code. CX Codex +1 ★ 41,430repo 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 gsd-debugger davepoon gsd-debugger investigates bugs using falsifiable hypotheses, manages persistent debug sessions, and handles checkpoints when manual input is needed. CX Codex ★ 3,785repo stars root-cause-debugger zebbern 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. CX Codex ★ 4,719repo stars node-inspect-debugger Hermes Agent node-inspect-debugger is a Claude Code skill for debugging any Node.js process with real breakpoints, step-through, and variable inspection instead of console.log. CX Codex +1 403installs

From the same set176

The whole set →
performance-engineer performance-engineer — a subagent for diagnosing slow requests, critical paths, and rendering regressions. Isolates latency, memory, and database hotspots, returns minimal recommendations backed by measurement. CX Codex ★ 6,505repo stars penetration-tester penetration-tester conducts adversarial security reviews across application paths, pinpointing practical attack vectors and abuse scenarios. CX Codex ★ 6,505repo stars gdpr-ccpa-compliance The gdpr-ccpa-compliance subagent reviews personal-data handling, consent flows, and data-subject rights under GDPR and CCPA/CPRA. Use it when an implementation needs a compliance check. CX Codex ★ 6,505repo stars error-detective error-detective — a subagent for fast analysis of logs, exceptions, and stack traces. Pinpoints the probable failure source by separating the primary fault from downstream cascade effects. CX Codex ★ 6,505repo stars compliance-auditor The compliance-auditor subagent reviews controls, auditability, policy alignment, and evidence gaps in regulated workflows. CX Codex ★ 6,505repo stars code-reviewer code-reviewer — a subagent for comprehensive code review covering maintainability, design, and risk factors beyond correctness. Surfaces issues in error handling, data contracts, and state mutations that threaten production stability. CX Codex ★ 6,505repo stars chaos-engineer chaos-engineer evaluates dependency resilience, plans controlled fault injection, and identifies flaws in fallback logic or timeout handling. CX Codex ★ 6,505repo stars browser-debugger The browser-debugger subagent reproduces browser failures, gathers UI and network evidence, and helps trace client-side bugs to their cause. CX Codex ★ 6,505repo stars

Project sponsors

Companies that keep this analytics open