Background Jobs

Run Codex tasks in the background and manage them with status, result, and cancel.

What background mode does

When you pass --background to any command that supports it, the plugin:

1. Enqueues the job and records it in the repository’s job state.
2. Spawns a detached task-worker process that runs Codex independently.
3. Returns immediately so you can continue working in Claude Code.

The Codex run proceeds in the background. You check on it and retrieve output using /codex:status, /codex:result, and /codex:cancel.

---

Starting a background job

Both review commands and /codex:rescue support --background:

/codex:review --background
/codex:adversarial-review --background
/codex:rescue --background investigate the regression

Job IDs are generated as review-<id> for review jobs and task-<id> for rescue jobs. You can see all job IDs in /codex:status output.

---

Checking status

/codex:status shows all running and recent jobs for the current repository. To inspect a specific job, pass its ID:

/codex:status
/codex:status task-abc123

If you omit the job ID from status, result, or cancel, the command operates on the most recent job.

Job states:

State	Meaning
queued	Enqueued; the worker process is starting.
running	Codex is actively working on the task.
completed	The job finished successfully.
cancelled	The job was cancelled before or during execution.

---

Getting the result

Once a job is completed, retrieve its full output with /codex:result:

/codex:result
/codex:result task-abc123

The output includes the full Codex response. When available, it also includes the Codex session ID.

You can reopen any completed Codex job directly in Codex: run codex resume <session-id> using the session ID shown in /codex:result. This lets you review the run or continue the work with the full Codex interface.

---

Cancelling a job

While a job is queued or running, cancel it with /codex:cancel:

/codex:cancel
/codex:cancel task-abc123

Cancel sends an interrupt to the active Codex turn and terminates the worker process. The job is then marked cancelled.