Codex Plugin Inline vs Detached Review Modes: A Complete Guide

The Codex plugin delivers review results in two modes: inline (foreground) runs synchronously and returns output immediately, while detached (background) runs asynchronously and returns results later via /codex:result.

The openai/codex-plugin-cc repository provides two distinct ways to execute code reviews depending on whether you need instant feedback or prefer to continue working while the review processes in the background. Understanding these delivery modes helps you choose the right approach for your workflow.

How Inline (Foreground) Mode Works

Inline mode executes the review command directly and blocks until completion. The plugin runs node …/codex‑companion.mjs review "$ARGUMENTS" without background execution, sending the companion script's stdout verbatim to the user in the same Claude turn.

This mode is defined in plugins/codex/commands/review.md (lines 42‑48) under the "Foreground flow" section. The user receives the complete review output immediately after the command finishes.

# User invokes inline mode with --wait flag

/codex:review --wait

# Plugin executes directly (from review.md Foreground flow):

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" review "$ARGUMENTS"

# Output returns immediately in the same conversation turn

How Detached (Background) Mode Works

Detached mode launches the review as a background task using the Bash step with run_in_background: true. The companion script runs asynchronously, allowing the user to continue working while the review processes.

This implementation appears in plugins/codex/commands/review.md (lines 51‑60) under the "Background flow" section. The companion script's --background flag handling in plugins/codex/scripts/codex‑companion.mjs triggers this behavior.

# User invokes detached mode with --background flag

/codex:review --background

# Plugin executes via Bash with background flag (from review.md Background flow):

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

# Immediate response:

# "Codex review started in the background. Check `/codex:status` for progress."

# Later, retrieve the result:

/codex:result <job-id>

Key Differences Between Inline and Detached Modes

Aspect	Inline Mode	Detached Mode
Execution	Synchronous, foreground	Asynchronous, background
Response time	Blocks until review completes	Returns instantly with acknowledgement
Result delivery	Immediate, same turn	Fetched later via /codex:result or /codex:status
Best for	Small reviews needing quick answers	Large reviews or when continuing work

Controlling the Delivery Mode

The Codex plugin provides explicit flags and an interactive fallback:

• --wait — Forces inline execution, preventing background processing
• --background — Forces detached execution, enabling asynchronous operation
• Neither flag — The plugin prompts once, recommending inline or detached based on estimated review size

The flag parsing logic resides in plugins/codex/scripts/codex-companion.mjs, which determines how to invoke the review process based on user input.

Retrieving detached results requires the separate result.md command, implemented in plugins/codex/commands/result.md. This command fetches completed review output from background jobs.

Summary

• Inline mode runs codex-companion.mjs directly and returns review output immediately in the same Claude turn
• Detached mode uses Bash({ … run_in_background: true }) to execute asynchronously, with results fetched later via /codex:result
• Control flags --wait and --background explicitly select the mode, or the plugin prompts when unspecified
• Source files managing these flows are plugins/codex/commands/review.md, plugins/codex/scripts/codex-companion.mjs, and plugins/codex/commands/result.md

Frequently Asked Questions

What happens if I don't specify --wait or --background when running a review?

The plugin asks you once which mode to prefer. It recommends the appropriate option based on the estimated size of the review task, guiding you toward inline for smaller reviews and detached for larger ones.

How do I retrieve results from a detached review?

Use the /codex:result <job-id> command, implemented in plugins/codex/commands/result.md, to fetch completed review output. You can also check /codex:status to monitor progress while the review runs.

Can I switch a running detached review to inline mode?

No. Once a review starts in detached mode, it continues as a background process. You would need to cancel and restart with --wait if you require synchronous execution.

Where is the background execution logic implemented in the source code?

The Bash({ … run_in_background: true }) call appears in plugins/codex/scripts/codex-companion.mjs, with the command definition and flow documentation in plugins/codex/commands/review.md (lines 51‑60).

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