Feature Request: Add a first-class Debug Mode for evidence-driven bug fixing

Summary

I would like to suggest adding a first-class Debug Mode to Codex, similar in spirit to Cursor’s Debug Mode, but designed natively for Codex.

Codex is already very capable at writing code, reviewing code, planning tasks, setting goals, running tests, and using tools/plugins. However, real-world debugging often requires more than a good plan or a persistent goal. Many bugs need a structured loop of reproduction, runtime evidence collection, root cause analysis, minimal patching, verification, and cleanup.

The proposed Debug Mode would give Codex a dedicated workflow for investigating and fixing bugs based on runtime evidence instead of relying too heavily on static code inspection or speculative changes.

Problem

In real projects, many bugs are difficult to fix reliably from code reading alone.

Examples:

• A UI button appears unresponsive, but the real cause may be a state race, a cancelled async task, a lifecycle ordering issue, or an event handler not being registered.
• A mobile app bug may only happen on a real device, after cold launch, with a specific permission state, screen size, USB connection state, or account state.
• A web app issue may depend on browser console errors, network requests, DOM state, local storage, auth state, timing, or cached data.
• A backend or database issue may require inspecting actual request payloads, response values, permission errors, schema mismatches, or production-like data.
• A flaky test may pass locally but fail under a specific timing or environment condition.
• A fix may appear correct in code review but still fail when the user reproduces the bug manually.
• Sometimes an attempted fix introduces a regression in behavior that was already fixed before.

The main issue is not that Codex cannot debug today. It can. The issue is that debugging is currently not a dedicated, optimized product workflow. Users often have to manually prompt Codex to add logs, run tests, collect output, paste logs back, explain reproduction steps again, ask for a smaller patch, and remind it to remove temporary debug code.

A dedicated Debug Mode could make this much more reliable and much more convenient.

Why Goal and Plan are not enough

Codex’s Goal and Plan features are useful, but they do not fully replace a dedicated Debug Mode.

Plan helps Codex think before making changes. This is valuable for implementation, refactoring, migration, and larger tasks. However, debugging is not only a planning problem. A very reasonable plan can still be based on the wrong assumption if Codex has not observed the bug happening at runtime.

Goal helps Codex continue working toward a persistent objective across multiple turns. This is also useful, especially for long-running tasks and iterative work. However, debugging is not just a long-running objective. If the process lacks runtime evidence, a longer autonomous loop may simply produce more speculative changes.

A Debug Mode should solve a different problem:

• Plan answers: “What steps should Codex take?”
• Goal answers: “What objective should Codex keep pursuing?”
• Debug Mode answers: “What evidence proves the root cause, what is the smallest safe fix, and how do we verify the bug is actually gone?”

These features should complement each other, but Goal and Plan should not be expected to fully replace a debugging workflow.

Why plugins, MCP, and hooks are not enough

Plugins, MCP, hooks, and external tools can help Codex access logs, run commands, connect to services, or automate project-specific workflows. They are very valuable, but they are still mostly tool infrastructure.

They do not automatically provide a complete debugging experience.

For example, a plugin or MCP server may expose logs, but it does not necessarily know:

• when a user is starting a bug reproduction session;
• what temporary instrumentation should be added;
• what logs are relevant and what logs are noise;
• which hypotheses have been confirmed or ruled out;
• whether the fix should be minimal or whether a refactor is justified;
• whether temporary debug code should be removed after verification;
• whether the same bug needs a regression test;
• how to present the final root cause and evidence in a trustworthy way.

Hooks can run commands at certain lifecycle points, but they are not the same as a guided reproduce-observe-fix-verify loop.

MCP can provide useful external context, but it is still not a user-facing Debug Mode. Most users should not need to manually assemble their own debugging framework out of plugins, hooks, custom scripts, and repeated prompts.

A first-class Debug Mode could internally reuse plugins, MCP, hooks, terminal output, test results, browser logs, screenshots, app snapshots, or IDE integrations where available. But the user-facing experience should be a coherent debugging workflow, not a collection of disconnected tools.

Proposed Debug Mode workflow

I suggest adding a /debug command or a visible Debug Mode button in Codex.

Example:

/debug The iOS app sometimes fails to connect to the camera after USB connection. It works in some cases but fails after cold launch. Please debug using runtime evidence and avoid speculative rewrites.

After entering Debug Mode, Codex should not immediately make broad code changes. Instead, it should start a structured debugging loop.

1. Understand the bug

Codex should summarize:

• expected behavior;
• actual behavior;
• reproduction steps;
• affected environment;
• suspected files or modules;
• initial hypotheses;
• what evidence is needed;
• what “fixed” means.

2. Add temporary instrumentation

Codex should be able to add temporary debug instrumentation, such as:

• structured logs;
• lifecycle logs;
• state transition logs;
• async task start/cancel/finish logs;
• network request and response logs with sensitive data redaction;
• permission state dumps;
• timing measurements;
• UI event tracing;
• test-specific assertions;
• error boundary or crash diagnostics.

Temporary debug code should be clearly marked so it can be removed later.

3. Reproduce the bug

Codex should guide or automate the reproduction process.

Depending on the project and available tools, this could include:

• asking the user to perform a specific reproduction flow;
• running a test suite;
• running a simulator or local app;
• using browser automation;
• collecting terminal output;
• collecting browser console logs;
• collecting screenshots or app snapshots;
• reading relevant logs from a local file or tool integration.

The key point is that each reproduction attempt should produce a structured evidence bundle, instead of forcing the user to paste scattered logs manually.

4. Analyze root cause from evidence

Codex should then analyze the evidence and explain:

• which hypothesis is supported;
• which hypotheses were ruled out;
• the actual root cause;
• the affected code path;
• why the bug happens;
• why the proposed fix is minimal and safe;
• what regression test should be added or updated.

This would make debugging much more trustworthy than a fix based mainly on guesswork.

5. Apply a minimal fix

Debug Mode should strongly prefer minimal patches.

Default behavior should be:

• no unrelated refactors;
• no formatting-only churn;
• no large architecture rewrite unless explicitly requested;
• preserve existing public behavior;
• keep temporary instrumentation separate from final code;
• add or update regression tests when possible.

This is important because many debugging attempts fail not because the model cannot write code, but because the fix is too broad and accidentally changes unrelated behavior.

6. Verify the fix

After applying the fix, Codex should verify it.

Verification could include:

• rerunning the relevant tests;
• rerunning the reproduction flow;
• checking logs again;
• asking the user to confirm the real-world bug is gone;
• comparing before/after evidence.

If the bug is still present, Codex should not start over with random changes. It should continue the debugging loop with more targeted instrumentation and updated hypotheses.

7. Clean up debug code

Once the fix is verified, Codex should automatically remove temporary instrumentation unless the user explicitly wants to keep some permanent logging.

The final state should include:

• the minimal fix;
• necessary regression tests;
• no leftover temporary debug logs;
• no unrelated code churn.

Expected benefits

A first-class Debug Mode would bring several major benefits.

1. Fewer speculative fixes

Codex would rely more on runtime evidence and less on assumptions.

2. Fewer regressions

A reproduce-fix-verify loop, combined with regression tests, would reduce the cycle where one bug is fixed but another previously fixed bug comes back.

3. Smaller and safer patches

Debug Mode could default to minimal changes, which is very important in production projects and large codebases.

4. Better support for UI, mobile, async, and device-specific bugs

Many bugs in front-end, mobile, desktop, browser, and async systems cannot be reliably diagnosed by static code reading alone.

5. Less manual work for users

Users should not need to repeatedly copy logs, paste console output, explain reproduction steps, and remind Codex to clean up debug code.

6. More trustworthy final answers

A final debug summary could clearly state:

• what evidence was collected;
• what the root cause was;
• what files changed;
• why the fix is safe;
• how the fix was verified;
• what risk remains.

This would make users much more confident that the bug was actually fixed.

Suggested MVP acceptance criteria

A useful MVP version of Debug Mode could include:

• a /debug command or visible Debug Mode entry point;
• a required bug summary and reproduction section;
• hypothesis generation before code modification;
• automatic insertion of temporary instrumentation;
• a structured reproduction/evidence collection step;
• root cause analysis based on collected evidence;
• minimal patch generation;
• verification after the fix;
• cleanup of temporary debug instrumentation;
• regression test creation or update where possible;
• a final summary listing evidence, root cause, changed files, verification result, and remaining risks.

Non-goals

This request is not asking Codex to perfectly reproduce every bug automatically. Some bugs will still require user interaction, real devices, production-like data, external hardware, or manual confirmation.

This request is also not asking Codex to copy another product feature-for-feature.

The goal is to give Codex a native, reliable debugging workflow:

bug report
→ hypotheses
→ temporary instrumentation
→ reproduction
→ evidence collection
→ root cause analysis
→ minimal fix
→ verification
→ cleanup
→ regression prevention

Closing

Codex is already powerful for coding tasks, but debugging is one of the highest-risk and highest-trust parts of AI-assisted software development. A first-class Debug Mode would make Codex much more reliable for real projects, especially large projects, mobile apps, complex front-end apps, async systems, device-specific bugs, flaky tests, and long-term maintenance work.

I believe this would be a very important improvement because it would help Codex move from “can attempt to fix bugs” toward “can systematically investigate, prove, fix, and verify bugs.”