Codex · Claude Code plugin · Usage guide

Using the Codex plugin in Claude Code

Code is done — which command asks Codex to review?
The openai/codex-plugin-cc plugin lets Claude Code hand work to OpenAI Codex (GPT-5.x) via a local runtime. Short answer: default to /codex:review. For high-risk changes (security, public API contract, wide blast radius) use /codex:adversarial-review. Note: /codex:rescue is not a review step — it hands Codex a fix when you are stuck. Review output is always verbatim and runs on your real git state.

Summary diagrams (ASCII)

Quick summary: when code is done and you want Codex (GPT-5.x) to re-check, use /codex:review — that is the main command. rescue is not for review; it asks Codex to fix when you are stuck. Diagrams below are plain text (scroll sideways if needed).

1 · What the 7 plugin commands do
                    7 LỆNH CODEX PLUGIN v1.0.3
    ┌──────────────────────────────────────────────────────────────┐
    │                                                                │
    │  NHÓM KIỂM TRA  (dùng sau khi code xong)                       │
    │  ┌────────────────────┐   ┌──────────────────────────────┐     │
    │  │ /codex:review      │   │ /codex:adversarial-review    │     │
    │  │ Review bình thường │   │ Review kiểu "phá hoại",      │     │
    │  │ MẶC ĐỊNH dùng      │   │ cố tìm chỗ hỏng. Chỉ dùng    │     │
    │  │ cái này            │   │ khi thay đổi rủi ro cao       │     │
    │  └────────────────────┘   └──────────────────────────────┘     │
    │                                                                │
    │  NHÓM SỬA LỖI  (dùng khi bị bí, KHÔNG phải để kiểm tra)         │
    │  ┌────────────────────────────────────────────────────────┐    │
    │  │ /codex:rescue                                          │    │
    │  │ Giao Codex điều tra nguyên nhân + sửa khi Claude bị    │    │
    │  │ kẹt. Đây là bước sửa, không phải bước kiểm tra         │    │
    │  └────────────────────────────────────────────────────────┘    │
    │                                                                │
    │  NHÓM THIẾT LẬP + VẬN HÀNH  (không dùng cho từng lần code)      │
    │  ┌──────────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐     │
    │  │ /codex:setup │ │  status  │ │  result  │ │   cancel   │     │
    │  │ Cài 1 lần,   │ │ Xem job  │ │ Lấy kết  │ │ Huỷ job    │     │
    │  │ bật gate     │ │ đang chạy│ │ quả job  │ │ đang chạy  │     │
    │  └──────────────┘ └──────────┘ └──────────┘ └────────────┘     │
    │                                                                │
    └──────────────────────────────────────────────────────────────┘
2 · Which command? (decision tree)
   Bạn muốn làm gì sau khi code xong?
   │
   ├─ Muốn Codex kiểm tra lại code?
   │     │
   │     ├─ Thay đổi bình thường          ──►  /codex:review
   │     │
   │     └─ Thay đổi rủi ro cao           ──►  /codex:adversarial-review
   │        (bảo mật, đổi API công khai,
   │         ảnh hưởng rộng)
   │
   ├─ Review ra lỗi, tự sửa không nổi?   ──►  /codex:rescue
   │
   └─ Muốn Codex tự review mỗi phiên?    ──►  /codex:setup
                                              (bật review gate 1 lần)
3 · Where it sits in the full review pipeline
Ý tưởng cốt lõi: Opus 4.8 viết code, GPT-5.5 (Codex) review lại.
Không để mô hình viết code tự chấm điểm chính mình.

   BƯỚC 1        BƯỚC 2         BƯỚC 3               BƯỚC 4
   ┌────────┐    ┌────────┐    ┌────────────────┐    ┌─────────────────┐
   │/ak:test│──► │/verify │──► │/ak:code-review │──► │ /codex:review   │
   └────────┘    └────────┘    └────────────────┘    └─────────────────┘
   Chạy test     Chạy thử       Opus review          GPT-5.5 review độc
   (unit,        thật, xem      (phía Opus)          lập, bắt lỗi Opus
   build...)     có đúng không                       không thấy

   Ai làm:       Ai làm:        Ai làm:              Ai làm:
   AgentKit      Built-in       AgentKit             Codex (GPT-5.x)

   Rủi ro cao  ──►  đổi bước 4 thành  /codex:adversarial-review
4 · Practical rules
   ┌───────────────────────────────────────────────────────────────┐
   │  Sửa nhỏ, cơ học       →  /verify là đủ, khỏi cần Codex        │
   │                                                               │
   │  Thay đổi bình thường  →  /ak:code-review + /codex:review     │
   │                                                               │
   │  Rủi ro cao            →  thêm /codex:adversarial-review      │
   │                           + bật review gate qua /codex:setup  │
   └───────────────────────────────────────────────────────────────┘

   Chạy đủ 4 bước cho MỌI thay đổi là dư thừa (vi phạm YAGNI).
   Chỉ chạy nhiều khi thay đổi thực sự đáng.
5 · Internals when you run /codex:review
   Bạn gõ /codex:review
        │
        ▼
   ┌──────────────────────┐    ┌─────────────┐    ┌──────────────┐
   │ codex-companion.mjs  │──► │  Codex CLI  │──► │   GPT-5.x    │
   │ (runtime trung gian) │    │             │    │  đọc diff,   │
   └──────────────────────┘    └─────────────┘    │  chấm điểm   │
        ▲                                          └──────┬───────┘
        │                                                 │
        └─────────  Kết quả trả về nguyên văn  ◄──────────┘
                    (verbatim, không chỉnh sửa)

01Which command?

Match your situation, then pick the command on the right. Green = review, orange = fix.

Code is done — what do you want next?
Have Codex re-check the codeeveryday changes
→
/codex:review
Want a hard review that hunts break pointssecurity, public API contracts, wide impact
→
/codex:adversarial-review
Review found bugs you cannot fix alonehand Codex root-cause + fix
→
/codex:rescue
Want auto-review at end of each sessionenable the review gate once
→
/codex:setup
✓
Core idea: Opus 4.8 writes the code; GPT-5.5 (Codex) reviews it. Do not let the same model that wrote the code grade itself. That is why /codex:review is valuable.

027 commands, 3 groups

Memorize by group: review after coding, fix when stuck, setup/ops for jobs — not every commit.

Review group
Use after coding
/codex:review
Normal review. Default this.
/codex:adversarial-review
Adversarial review that hunts breakage. High-risk only.
Fix group
Use when stuck
/codex:rescue
Hand Codex investigate + fix. A fix step, not a review step.
Setup & ops
Not for every coding pass
/codex:setup
Readiness check; toggle review gate.
/codex:status
Inspect running jobs.
/codex:result
Fetch finished job output.
/codex:cancel
Cancel a background job.

03How the pieces fit

Claude stays in the driver's seat. Codex is a second engine Claude calls for review or a tight task, then returns raw output to you.

You
Type /codex: …
inside Claude Code
Claude Code
codex-companion.mjs
shared runtime, jobs per repo
Codex CLI
GPT-5.x
your ChatGPT / API login
Back to you
Verbatim result
findings, next steps

04Place in the review pipeline

Idea: run tests and real tryouts first, review next, then a second model. Codex is the last step.

Step 1
/ak:test
Run tests: unit, build
→
Step 2
/verify
Real tryout — does it work?
→
Step 3
/ak:code-review
Opus self-review
→
Step 4
/codex:review
Independent GPT-5.5 review
◆
High risk → swap step 4 for /codex:adversarial-review. Running all four steps on every change is wasteful (YAGNI): tiny mechanical edits only need /verify, no Codex.

05Install

Four commands inside Claude Code. Needs Node.js 18.18+ plus a ChatGPT plan or OpenAI API key.

  1. Add marketplace. /plugin marketplace add openai/codex-plugin-cc
  2. Install plugin. /plugin install codex@openai-codex
  3. Reload. /reload-plugins: registers commands, subagent, hooks.
  4. Verify. /codex:setup: checks Node, npm, Codex CLI, login.
★
No Codex CLI yet? /codex:setup can offer install (npm install -g @openai/codex) when npm is present. Otherwise install first, then re-run setup.

06Setup & login

/codex:setup reports readiness per component. Login reuses the local Codex CLI session. If logged out, run !codex login and pick ChatGPT or an API key.

Check Status Example detail
Node✓ readyv22.18.0
npm✓ ready11.7.0
Codex CLI✓ readycodex-cli 0.144.1 · advanced runtime available
Login✓ logged inusing ChatGPT login
Session runtimedirect startfirst review/task starts shared runtime if needed
Review gateoffenable with --enable-review-gate
◆
Not logged in? Setup still points you at !codex login. The ! prefix runs the command in-session so output lands in the chat.

07Command reference

Seven commands under /codex:. Review and rescue return Codex output verbatim: Claude does not paraphrase or act unless you ask.

/codex:review review only
Codex reviews your local git state: uncommitted work, or branch diff vs a base. Returns findings verbatim and never edits files. Default review command.
--wait --background --base <ref> --scope auto|working-tree|branch
/codex:review /codex:review --base main /codex:review --background
/codex:adversarial-review review only
Directed review that challenges the approach: design choices, trade-offs, assumptions — not only implementation bugs. Free-text focus after the flags.
--wait --background --base <ref> --scope auto|working-tree|branch chữ mô tả trọng tâm…
/codex:adversarial-review chất vấn thiết kế caching /codex:adversarial-review --base main --background tìm race condition
/codex:rescue can write files
Hand a task to Codex via the codex-rescue subagent: investigate, fix, or continue prior work. Default can write files. For diagnose-only, ask for review/research with no edits.
--background --wait --resume --fresh --model <model|spark> --effort none…xhigh
/codex:rescue điều tra vì sao test rớt /codex:rescue --model gpt-5.4-mini sửa lỗi hồi quy /codex:rescue --background đào sâu bộ test hay chập chờn
/codex:setup readiness
Checks whether Codex CLI is installed and logged in; also enables/disables the end-of-session review gate.
--enable-review-gate --disable-review-gate
/codex:setup /codex:setup --enable-review-gate # bật cổng
/codex:status job
List running/recent Codex jobs for this repo plus review-gate status. Pass a job ID for full detail on one run.
[job-id] --all --wait --timeout-ms <ms>
/codex:status /codex:status task-abc123
/codex:result job
Fetch saved final output of a finished job: conclusion, summary, findings, artifacts, next steps, and the Codex session ID so you can resume the thread in Codex.
[job-id]
/codex:result /codex:result task-abc123
/codex:cancel job
Cancel a background Codex job in this repo. Without an ID, cancels the current run.
[job-id]
/codex:cancel /codex:cancel task-abc123

08Auto review gate

An opt-in safety layer. When on, the plugin runs a focused Codex review at session end against Claude's answer. Blocking findings keep the turn open so Claude can fix before finishing. 

/codex:setup --enable-review-gate
# Codex reviews before Claude stops each turn.
/codex:setup --disable-review-gate
# Back to manual review only.
# At end of turn:
1. Claude drafts final answer
2. Codex focused review of the change
3. Blocking issues -> keep turn open, Claude continues
4. Clean      -> turn ends normally
▲
Cost warning. This gate can create long Claude/Codex loops and burn quota fast. Leave it off for daily work. Enable only for important changes where an extra pass is worth it.

09Rescue flow

/codex:rescue routes your task to the codex-rescue subagent: a thin prompt wrapper, one Codex call, raw output back. Nothing else auto-reads files or continues steps.

  1. Describe the work. Free text after the command: "investigate why X fails", "apply best fix", "port this to the new API".
  2. Resume or fresh. If a Codex thread can resume, you are asked once for --resume or --fresh. Follow-ups like "continue" default to resume.
  3. Foreground or background. Small tight tasks run in front. Open-ended/long work defaults to background — check with /codex:status.
  4. Verbatim result. Codex output is unedited. Re-fetch the full saved payload later with /codex:result.

10Model & effort

Set model and reasoning effort per run via flags, or defaults in Codex config. Flags win over config. 

# model + effort for one rescue
/codex:rescue --model gpt-5.4-mini --effort high fix flaky tests

# 'spark' maps to gpt-5.3-codex-spark
/codex:rescue --model spark investigate regression

# effort: none | minimal | low | medium | high | xhigh
# .codex/config.toml  (project level; repo must be trusted)
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
# ~/.codex/config.toml  (user defaults)
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
★
Leave --model and --effort empty to use Codex defaults. Rescue only overrides when you set them.

11Job lifecycle

Background review/rescue become tracked jobs, scoped per repo. Three commands cover their lifecycle.

running
/codex:status
phase, time, summary
done
/codex:result
full payload + session ID
cancel
/codex:cancel
stop a background job

FAQ

Is an OpenAI API key required?
Not necessarily: a ChatGPT plan works too. The plugin uses whatever the local Codex CLI is logged into. Run !codex login either way.
Does review change my code?
No. /codex:review and /codex:adversarial-review only review and return verbatim findings. Only /codex:rescue can write files — and you can still ask for diagnose-only.
review vs adversarial-review — which?
Use /codex:review for implementation bugs. Use /codex:adversarial-review to stress the approach: assumptions, trade-offs, and designs that break under real conditions.
Wait or background?
Without --wait or --background, the command estimates diff size and asks. Small changes (1–2 files) often suggest wait. Larger/unclear defaults to background.
How do I continue a Codex thread outside Claude?
/codex:result prints the Codex session ID. Resume that thread in the Codex CLI to keep context.
Why does rescue pick up work I did not request?
The codex-rescue subagent is used proactively when Claude is stuck or wants a second pass on a hard task. It does not snatch tiny jobs Claude can finish alone.