# How the Codex Review Gate Works and How to Enable or Disable It

> Understand the Codex review gate safety mechanism. Learn how to enable or disable this feature controlling Claude turn reviews using the stopReviewGate flag.

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

---

**The Codex review gate is a safety mechanism that forces a mandatory review of the previous Claude turn before a session can be closed, controlled by the Boolean `stopReviewGate` flag in the plugin's persistent state.**

The Codex review gate is implemented in the **openai/codex-plugin-cc** repository as an optional safeguard. When enabled, it intercepts `/codex:stop` commands, runs a programmatic review of the session's changes, and can block termination if issues are detected. This article explains the gate's architecture and provides the exact commands to toggle it.

## How the Codex Review Gate Works

### Core Architecture

The review gate consists of four interconnected components:

1. **Persisted configuration** — The `stopReviewGate` flag is stored in [`state.json`](https://github.com/openai/codex-plugin-cc/blob/main/state.json) and defaults to `false` on first use. In `plugins/codex/scripts/lib/state.mjs`, lines 19-26 initialize this value when the plugin state is created.

2. **Setup command** — The `/codex:setup` sub-command provides CLI access to toggle the flag, implemented in `plugins/codex/scripts/codex-companion.mjs` (lines 29-34).

3. **Stop-gate hook** — The `stop-review-gate-hook.mjs` script enforces the gate logic when sessions terminate.

4. **Status reporting** — The global status view displays the gate state through the `needsReview` field.

### The Stop-Gate Hook Execution Flow

When a user runs `/codex:stop` or the companion process exits, `plugins/codex/scripts/stop-review-gate-hook.mjs` executes:

```javascript
// From stop-review-gate-hook.mjs, lines 46-48
const config = await getConfig(workspaceRoot);

```

If `config.stopReviewGate` is `false`, the hook logs any running task and allows the stop to proceed (lines 54-57).

If `config.stopReviewGate` is `true`, the hook performs three operations (lines 66-74):

- Verifies Codex is correctly set up
- Runs the `runStopReview` task to analyze the previous turn
- Blocks the stop unless the review returns an `ALLOW:` line, emitting `{"decision": "block"}` with a reason

## How to Enable or Disable the Codex Review Gate

### Using CLI Commands

| Action | Command | Effect |
|--------|---------|--------|
| **Enable** | `!codex setup --enable-review-gate` | Sets `config.stopReviewGate` to `true`; stops now require review approval |
| **Disable** | `!codex setup --disable-review-gate` | Sets `config.stopReviewGate` to `false`; stops proceed immediately |
| **Check state** | `!codex status` | Shows "Review gate: enabled" or "Review gate: disabled" in output |

The `--enable-review-gate` and `--disable-review-gate` flags call `setConfig(workspaceRoot, "stopReviewGate", value)` as shown in `codex-companion.mjs` lines 29-34. The setup report (lines 98-110) confirms the new state.

### Verifying the Current State

The status system exposes the gate state through two mechanisms:

- **Programmatic access**: `plugins/codex/scripts/lib/job-control.mjs` lines 38-39 set `needsReview` from `config.stopReviewGate`
- **Human-readable output**: `plugins/codex/scripts/lib/render.mjs` lines 330-331 print the formatted status line

```bash

# Example status output showing enabled gate

!codex status

# → Review gate: enabled

# → needsReview: true

```

### Programmatic Control

To toggle the gate from custom scripts, use the same internal helpers:

```javascript
import { setConfig, getConfig } from "./plugins/codex/scripts/lib/state.mjs";
import { resolveWorkspaceRoot } from "./plugins/codex/scripts/lib/workspace.mjs";

const workspaceRoot = resolveWorkspaceRoot(process.cwd());

// Check current state
const current = await getConfig(workspaceRoot);
console.log("Gate enabled:", current.stopReviewGate);

// Toggle
await setConfig(workspaceRoot, "stopReviewGate", !current.stopReviewGate);

```

The `setConfig` helper is defined in `plugins/codex/scripts/lib/state.mjs` lines 53-60 and atomically writes to [`state.json`](https://github.com/openai/codex-plugin-cc/blob/main/state.json).

## Complete Example Workflow

```bash

# 1. Enable the review gate

!codex setup --enable-review-gate

# → Enabled the stop‑time review gate for /path/to/workspace.

# 2. Start a coding session

!codex start

# 3. Make changes...

# 4. Attempt to stop — this triggers the review

!codex stop

# → [review runs automatically]

# → If review finds issues: {"decision":"block","reason":"Codex stop‑time review found issues …"}

# → If review passes: session closes normally

# 5. Disable when no longer needed

!codex setup --disable-review-gate

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| `plugins/codex/scripts/stop-review-gate-hook.mjs` | Core enforcement logic; checks flag and runs blocking review |
| `plugins/codex/scripts/codex-companion.mjs` | CLI toggle commands (`--enable-review-gate`, `--disable-review-gate`) |
| `plugins/codex/scripts/lib/state.mjs` | Persistence layer; provides `setConfig()` and `getConfig()` |
| `plugins/codex/scripts/lib/job-control.mjs` | Status snapshot including `needsReview` field |
| `plugins/codex/scripts/lib/render.mjs` | Formatted "Review gate: enabled/disabled" output |

## Summary

- The **Codex review gate** is controlled by `config.stopReviewGate`, defaulting to `false`
- **Enable** with `!codex setup --enable-review-gate`; **disable** with `--disable-review-gate`
- When enabled, the `stop-review-gate-hook.mjs` script blocks `/codex:stop` until review returns `ALLOW:`
- Configuration persists in [`state.json`](https://github.com/openai/codex-plugin-cc/blob/main/state.json) via `plugins/codex/scripts/lib/state.mjs`
- Check current state through `!codex status` or the `needsReview` field in status snapshots

## Frequently Asked Questions

### What happens if the review gate blocks a stop?

The hook emits a JSON payload with `"decision": "block"` and a reason string, as implemented in `stop-review-gate-hook.mjs` lines 66-74. The session remains active and the user must address the identified issues or disable the gate to proceed.

### Can the review gate be enabled per-workspace?

Yes. The [`state.json`](https://github.com/openai/codex-plugin-cc/blob/main/state.json) file and `stopReviewGate` flag are scoped to the workspace root resolved via `resolveWorkspaceRoot()`. Each workspace maintains independent configuration, so enabling the gate in one project does not affect others.

### Does enabling the gate affect existing running sessions?

No. The gate is evaluated only at stop-time. Enabling the flag via `!codex setup --enable-review-gate` takes effect immediately for future stop commands but does not interrupt or modify active Codex processes.