Codex Debugger

Build a case. Prove the cause.

An evidence-driven debugging system for Codex Desktop and Codex CLI.

Install · How It Works · Demo · Commands · Architecture

[!NOTE] Media slot ready. Add a GIF, screenshot, or linked video thumbnail above this note when your demo is recorded. The media guide has the filenames already wired into the template.

Debugging Without the Guesswork

Most automated debugging starts with a suspicious line and rushes toward a patch. Codex Debugger starts earlier.

It establishes the product contract, traces real callers, ranks explanations that can be proven wrong, and runs the smallest credible experiment. Production code stays untouched until the defect is reproduced and the causal boundary is clear.

signal → contract → hypothesis → probe → diagnosis → patch → verdict

The result is not “this looks fixed.” It is a casefile containing the exact before and after commands, captured output, root cause, approved change, wider checks, and remaining risk.

What You Get

| Capability | What it changes | |---|---| | Contract-first survey | Grounds expected behavior in tests, types, docs, schemas, UI copy, and callers | | Falsifiable hypotheses | Replaces broad suspicion with ranked claims that a probe can reject | | Scoped authorization | Separates permission to create a probe from permission to edit production code | | Identical command proof | Runs the same targeted command before and after the patch | | Honest verdicts | Distinguishes proven fixes, regressions, incomplete evidence, and rejected leads | | Casefile output | Keeps the full investigation readable in Codex and on GitHub |

Install

Run the package directly from npm:

npx codex-debugger

This installs the skill at:

~/.codex/skills/codex-debugger

Restart Codex after the first installation. Then open any project and start a case:

Use $codex-debugger to open a case on this project. Survey its contracts, rank falsifiable bug hypotheses, and stop at Probe authorization before writing files.

Re-run the same command whenever you want to update the installed copy. It replaces the existing codex-debugger skill automatically.

The Case System

Codex Debugger uses six named stages so the investigation remains easy to follow in a desktop-and-terminal recording.

| Stage | Question | Output | |---:|---|---| | 01 · Intake | What was actually observed? | Normalized signal and unknowns | | 02 · Survey | What does the system promise? | Contract map and reachable risk surfaces | | 03 · Probe | Which explanation survives a real test? | Approved, focused reproduction | | 04 · Diagnosis | Where does state first become incorrect? | Causal boundary and falsifier | | 05 · Patch | What is the smallest causal correction? | Approved production change | | 06 · Verdict | Did identical evidence go red to green? | Verdict, wider checks, and casefile |

Two checkpoints keep the scope clear:

read-only survey
      │
      ├── Checkpoint A → approve probe files and command
      │
      └── reproduced defect
              │
              └── Checkpoint B → approve exact production patch

Investigation Modes

Use the mode that matches the signal you have.

Use $codex-debugger in open-case mode. Find the strongest reachable correctness risks, build a contract map, and ask before creating the best probe.

Use $codex-debugger in reported mode. The first page skips the first five results. Separate observations from assumptions, reproduce it at the narrowest credible layer, and isolate the causal boundary.

Use $codex-debugger in red-only mode. Produce a credible failing probe and diagnosis, but do not edit production code.

Use $codex-debugger in intermittent mode. Control seeds, workers, clocks, ordering, and shared state. Measure a baseline failure rate before proposing any patch.

Verdict Language

Codex Debugger uses a small, strict vocabulary:

| Verdict | Meaning | |---|---| | REPRODUCED | The approved probe fails for the predicted reason | | REJECTED | A valid probe contradicts the hypothesis | | NO_DEFECT_FOUND | No candidate was proven in the inspected scope | | FIX_PROVEN | The identical probe passes and relevant wider checks pass | | FIX_UNVERIFIED | The probe passes, but wider evidence is missing | | REGRESSION_DETECTED | The probe passes while a relevant wider check fails | | STILL_BROKEN | The identical probe still fails | | INCONCLUSIVE | The available evidence cannot support a verdict |

Evidence Toolkit

The installed skill includes three dependency-free Python tools.

Observe a command

python toolkit/observe.py \
  --case CDX-2026-001 \
  --phase before \
  --output before.json \
  -- npm test -- tests/pagination.test.js

observe.py records the command array, working directory, runtime, duration, exit code, timeout state, and sanitized output.

Decide the verdict

python toolkit/decide.py \
  before.json after.json verdict.json \
  --reproduction confirmed \
  --wider-checks passed

Build the casefile

python toolkit/casefile.py \
  verdict.json context.json \
  outputs/codex-debugger/CDX-2026-001/casefile.md

Each case stays together:

outputs/codex-debugger/CDX-2026-001/
├── before.json
├── after.json
├── verdict.json
└── casefile.md

Installer Commands

# Install or update
npx codex-debugger

# Uninstall
npx codex-debugger uninstall

Installation targets ~/.codex/skills/codex-debugger by default.

Record a Strong Demo

Use Codex Desktop on the left and a terminal on the right.

1. Run npx codex-debugger in the terminal.
2. Open a project with one deterministic boundary bug.
3. Start an open-case investigation in Codex Desktop.
4. Pause on the contract map and ranked hypothesis table.
5. Approve Checkpoint A and show the probe fail in the terminal.
6. Pause on the diagnosis and causal boundary.
7. Approve Checkpoint B and rerun the identical command.
8. End on FIX_PROVEN and open the generated casefile.

Keep the recording short. The strongest story is the transition from a plausible hypothesis to captured proof.

Suggested LinkedIn Caption

I built Codex Debugger, an evidence-driven debugging system for Codex Desktop and CLI. It treats each investigation as a case: establish the contract, rank falsifiable hypotheses, approve a focused probe, isolate the causal boundary, and verify the same command red to green. The result is a complete casefile—not a guessed patch. Install it with npx codex-debugger.

Project Architecture

codex-debugger/
├── bin/
│   └── codex-debugger.js       # npm executable
├── src/
│   ├── arguments.js            # command parsing
│   ├── installation.js         # install state and filesystem actions
│   └── cli.js                  # command orchestration and output
├── codex-debugger/
│   ├── SKILL.md                # six-stage case workflow
│   ├── agents/openai.yaml      # Codex presentation metadata
│   ├── playbooks/
│   │   ├── discovery.md        # contract and hypothesis field guide
│   │   ├── probe-design.md     # reproduction design rules
│   │   └── casefile-contract.md
│   └── toolkit/
│       ├── observe.py          # command observation
│       ├── decide.py           # before/after verdict
│       └── casefile.py         # Markdown casefile renderer
└── tests/
    └── installer.test.js

Develop and Publish

npm test
npm run check
npm run pack:check

Publish after the checks pass:

npm login
npm publish --access public

The package has no runtime npm dependencies. Node.js 18 or newer is required for installation; Python 3 runs the optional evidence toolkit during an investigation.

License and Attribution

Codex Debugger is released under the MIT License. See LICENSE and NOTICE for copyright and attribution details.

A debugger should leave evidence, not confidence theater.