# Foreground vs Background Task Execution in the OpenAI Codex Plugin

> Understand foreground vs background task execution in the OpenAI Codex plugin. Learn how to run tasks synchronously or asynchronously for uninterrupted workflow and easy status checks.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-08-02

---

**Foreground execution runs tasks synchronously and returns output immediately, while background execution spawns detached processes that allow you to continue working and check status later with `/codex:status`.**

The openai/codex-plugin-cc repository supports two distinct execution modes for its core operations including review, rescue, and adversarial-review. Understanding how foreground and background task execution differ helps you prevent chat timeouts during long-running jobs while optimizing for quick feedback when needed.

## How Foreground Execution Works

Foreground mode executes commands synchronously within the same chat turn. The plugin waits for the subprocess to finish, captures its stdout, and returns the raw output directly to the user without requiring additional messaging.

### The --wait Flag Implementation

When you append `--wait` to any command, the system routes to the foreground execution block. In [`plugins/codex/commands/review.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md), lines 44-48 implement this by invoking the companion script directly:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" review "--wait --base main"

```

The result appears immediately in the chat window because the process blocks until completion. This mode is ideal for small, quickly finishing jobs where instant feedback is required.

### Foreground Rules in Command Definitions

Lines 19-21 of [`plugins/codex/commands/review.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md) contain the explicit execution mode rules that force foreground operation when `--wait` is detected. Similarly, [`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md) at lines 17-18 and [`plugins/codex/commands/adversarial-review.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/adversarial-review.md) at lines 22-23 mirror this logic, ensuring consistent behavior across all slash-commands.

## How Background Execution Works

Background mode spawns the command as a detached process using the `Bash` tool with `run_in_background: true`. The current chat turn returns immediately, informing you that the job has started while the actual work continues in the background.

### The Detached Process Pattern

Lines 53-59 of [`plugins/codex/commands/review.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md) demonstrate the exact launch pattern for background tasks:

```typescript
Bash({
  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" review "--background --scope working-tree"`,
  description: "Codex review",
  run_in_background: true
})

```

The assistant responds with a confirmation message such as "Codex review started in the background," allowing you to continue other work without waiting for the operation to complete.

### Automatic Background Selection

When you run a command without explicit flags (for example, `/codex:review`), the plugin estimates the diff size using `git status` and `git diff`. If the operation appears large, the assistant prompts you to choose between "Wait for results" (foreground) or "Run in background," dynamically selecting the appropriate execution path based on the estimated workload.

## Monitoring Background Jobs with job-control.mjs

Once a background job starts, its state persists in the workspace through utilities defined in `plugins/codex/scripts/lib/job-control.mjs`. Lines 13-40 implement `buildStatusSnapshot`, `resolveCancelableJob`, and related functions that track active, completed, and cancelled jobs.

To inspect running tasks, use the status command:

```markdown
/codex:status

```

This queries the status snapshot utilities to display current job phases, completion percentages, and recent job history. The `job-control.mjs` module handles job enumeration and enrichment, ensuring you always have visibility into detached processes even across multiple chat sessions.

## Summary

- **Foreground execution** uses the `--wait` flag, runs synchronously in `codex-companion.mjs`, and returns output immediately via stdout capture.
- **Background execution** uses the `--background` flag or automatic detection, launches with `Bash` tool's `run_in_background: true`, and detaches immediately.
- **Job tracking** relies on `buildStatusSnapshot` and `resolveCancelableJob` in `plugins/codex/scripts/lib/job-control.mjs` to persist state.
- **Status checking** is performed via `/codex:status` to monitor active and completed background operations.

## Frequently Asked Questions

### When should I use foreground versus background execution?

**Use foreground execution** (`--wait`) for small, fast operations where you need immediate results and the output fits within a single chat turn. **Use background execution** (`--background`) for large reviews, extensive rescues, or any operation that might exceed chat timeout limits, allowing you to continue working while the task processes.

### How do I check if a background job is still running?

Run `/codex:status` in the chat. This command invokes `buildStatusSnapshot` from `plugins/codex/scripts/lib/job-control.mjs` to enumerate all active jobs, display their current phases, and show recently completed or cancelled tasks.

### Can I cancel a background job after it starts?

Yes. The `resolveCancelableJob` function in `plugins/codex/scripts/lib/job-control.mjs` provides mechanisms to interact with running background jobs. Use the appropriate slash-command (such as `/codex:cancel` if available) or check `/codex:status` to identify the job ID before requesting cancellation.

### What determines whether the assistant suggests foreground or background mode?

When no flag is specified, the plugin analyzes the repository state using `git diff` and `git status` to estimate the operation size. According to the logic in [`plugins/codex/agents/codex-rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/agents/codex-rescue.md) and similar command files, small requests default to foreground preferences while large diffs trigger a prompt asking you to choose between waiting or running in the background.