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

> Learn to run Codex reviews asynchronously using the --background flag in Claude Code. Track job progress with codex status and get results easily.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-15

---

**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:

```bash
/codex:review --background

```

According to the source code in [`plugins/codex/commands/review.md`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```bash
/codex:status <jobId>

```

As implemented in [`plugins/codex/commands/status.md`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```bash
/codex:result <jobId>

```

This command, defined in [`plugins/codex/commands/result.md`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```bash
/codex:cancel <jobId>

```

The implementation in [`plugins/codex/commands/cancel.md`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```typescript
// 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`](https://github.com/openai/codex-plugin-cc/blob/main/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).