# How to Report a Bug in the Codex Plugin: A Complete Guide > Learn how to report a bug in the Codex plugin. Follow our guide to generate a diagnostic report and open a GitHub issue for quick resolution on openai/codex-plugin-cc. - Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) - Tags: how-to-guide - Published: 2026-07-03 --- **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: ```bash # 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`](https://github.com/openai/codex-plugin-cc/blob/main/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: ```text 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: ```markdown ## 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`](https://github.com/openai/codex-plugin-cc/blob/main/README.md)**: Documents all available slash-commands and their flags, helping you accurately describe which command triggered the bug. - **[`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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.