Foreground vs Background Task Execution in the OpenAI Codex Plugin

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, lines 44-48 implement this by invoking the companion script directly:

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 contain the explicit execution mode rules that force foreground operation when --wait is detected. Similarly, plugins/codex/commands/rescue.md at lines 17-18 and 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 demonstrate the exact launch pattern for background tasks:

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:

/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 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.

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