codex

name	codex
description	How to invoke the Codex CLI (`codex`) from the shell. Read this BEFORE shelling out to `codex` for any nontrivial task — it covers calling the real binary (not the Superconductor wrapper, which hangs) and capturing output with `-o` so the answer doesn't get buried in the agent-session stream.
allowed-tools	["Bash","Read"]

Calling Codex from the shell

Whenever you invoke codex from Bash, follow these two rules. They are not review-specific — they apply to any codex exec, codex review, or other non-interactive call.

1. Call the real binary, not the Superconductor wrapper

Superconductor installs a wrapper at ~/.superconductor/bin/codex (first on PATH) that injects its own MCP server via -c config overrides. That MCP handshake can hang codex indefinitely when run non-interactively from inside a Superconductor-managed session. Resolve and call the real binary:

CODEX_BIN="$(which -a codex | grep -v '/.superconductor/' | head -n1)"

Bash state does not persist between tool calls, so re-resolve $CODEX_BIN each call (or substitute the absolute path, e.g. ~/.nvm/versions/node/v22.16.0/bin/codex, into later commands).

2. For anything nontrivial, capture output with -o and read the file

When Codex actually thinks for a while, don't read its answer from stdout — add -o <file> and read that file instead:

CODEX_OUT="$(mktemp)"
"$CODEX_BIN" exec -o "$CODEX_OUT" "your prompt"   # or: "$CODEX_BIN" review --uncommitted -o "$CODEX_OUT"
# then Read "$CODEX_OUT"

Why. Codex streams its entire agent session to stdout — a config banner, then every tool call it makes (file reads, greps, scratch scripts) and each command's output — and prints the actual answer only as the final message. The longer it thinks, the more the real answer is buried in tool noise. Reading / skimming / tail-ing stdout makes the answer look like just more of the transcript, and it gets misread or silently lost. -o writes only that final message to the file, so you Read a clean result.

A non-empty $CODEX_OUT is the answer; an empty/absent file is the only true "Codex produced nothing" signal (exit code is 0 either way). Re-create $CODEX_OUT each call — Bash state doesn't persist.

Skip -o only for genuinely trivial one-shots where you expect a couple of lines and no tool use (e.g. codex --version).

Piping a prompt in

For codex exec, pass long or special-character-laden prompts via stdin, not argv — interpolating into the argv breaks on quotes/backticks and can blow ARG_MAX:

"$CODEX_BIN" exec -o "$CODEX_OUT" - <<'EOF'
<your prompt here>
EOF

One pass

Treat each call as one pass — no resume/follow-up unless the task specifically calls for it.