How to Report a Bug in the Codex Plugin: A Complete Guide

To report a bug in the Codex plugin, run the failing slash-command, copy the diagnostic report generated by the plugin's runtime, and open a GitHub issue in the openai/codex-plugin-cc repository with the report and reproduction steps.

The Codex plugin for Claude Code is a thin wrapper around the local Codex CLI that adds slash-commands (/codex:review, /codex:rescue, etc.) and a background job runtime. When commands fail or behave unexpectedly, the plugin relies on the standard GitHub issue workflow rather than a built-in reporting tool, requiring users to manually gather diagnostic data generated by the plugin's internal reporting functions.

Why the Codex Plugin Uses GitHub Issues for Bug Reporting

Unlike some Claude Code extensions that offer native telemetry or bug reporting commands, the Codex plugin intentionally surfaces all diagnostic information locally through diagnostic reports. These reports are formatted by the renderSetupReport and renderStatusReport functions in plugins/codex/scripts/lib/render.mjs and displayed directly in your terminal. This design ensures transparency and allows you to review exactly what data is being shared before filing an issue in the open-source repository.

Step-by-Step Guide to Reporting a Bug in the Codex Plugin

1. Gather Environment Context

Before opening an issue, collect the exact versions of your toolchain. The plugin's compatibility depends on specific versions of Node.js, npm, and the underlying Codex CLI.

Run the following commands to capture your environment:

# Check the plugin version

npm list -g @openai/codex

# Check the Codex CLI version

codex --version

# Check Node version

node --version

Include your operating system (e.g., macOS 13.5, Ubuntu 22.04) and the exact slash-command you executed, including any flags like --background or --model gpt-5.4-mini.

2. Capture the Diagnostic Report

When a command fails, the plugin prints a structured report containing sections like Status, Node, npm, Codex, Auth, Session runtime, and Review gate. This report is generated from the report object built in plugins/codex/scripts/lib/codex.mjs and rendered by the utility functions in render.mjs.

Copy the entire report from your terminal. For example, a typical setup report looks like this:

Status: not ready
- node: 18.18 (ok)
- npm: 9.8.0 (ok)
- codex: not installed
- auth: not logged in
- session runtime: none
- review gate: disabled

This output reflects the exact state the plugin observed and is essential for maintainers to reproduce your issue.

3. Document Reproducible Steps

Create a minimal reproduction case. According to the command definitions in plugins/codex/commands/rescue.md and the README, you should document:

• The repository state or file changes you were working on
• The exact flags used (e.g., /codex:rescue --background investigate why the tests started failing)
• The expected behavior versus the actual behavior

If the bug involves a specific model or background job configuration, include those parameters as they are processed by the runtime orchestration logic in codex.mjs.

4. Open a GitHub Issue

Navigate to the repository's Issues page and create a new issue:

https://github.com/openai/codex-plugin-cc/issues/new

Choose the Bug report template if available, or start a blank issue. Paste the diagnostic report and environment details you collected. Tag the issue with bug to help maintainers triage effectively.

5. Follow Up with Additional Logs

If the maintainer requests deeper debugging information, provide the Codex app-server log referenced in error messages. Specifically, at line 1084 of plugins/codex/scripts/lib/codex.mjs, the plugin surfaces hints pointing to specific log files when the Codex import fails. Supplying these logs speeds up the triage process significantly.

Example Bug Report Template

Use this markdown structure when filing your issue:

## Bug report – `/codex:rescue` crashes on macOS

**Plugin version**: @openai/codex v0.3.2  
**Node**: v18.18.0  
**OS**: macOS 13.5  

**Command run**

/codex:rescue --background investigate why the CI build fails

**Plugin output**

Status: not ready

• node: 18.18 (ok)
• npm: 9.8.0 (ok)
• codex: not installed
• auth: not logged in ...

**Steps to reproduce**

1. Clone a repo with a failing CI job.
2. Start Claude Code in that directory.
3. Run the command above.

**Expected behavior**: The plugin should launch Codex in the background and later produce a result.  
**Actual behavior**: It aborts with "Codex not installed".

Key Source Files Behind the Reporting System

Understanding how the plugin generates diagnostic data helps you gather the right information:

• plugins/codex/scripts/lib/render.mjs: Implements renderSetupReport and renderStatusReport, which format the diagnostic sections you copy into bug reports.
• plugins/codex/scripts/lib/codex.mjs: Builds the report objects consumed by the render functions and contains error handling logic (including line 1084 hints for additional logs).
• README.md: Documents all available slash-commands and their flags, helping you accurately describe which command triggered the bug.
• plugins/codex/commands/rescue.md: Defines the specific behavior and flags for the rescue command, useful when reporting background job failures.

Summary

• Gather your plugin version, Node version, OS, and Codex CLI version before filing.
• Copy the diagnostic report generated by renderSetupReport in plugins/codex/scripts/lib/render.mjs to provide exact state information.
• Document reproducible steps including exact slash-commands and flags from the README or command documentation.
• Open a GitHub issue at openai/codex-plugin-cc and tag it with bug.
• Follow up with additional logs (such as the Codex app-server log) if requested by maintainers.

Frequently Asked Questions

Where do I find the Codex plugin version?

Run npm list -g @openai/codex in your terminal. The plugin also displays its version in the diagnostic report generated by the renderStatusReport function when you run any slash-command.

What should I do if the plugin says "Codex not installed"?

This indicates the underlying Codex CLI is missing or not in your PATH. The diagnostic report from plugins/codex/scripts/lib/render.mjs will show codex: not installed. Include this in your bug report, but first try running /codex:setup as suggested in plugins/codex/commands/rescue.md to resolve the dependency issue.

Can I report bugs directly from Claude Code?

No, the plugin does not implement a built-in bug reporting command. You must manually open a GitHub issue in the openai/codex-plugin-cc repository. This ensures you review the diagnostic data before sharing it and follows the standard open-source workflow.

What logs should I attach if the maintainer asks for more details?

Attach the Codex app-server log referenced in the error message. The error handling code in plugins/codex/scripts/lib/codex.mjs (around line 1084) specifically hints at this log file path when the Codex import fails, providing the exact context maintainers need for debugging.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}