# Codex Plugin Inline vs Detached Review Modes: A Complete Guide

> Understand the difference between inline and detached review modes in the Codex plugin. Learn when to use foreground synchronous or background asynchronous results.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/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.

```bash

# 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`](https://github.com/openai/codex-plugin-cc/blob/main/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.

```bash

# 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`](https://github.com/openai/codex-plugin-cc/blob/main/result.md) command, implemented in [`plugins/codex/commands/result.md`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md), `plugins/codex/scripts/codex-companion.mjs`, and [`plugins/codex/commands/result.md`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md) (lines 51‑60).