How to Run Codex Reviews in the Background and Track Progress in Claude Code

You can run Codex reviews asynchronously by adding the --background flag to the /codex:review command, then monitor progress with /codex:status <jobId> and retrieve results with /codex:result <jobId>.

The openai/codex-plugin-cc repository extends Claude Code with Codex-powered code review capabilities. When you need to run Codex reviews in the background without blocking your current session, the plugin provides a built-in job tracking system that queues, monitors, and stores review results for later retrieval.

Starting Background Reviews with the --background Flag

To initiate an asynchronous review, append the --background flag to the standard review command:

/codex:review --background

According to the source code in plugins/codex/commands/review.md, this flag signals the codex-companion script to detach the process from the current turn. When detected, the system creates a background job rather than executing synchronously.

How Background Job Execution Works

The codex-companion.mjs Core Script

The heavy lifting occurs in plugins/codex/scripts/codex-companion.mjs. When --background is present, the script invokes the Claude Code Bash tool with run_in_background: true, which detaches the process immediately.

The script generates a unique job ID and returns a launch message via the renderQueuedTaskLaunch function, displaying:

<Title> started in the background as <jobId>. Check /codex:status <jobId> for progress.

Job Persistence via tracked-jobs.mjs

All background jobs flow through the tracked-jobs subsystem defined in plugins/codex/scripts/lib/tracked-jobs.mjs. This module manages:

• Unique job ID generation
• State persistence to a log file
• Status transition tracking (queued → running → finished/cancelled)

Monitoring Progress with /codex:status

To check the current state of a background review, use the status command:

/codex:status <jobId>

As implemented in plugins/codex/commands/status.md, this command reads the job ledger and reports the current state—queued, running, finished, or cancelled—along with any partial output generated so far.

Retrieving Final Results with /codex:result

Once a job reaches the finished state, retrieve the complete review output using:

/codex:result <jobId>

This command, defined in plugins/codex/commands/result.md, fetches the stored stdout for the specified job ID from the tracked jobs log.

Canceling Long-Running Reviews

If a review is taking too long or was initiated by mistake, cancel it with:

/codex:cancel <jobId>

The implementation in plugins/codex/commands/cancel.md marks the job as cancelled in the ledger and terminates the underlying process if still active.

Programmatic Usage from Custom Scripts

You can also trigger background reviews programmatically using the companion script directly:

// Launch a background review from a custom script
Bash({
  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" review --background`,
  description: "Codex review",
  run_in_background: true
});

This pattern matches the internal implementation, explicitly setting run_in_background: true to ensure the process detaches from the current Claude Code session.

Summary

• Start background reviews by adding --background to /codex:review, which triggers codex-companion.mjs to queue the job via tracked-jobs.mjs.
• Monitor execution using /codex:status <jobId> to check states including queued, running, finished, or cancelled.
• Retrieve output with /codex:result <jobId> once the job completes.
• Cancel jobs using /codex:cancel <jobId> if needed.
• All commands share the underlying infrastructure in plugins/codex/scripts/lib/tracked-jobs.mjs for reliable asynchronous execution.

Frequently Asked Questions

How do I run Codex reviews in the background without blocking my Claude Code session?

Add the --background flag to your /codex:review command. The system will immediately return a job ID and execute the review asynchronously using the tracked-jobs subsystem, allowing you to continue working while the review runs.

Where are background job statuses stored?

Job states persist through the tracked-jobs module in plugins/codex/scripts/lib/tracked-jobs.mjs, which maintains a log file containing job IDs, current states, and output buffers. This ensures status and results survive even if you close and reopen Claude Code.

Can I cancel a background review after it starts?

Yes. Use /codex:cancel <jobId> to immediately mark a job as cancelled in the ledger. According to plugins/codex/commands/cancel.md, this stops the underlying review process and updates the job status accordingly.

What states can a background Codex review have?

Background jobs progress through four states managed by tracked-jobs.mjs: queued (waiting to start), running (actively processing), finished (completed successfully), and cancelled (manually stopped or failed).

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