English · 简体中文

Codex Debug Agent

Evidence, not guesswork.

A runtime-evidence debugging plugin for Codex with a native macOS
human reproduction gate, local media evidence, and 24-hour task suspension.

Quick Start · How It Works · Architecture · Privacy · Report a Bug

---

Codex can read code and run tests, but some bugs only appear after a real person signs in, drags a file, grants a permission, or follows a precise UI path. Codex Debug Agent closes that gap.

It turns debugging into a falsifiable evidence loop: form competing hypotheses, add the smallest useful probes, pause for a real reproduction when needed, classify the evidence, apply one supported fix, and verify the exact path again.

Why this exists

Most AI debugging fails in a predictable way: it sees a symptom, guesses a cause, and starts editing. This plugin changes the default.

Typical agent debugging	Codex Debug Agent
Jumps from symptom to patch	Starts with falsifiable hypotheses
Treats passing builds as proof	Requires evidence from the failing path
Asks the user to reply “done”	Opens a native, structured Human Gate
Loses context while waiting	Keeps the MCP tool call pending for up to 24 hours
Mixes screenshots into chat manually	Accepts local image/video evidence with ⌘V
Leaves temporary logs behind	Verifies post-fix, then removes probes and session artifacts

Highlights

• Evidence-first debugging — hypothesis IDs, targeted runtime probes, and explicit CONFIRMED, REJECTED, or INCONCLUSIVE outcomes.
• Native Human Gate — a focused SwiftUI dialog for reproduction steps, expected evidence, notes, and the next debugging decision.
• English and Simplified Chinese — the Agent selects en or zh-CN from the conversation language and keeps native controls and reproduction content consistent.
• Real task suspension — Codex directly awaits the MCP result instead of polling a detached helper or pretending to pause.
• Local visual evidence — paste screenshots or screen recordings with ⌘V; attachments remain on the Mac.
• Quiet by design — the companion uses a launchd-activated Unix socket and stays exited while idle.
• Before/after proof — the same reproduction path is compared across pre-fix and post-fix runs.
• Ready to inspect — the Swift app, Python MCP server, Skill, build scripts, and Universal 2 app bundle all live in this repository.

Quick Start

Requirements

• macOS 14 or newer
• Codex with local plugin support
• uv or Python 3.11+

The bundled Universal 2 app supports Apple Silicon and Intel Macs. Xcode is not required for normal installation.

Install

Clone the repository into the personal plugin directory and run the installer:

git clone https://github.com/pj-workspace/codex-debug-plugin.git ~/plugins/codex-debug-plugin
cd ~/plugins/codex-debug-plugin
./scripts/install-plugin.zsh

The installer backs up an existing personal marketplace file, registers the plugin, installs the native companion, and enables the plugin in Codex.

Open a new Codex task so the Skill and MCP tools are loaded, then ask:

Debug this reproducible issue using runtime evidence. Pause and show the native reproduction dialog when you need me.

The Agent passes language: en for English conversations and language: zh-CN for Simplified Chinese conversations. auto follows the preferred macOS language when no preference is known.

Verify

uv run --with 'mcp>=1.25,<2' ./scripts/smoke-test-mcp.py

A healthy installation reports both request_debug_decision and ping_debug_dialog.

How It Works

1. Define the failure — capture the shortest real reproduction and the expected behavior.
2. Form competing hypotheses — normally 3–5 explanations from different subsystems.
3. Instrument selectively — add only the probes that distinguish those hypotheses.
4. Reproduce for real — Codex runs the path itself or opens the native Human Gate for user-only actions.
5. Classify evidence — confirm, reject, or keep each hypothesis inconclusive using concrete runtime observations.
6. Fix narrowly — change only the behavior supported by the evidence.
7. Verify and clean up — repeat the same path, compare runs, then remove temporary instrumentation.

Architecture

flowchart LR
    C[Codex] --> S[Evidence Debugging Skill]
    S --> P[Runtime probes]
    P --> A[Application under test]
    S --> M[stdio MCP server]
    M --> U[User-owned Unix socket]
    U --> L[launchd socket activation]
    L --> D[Native Swift dialog]
    H[Human reproduction] --> D
    D -->|decision, notes, local attachments| M
    M -->|structured MCP result| C

Loading

The MCP server never opens a fake detached prompt. The current Codex task calls request_debug_decision directly and remains pending until the user responds, cancels, or the 24-hour timeout is reached.

Repository Layout

codex-debug-plugin/
├── .codex-plugin/          # Codex plugin manifest
├── companion/              # Signed Universal 2 app bundle
├── mcp/                    # Python stdio MCP server
├── native/                 # SwiftUI app source and launchd definition
├── scripts/                # Register, build, install, health-check, and smoke tests
├── skills/
│   └── evidence-debugging/ # Debugging workflow and runtime protocols
└── assets/                 # Icon and high-resolution bilingual screenshots

Native App

The repository ships a signed ad-hoc Universal 2 build at:

companion/Codex Debug Dialog.app

To rebuild it from source with Swift 5.10+:

./scripts/build-macos-companion.zsh

The installer prefers the bundled app and falls back to a local source build only when the bundle is absent.

Privacy and Safety

• Communication stays on the local machine through a user-owned Unix-domain socket.
• Screenshots and videos remain at their local paths; the plugin does not upload or forward them.
• The Skill forbids logging tokens, passwords, cookies, request bodies, or other secrets.
• Runtime probes must be scoped to the current investigation and removed after verification.
• The helper runs as a user LaunchAgent, never as a privileged system daemon.
• Socket, LaunchAgent, and Codex configuration files use restrictive user-only permissions.

Current Scope

Codex Debug Agent currently provides the evidence workflow, native reproduction gate, attachment handoff, and local lifecycle management on macOS. Automatic browser Console/Network capture, IDE breakpoint adapters, session recovery after a client restart, and non-macOS companions are not implemented yet.

Roadmap

• Browser Console and Network evidence capture
• IDE breakpoint and debug-adapter integration
• Durable session recovery across Codex restarts
• Richer image/video evidence inspection
• Signed and notarized macOS releases
• Windows and Linux human-gate companions

Contributing

Issues and focused pull requests are welcome. Read CONTRIBUTING.md before proposing a large change. Please keep contributions aligned with the core rule: a fix is not proven until the original failing path has produced before-and-after evidence.

When changing the native app or MCP bridge, run:

./scripts/build-macos-companion.zsh
uv run --with 'mcp>=1.25,<2' ./scripts/smoke-test-mcp.py
python3 -m py_compile mcp/src/debug_dialog_mcp/*.py scripts/*.py
zsh -n scripts/*.zsh

Community

• Bug reports and feature requests
• Questions and design discussions
• Contributing guide
• Security policy
• Code of Conduct

License

MIT © 2026 Jay Pan