# Performance Considerations for the Codex Plugin: Optimization Guide for Claude Code > Optimize your Claude Code experience with this Codex plugin performance guide. Learn to manage background processes, network latency, and disk I/O for peak efficiency. - Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) - Tags: performance - Published: 2026-07-03 --- **The Codex plugin uses an asynchronous, broker-driven architecture that spawns background Node.js processes to handle tasks, requiring careful management of process lifecycle, network latency, and disk I/O to maintain optimal performance in Claude Code.** The openai/codex-plugin-cc repository implements a sophisticated background job system for integrating OpenAI Codex with Claude Code. Understanding the performance characteristics of this asynchronous architecture is essential for maintaining a responsive development environment while leveraging AI-powered code reviews. ## Background Job Architecture and Process Overhead Each `/codex:*` command creates a **tracked job** executed by a separate Node.js process called the **App Server**. According to `plugins/codex/scripts/lib/broker-endpoint.mjs`, spawning this broker process incurs a startup cost of approximately **10-30ms**. Running many concurrent jobs increases CPU and memory pressure on the host system. The broker manages these jobs through the endpoint defined in `plugins/codex/scripts/lib/broker-endpoint.mjs`, queuing commands when the single active broker per repository is already occupied. ## Network Latency and API Request Optimization The plugin communicates with the Codex service via the **`CodexAppServerClient`** class implemented in `plugins/codex/scripts/lib/app-server.mjs`. This client issues HTTP requests to the OpenAI Codex API, making **network round-trips** the dominant latency factor in overall performance. Large prompts or requests encompassing many files increase payload size and response time. When reviewing large codebases, narrow the scope using `--base ` or specific file paths to minimize the data transmitted to the API and reduce waiting time. ## Disk I/O and State Persistence Bottlenecks Job metadata, logs, and intermediate snapshots are persisted to disk by **`plugins/codex/scripts/lib/state.mjs`** and the filesystem utilities in the library. Heavy I/O operations from many concurrent jobs writing large log files can become a bottleneck on slower storage systems. Monitor disk activity when running multiple background reviews simultaneously to prevent I/O contention. ## Concurrency Limits and the Single Broker Constraint The broker enforces **only one active broker per repository**. As implemented in the broker lifecycle management, if a job is already running, new commands are queued or rejected rather than executed immediately. Attempting to run too many background tasks simultaneously causes queuing delays. Check active jobs using `/codex:status` before initiating new long-running operations to avoid blocking your workflow. ## Resource Cleanup and Process Lifecycle Management After job completion, the client closes its connection via **`await client.close()`**. The broker also shuts down the App Server when idle, as managed in `plugins/codex/scripts/lib/broker-lifecycle.mjs`. Failure to let jobs complete—such as through abrupt termination—can leave **orphaned processes** consuming CPU and memory. Always cancel unwanted jobs with `/codex:cancel ` rather than killing the terminal session. ## Optimizing Polling Intervals for Wait Loops Commands using the `--wait` flag poll the broker endpoint via **`waitForBrokerEndpoint`** at default **50ms intervals**. While this provides responsive status updates, aggressive polling increases CPU usage during high-concurrency scenarios. For environments running many concurrent jobs, you can increase the polling interval by modifying the **`options.pollIntervalMs`** parameter in `plugins/codex/scripts/lib/broker-lifecycle.mjs`, trading responsiveness for lower CPU overhead. ## Practical Performance Optimization Strategies Implement these specific tactics to maintain optimal performance when using the Codex plugin: 1. **Prefer Background Execution** – Use `--background` for long-running reviews to avoid blocking the UI and let the broker manage resources efficiently: ```bash /codex:review --background ``` 2. **Monitor and Clean Up Jobs** – Run `/codex:status` frequently to check pending jobs and cancel stray operations to free resources: ```bash /codex:status /codex:cancel ``` 3. **Limit Review Scope** – Target specific refs or paths to reduce payload size and network latency: ```bash /codex:adversarial-review --base main "challenge the caching strategy" --background ``` 4. **Reuse the Broker Process** – Once started, subsequent commands reuse the same process, saving the 10-30ms startup overhead. Avoid rapid stop/start cycles. 5. **Adjust Polling (Advanced)** – Modify `options.pollIntervalMs` in `broker-lifecycle.mjs` when running many concurrent jobs to reduce CPU usage at the cost of slower status updates. ## Summary - The Codex plugin spawns separate Node.js processes (App Servers) with a **10-30ms startup cost** managed by `plugins/codex/scripts/lib/broker-endpoint.mjs` - **Network latency** dominates performance; minimize payload size by scoping reviews with `--base` or specific paths - **Disk I/O** from `plugins/codex/scripts/lib/state.mjs` and logging can bottleneck on slower storage during high concurrency - Only **one broker runs per repository**; excess jobs queue, so monitor with `/codex:status` - Proper cleanup via `client.close()` and `/codex:cancel` prevents orphaned processes from consuming resources - Default **50ms polling intervals** balance responsiveness and CPU; adjust `pollIntervalMs` for high-concurrency scenarios ## Frequently Asked Questions ### How much overhead does spawning a new Codex broker process add? Spawning the App Server process adds approximately **10-30 milliseconds** of startup overhead according to the `plugins/codex/scripts/lib/broker-endpoint.mjs` implementation. However, once active, subsequent commands reuse the same broker process, eliminating this cost for multiple operations within the same session. ### Why does my Codex command hang when another review is running? The architecture enforces a **single active broker per repository**. If a job is already executing, new commands queue or reject rather than run concurrently. Check running jobs with `/codex:status` and cancel unnecessary ones with `/codex:cancel ` to free the broker for new operations. ### How can I reduce CPU usage when waiting for multiple Codex jobs? The default polling interval of **50ms** in `waitForBrokerEndpoint` provides responsive updates but increases CPU load. You can increase the **`options.pollIntervalMs`** parameter in `plugins/codex/scripts/lib/broker-lifecycle.mjs` to reduce polling frequency, though this trades responsiveness for lower resource consumption. ### What happens if I terminate Claude Code while a Codex job is running? Abrupt termination prevents the proper cleanup sequence defined in `plugins/codex/scripts/lib/broker-lifecycle.mjs`, potentially leaving orphaned Node.js processes running in the background. Always cancel active jobs using `/codex:cancel` before exiting, or verify no App Server processes remain using system process monitors.