Skip to main content
subagent CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/codex-cli.md
Open on GitHub

What 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 parseConfig function does
  • Have codex-cli look at src/api.ts and point out bottlenecks

How to install codex-cli

Manually: put the files in place

.claude/agents/codex-cli.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

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

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set35

The whole set →
get-current-datetime get-current-datetime — a subagent that runs the date command with a specified timezone and returns only the raw output. Use it when you need the current date and time in a prompt without extra commentary. CX Codex ★ 2,744repo stars 10_instruction_stress 10_instruction_stress is a Claude Code prompt that tests whether a model follows four simultaneous constraints while describing an imaginary coffee shop. GP ChatGPT ★ 2,744repo stars 05_tool_heavy_task The 05_tool_heavy_task prompt has Claude Code read three files one at a time, then sum up Meridian’s testing strategy in a single paragraph. It also tests whether the agent makes separate tool calls. GP ChatGPT ★ 2,744repo stars zai-cli Routes code analysis requests to the GLM 4.7 model via the z.ai CLI directly from your Claude Code workflow. CX Codex ★ 2,744repo stars 09_typescript_refactor 09_typescript_refactor is a Claude Code prompt that makes TypeScript functions easier to read. It asks for a code block and a short explanation. GP ChatGPT ★ 2,744repo stars 02_english_prose 02_english_prose rewrites an English paragraph to remove every comma. You can restructure sentences and use other punctuation while preserving the meaning. GP ChatGPT ★ 2,744repo stars 08_csv_transform 08_csv_transform aggregates tabular order entries into customer spending totals and returns raw CSV without conversational filler. GP ChatGPT ★ 2,744repo stars 04_stack_trace_debug The 04_stack_trace_debug prompt asks Claude Code to find the cause of a Python stack trace, identify the failing call, and suggest a fix. Use it when you need a compact diagnosis. GP ChatGPT ★ 2,744repo stars

Project sponsors

Companies that keep this analytics open