# How to Execute Long-Running Codex Tasks in the Background with openai/codex-plugin-cc

> Execute long-running Codex tasks in the background using the --background flag. Monitor progress with codex status and retrieve results efficiently.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: best-practices
- Published: 2026-07-05

---

**Use the `--background` flag in `codex-companion.mjs` to detach long-running Codex jobs into isolated Node processes, then monitor progress with `/codex:status` and retrieve results via `/codex:result`.**

The openai/codex-plugin-cc repository provides a robust background execution system that prevents the Claude Code UI from freezing during lengthy reviews, adversarial analyses, or rescue tasks. By leveraging process isolation and atomic state persistence, you can execute long-running Codex tasks in the background while maintaining full visibility into job progress and final outputs.

## Why Background Execution Matters for Codex Workloads

Codex reviews and rescue tasks can take minutes when processing large codebases or using high-effort reasoning models. Running these operations in the foreground blocks your terminal and prevents concurrent work. The plugin solves this by implementing a **detached worker architecture** that spawns independent Node processes, stores progress in JSON files under `.codex/jobs/`, and provides CLI commands to query or cancel jobs asynchronously.

## How the Background Execution System Works

### Command Parsing and Job Creation

When you append `--background` to any command, the `parseCommandInput` function in `codex-companion.mjs` (lines 41-48) sets `options.background = true`. This triggers `handleTask` to call `enqueueBackgroundTask` (lines 84-100) rather than executing synchronously.

The system creates a structured job object via `buildTaskJob` (lines 62-71), which assigns a unique `jobId`, defines the log file path, and writes an initial *queued* record to disk using `createTrackedProgress`.

### The Detached Worker Architecture

The `enqueueBackgroundTask` function spawns a detached child process through `spawnDetachedTaskWorker` (lines 71-80). This worker runs independently of the parent Claude Code process, ensuring that crashes or memory-intensive operations do not affect your active session.

The detached child executes `handleTaskWorker`, which reads the stored request and runs `runTrackedJob` from `tracked-jobs.mjs`. This function updates the job file in-place, transitioning the status from `"queued"` to `"running"` and finally to `"completed"` or `"failed"`.

### Progress Tracking and State Persistence

Progress events flow through `createJobProgressUpdater` in `tracked-jobs.mjs` (lines 70-95), which writes JSON-structured log lines to the job-specific `*.log` file. The system uses atomic updates via `writeJobFile` in `state.mjs` to prevent corruption during concurrent writes.

Jobs are automatically scoped to your current Claude session using `SESSION_ID_ENV`, ensuring that multiple users on the same repository do not see each other's background tasks unless they share a session ID.

## Best Practices for Background Codex Tasks

### Always Use `--background` for Long-Running Operations

For reviews, adversarial reviews, and rescue tasks that exceed a few seconds, append the `--background` flag to prevent UI freezing:

```bash
node scripts/codex-companion.mjs review --background --base main

```

This returns a JSON payload containing the `jobId`, `status: "queued"`, and `logFile` path, allowing immediate terminal access.

### Monitor the Structured Log File

Each background job writes detailed progress to a log file adjacent to its JSON state file in `.codex/jobs/`. Use `cat` or tail commands on the `logFile` path returned during job creation to inspect real-time progress outside of the CLI interface.

### Set Appropriate Reasoning Effort Levels

High-effort reasoning (`--effort high`) dramatically increases latency. For background jobs where completion time is flexible, specify your time budget explicitly:

```bash
node scripts/codex-companion.mjs task --background --effort medium "refactor authentication logic"

```

### Prefer Explicit Model Aliases

Avoid ambiguity by specifying model aliases directly. The `MODEL_ALIASES` map in `codex-companion.mjs` translates shortcuts like `spark` to `gpt-5.3-codex-spark`:

```bash
node scripts/codex-companion.mjs rescue --background --model spark "investigate flaky tests"

```

### Cancel Runaway Jobs Immediately

If a background job consumes excessive tokens or enters an infinite loop, terminate it using the saved PID:

```bash
node scripts/codex-companion.mjs cancel task-2026-07-05-13-42-01

```

The plugin calls `terminateProcessTree` and updates the job status to `"cancelled"` atomically.

### Resume Previous Tasks to Save Context

Use `--resume-last` to pick the most recent successful task thread, reusing context and reducing token usage:

```bash
node scripts/codex-companion.mjs task --background --resume-last "continue the refactor"

```

### Poll Job Status Programmatically

Query the current state without blocking using `/codex:status`:

```bash
node scripts/codex-companion.mjs status task-2026-07-05-13-42-01

```

This reads the stored JSON via `readStoredJob` in `job-control.mjs` and returns the current phase, timestamps, and completion percentage.

### Persist Job IDs for Automation

Store the `jobId` in environment variables when scripting CI pipelines:

```bash
export CODX_JOB=$(node scripts/codex-companion.mjs task --background "analyze dependencies" | jq -r .jobId)

# Later retrieval:

node scripts/codex-companion.mjs result $CODX_JOB

```

### Verify CLI Installation Before Queuing

Background jobs require the Codex CLI binary to be installed and authenticated. Run `/codex:setup` before enqueueing tasks to avoid immediate failures in the detached worker.

### Avoid Conflicting Flags

The `--background` and `--wait` flags are mutually exclusive. The code in `parseCommandInput` will throw if both are specified, so choose one execution mode per command.

## Practical Examples

### Queueing a Code Review in the Background

Start a comprehensive review on your main branch without blocking your terminal:

```bash
node scripts/codex-companion.mjs review --background --base main --effort high

```

**Expected output:**

```json
{
  "jobId": "task-2026-07-05-13-42-01",
  "status": "queued",
  "title": "Codex Review",
  "summary": "Running review on branch main",
  "logFile": "/path/to/.codex/jobs/task-2026-07-05-13-42-01.log"
}

```

### Monitoring Progress and Retrieving Results

Check the current status while the job runs:

```bash
node scripts/codex-companion.mjs status task-2026-07-05-13-42-01

```

Once completed, fetch the final rendered output:

```bash
node scripts/codex-companion.mjs result task-2026-07-05-13-42-01

```

The `render.mjs` module (lines 60-66) handles formatting the result or displaying error payloads if the job failed.

### Canceling a Background Task

If you need to abort a job:

```bash
node scripts/codex-companion.mjs cancel task-2026-07-05-13-42-01

```

This looks up the PID in the job record, terminates the process tree, and updates the status to `"cancelled"` via `upsertJob` in `state.mjs`.

## Summary

- **Use `--background`** to detach long-running Codex operations from the Claude Code UI, preventing terminal freezes.
- **Monitor jobs** via `/codex:status` and retrieve outputs with `/codex:result`, both of which read from JSON files in `.codex/jobs/`.
- **Cancel efficiently** using `/codex:cancel`, which terminates the specific PID stored in the job record.
- **Optimize resources** by setting `--effort` levels appropriately and using `--resume-last` to reuse context from previous tasks.
- **Ensure isolation** through the detached worker architecture in `spawnDetachedTaskWorker`, which protects your main session from crashes or memory spikes.

## Frequently Asked Questions

### What happens if I close Claude Code while a background job is running?

The detached worker process continues executing independently because `spawnDetachedTaskWorker` creates a separate Node process with its own PID. When you reopen Claude Code, use `/codex:status` or `/codex:result` with the job ID to retrieve the current state or final output from the persisted JSON files in `.codex/jobs/`.

### How do I know when my background Codex task is complete?

Poll the job status using `node scripts/codex-companion.mjs status <jobId>`, which reads the atomic state updates written by `writeJobFile`. The status field transitions from `"queued"` to `"running"` and finally to `"completed"` or `"failed"`, with timestamps recorded for each phase change.

### Can I run multiple background Codex jobs simultaneously?

Yes. Each call to `enqueueBackgroundTask` creates a unique job ID and spawns a separate detached process. Jobs are scoped to your current `SESSION_ID_ENV`, so you can queue multiple reviews or rescue tasks concurrently without interference, provided your system has sufficient resources.

### What is the difference between `--background` and `--wait`?

The `--background` flag detaches the job immediately and returns a JSON payload with the job ID, while `--wait` would block the terminal until completion. These flags are mutually exclusive in the source code, and attempting to use both will cause `parseCommandInput` to throw an error.