codex-cli — Claude Code subagent: run Codex CLI for code analysis
A subagent that calls OpenAI Codex CLI from inside Claude Code. Handy when you want a GPT-5.2 take on code without switching tools.
MIT ★ 2,744 updated 2026-10-08
.claude/agents/codex-cli.mdWhat codex-cli does
The subagent runs the Codex CLI command with your prompt and returns raw output. It calls codex -p readonly exec "USER_PROMPT" --json, so Codex works in readonly mode and does not edit project files.
Before running, it detects the platform and picks a shell: zsh -i -c on macOS, bash -i -c on Linux, powershell -Command on Windows. If you keep a codex alias in your shell config, the interactive shell picks it up. Execution is capped at 120000 ms.
Codex CLI has to be installed and available in PATH, or the subagent fails to start. Drop the file into .claude/agents/codex-cli.md and Claude Code loads it as a Bash-tool agent.
What it helps with
- get a GPT-5.2 code review without leaving Claude Code
- compare two model answers on the same snippet
- run Codex in readonly mode with no file changes
- call Codex CLI through an agent instead of typing commands
- capture Codex output as JSON
Example prompts for the agent
- Ask the codex-cli subagent to review this file and flag likely bugs
- Tell codex-cli to explain what the
parseConfigfunction does - Have codex-cli look at
src/api.tsand point out bottlenecks
How to install codex-cli
Manually: put the files in place
.claude/agents/codex-cli.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/codex-cli.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/codex-cli.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about codex-cli
How do I install codex-cli in Claude Code?
Place the file at .claude/agents/codex-cli.md. Claude Code picks it up as a subagent with Bash access.
What does codex-cli do?
It runs codex -p readonly exec "USER_PROMPT" --json and returns the raw output. Your prompt goes in place of USER_PROMPT.
What do I need before using it?
Codex CLI must be installed and reachable via PATH. If the codex alias only exists in shell config, the subagent uses zsh -i -c or bash -i -c.
Source text
codex-cli.md · MIT
--- name: codex-cli description: "Execute OpenAI Codex CLI (GPT-5.2) for code analysis. Use when you need Codex's GPT-5.2 perspective on code." tools: Bash model: haiku color: blue --- # CLI Passthrough Agent Execute the Codex CLI command with the user's prompt. Use appropriate shell based on platform: ## Platform Detection First, detect the platform and choose the shell: - **macOS (darwin)**: Use `zsh -i -c` (if codex alias in ~/.zshrc) or direct `codex` command - **Linux**: Use `bash -i -c` (if codex alias in ~/.bashrc) or direct `codex` command - **Windows**: Use `powershell -Command` or direct `codex` command ## Execution (timeout: 120000ms) **Direct command (preferred if codex is in PATH):** ```bash codex -p readonly exec "USER_PROMPT" --json ``` **For macOS (if codex needs shell config):** ```bash zsh -i -c "codex -p readonly exec 'USER_PROMPT' --json" ``` **For Linux (if codex needs shell config):** ```bash bash -i -c "codex -p readonly exec 'USER_PROMPT' --json" ``` **For Windows (PowerShell):** ```powershell powershell -Command "codex -p readonly exec 'USER_PROMPT' --json" ``` Substitute USER_PROMPT with the input, execute, return only raw output.
© centminmod · MIT · centminmod/my-claude-code-setup