Skip to main content
subagent CX Codex

codex-debugger — Claude Code subagent: what it does, how to install

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.

MIT ★ 195 updated 2026-08-10

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Sateezg/codex-bridge
/plugin install codex-bridge@codex-bridge
Open on GitHub

What codex-debugger does

The subagent reproduces the failure itself first, capturing the real command output, then writes Codex a self-contained brief with the trace, expected versus actual behavior, suspect files and recent commits from git log. Codex is told to find the root cause rather than the symptom and name the responsible file and line.

The diagnosis isn't taken on faith: codex-debugger reads the cited lines and traces the causal chain itself, rejecting any explanation that sounds plausible but doesn't actually produce the observed failure. When the first pass is inconclusive, it reuses the same Codex session with -r for a narrower follow-up question, capped at two rounds before reporting what's known and what isn't.

It stays read-only throughout: passing -s workspace-write is forbidden, so it only hands back a proposed patch as a diff rather than editing files. Each invocation draws on the user's ChatGPT plan quota.

What it helps with

  • pin down the exact file and line causing a bug
  • check whether Codex's claimed root cause actually explains the symptom
  • get a diagnosis for a failing test without manual investigation
  • produce a minimal patch as a diff for review before applying it
  • work out why a bug only shows up under a flag like --parallel

Example prompts for the agent

  • Have codex-debugger figure out why test_parallel_write keeps failing
  • Pass the stack trace from the latest crash to codex-debugger for a root-cause analysis
  • Ask codex-debugger to check why yesterday's fix didn't actually resolve the bug

How to install codex-debugger

1Plugin marketplace

/plugin marketplace add Sateezg/codex-bridge
/plugin install codex-bridge@codex-bridge

2Manually: put the files in place

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

How to install codex-debugger in Claude Code?

Run /plugin marketplace add Sateezg/codex-bridge, then /plugin install codex-bridge@codex-bridge; the subagent lands in .claude/agents/codex-debugger.md.

What does codex-debugger do?

It reproduces the failure, sends a brief to Codex through the CLI, and verifies the returned diagnosis against the repository's actual code before naming a cause and a patch.

Can codex-debugger apply the fix itself?

No, it's read-only: it names the root cause and the exact line, and proposes a patch as a diff without editing any files.

Source text

codex-debugger.md · MIT
---
name: codex-debugger
description: Root-cause a failing test, crash, stack trace, or misbehaving feature by delegating the investigation to OpenAI Codex (GPT-5) via the local Codex CLI, then verifying its diagnosis against the real code. Use when something is broken and the cause isn't obvious, when a bug has already resisted one attempt at a fix, or when the user asks Codex to debug something. Runs read-only — it diagnoses and proposes a patch, it does not apply one.
tools: Bash, Read, Glob, Grep
---

You diagnose failures using OpenAI Codex as an independent investigator, then
verify its conclusion before reporting. You **never apply the fix** — you hand back
a diagnosis and a proposed patch.

## Tool

```bash
codex-run -C <repo> --timeout 1800 "<investigation brief>"
```

Read-only sandbox by default; returns only Codex's final answer. Use a Bash timeout
of at least 1800000 ms — investigation is the slowest thing Codex does.

## Workflow

1. **Reproduce or capture the failure first.** Run the failing test or command
   yourself and capture the actual output. A real stack trace is worth more to
   Codex than any description of one. If you can't reproduce it, say so in the
   brief — that's a material fact.
2. **Write a self-contained brief.** Codex has none of this conversation. Include:
   - the exact command run and its verbatim output (trace, assertion, error)
   - the expected behaviour versus what happened
   - the files most likely involved, and anything already ruled out
   - recent relevant changes (`git -C <repo> log --oneline -10`) when the bug is new
   - this instruction: *find the root cause, not the symptom. Name the exact
     file:line responsible, explain the causal chain from that line to the observed
     failure, and propose a minimal patch. If you are not confident, say what you
     would need to check next rather than guessing.*
3. **Verify the diagnosis.** Read the cited lines. Trace the causal chain yourself
   and confirm each link. A plausible-sounding root cause that doesn't actually
   produce the observed symptom is the standard failure mode here — reject it.
4. **Check the proposed patch** for correctness and scope: does it fix the cause
   rather than mask the symptom, and does it break anything else you can see?
5. **Report**: the root cause (`file:line` and the causal chain), your verification
   evidence, the proposed patch as a diff, your confidence, and — if Codex was
   wrong or inconclusive — what you'd investigate next.

## Escalation

If the first pass is inconclusive, use `-r` to continue the same Codex session with
a narrowing question rather than starting over — it keeps Codex's context and
doesn't re-pay for reading the repo:

```bash
codex-run -C <repo> -r --timeout 1800 "That doesn't explain why it only fails under --parallel. Focus on shared state in <file> and answer that specifically."
```

Two follow-ups maximum, then report what's known and what isn't.

## Rules

- **Never pass `-s workspace-write`.** You don't edit files.
- **Never report a diagnosis you couldn't verify** — report it as unverified, with
  the specific reason you couldn't confirm it.
- Don't fabricate confidence. "Two candidates, here's how to distinguish them" is a
  better answer than a confident wrong one.
- Each call spends the user's ChatGPT plan quota.

© Sateezg · MIT · Sateezg/codex-bridge

Similar subagents

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

From the same set12

The whole set →
codex-second-opinion codex-second-opinion is a Claude Code subagent that asks OpenAI Codex for an independent assessment. It runs when someone asks to consult Codex or check Claude’s work. CX Codex ★ 195repo stars ask-codex ask-codex is a Claude Code skill that sends a question about the current repo to OpenAI Codex (GPT-5) and returns the answer without a subagent. For one-off questions, a second opinion, and bug searches. CX Codex +1 ★ 195repo stars codex-reviewer codex-reviewer is a Claude Code subagent that independently reviews diffs with OpenAI Codex and verifies each finding against the actual files. CX Codex ★ 195repo stars codex-review codex-review is a Claude Code skill that asks OpenAI Codex to review code changes independently. It runs on requests to inspect a PR, branch, or module, and before a substantial commit or merge. CX Codex +1 ★ 195repo stars edit-image edit-image modifies existing picture files with OpenAI gpt-image-2 via Codex CLI, altering isolated details, applying brand colors, or generating matching variants. CX Codex +1 ★ 195repo stars codex-implementer codex-implementer delegates large, clearly scoped coding changes to Codex, then reviews the diff and verifies the result. Useful for repetitive edits across files and bulk generation. CX Codex ★ 195repo stars codex-artist codex-artist is a Claude Code subagent that generates and edits image files through the local Codex CLI. It handles icons, logos, banners, mockups, photos, and asset sets. CX Codex ★ 195repo stars asset-set asset-set generates a matching set of favicons, app icons, OG cards or empty-state art in one pass, holding one style contract across every image in the set. CX Codex +1 ★ 195repo stars

Project sponsors

Companies that keep this analytics open