external-agents

External AI CLIs: Codex & Gemini

Run OpenAI Codex CLI or Google Gemini CLI for second opinions and external reviews.

Critical Rules

1. Run CLIs directly via Bash (with run_in_background: true for async). Subagents cannot approve Bash permissions interactively — the command gets denied.

2. Do NOT pipe stdin into codex exec — codex ignores stdin entirely. Save content to a file (e.g., /tmp/review-diff.txt) and tell codex to read it in the prompt. Piping produces empty/plan-only output.

Prerequisites

Tool	Install	Config
Codex	npm install -g @openai/codex	codex login / ~/.codex/config.toml
Gemini	brew install gemini-cli	Google auth / ~/.gemini/settings.json

Check availability: codex --version / gemini --version

When to Use

• User wants a second opinion from a different AI model
• Code review from an external perspective
• Verification of an approach or architecture
• User explicitly requests codex or gemini

Recommended Models

No "latest" alias exists for either CLI — you must pin specific model names.

Codex (SWE-optimized)

Model	Use Case
gpt-5.4	Best. Latest agentic coding model.
gpt-5.3-codex	Previous generation. Still capable.
gpt-5.2-codex	Older generation.

Set default in ~/.codex/config.toml: model = "gpt-5.4"

Codex uses stored OAuth tokens (~/.codex/auth.json) from codex login — no env var needed.

Gemini

Model	Use Case
gemini-3.1-pro-preview	Best. Latest model (Feb 2026). Requires previewFeatures: true.
gemini-3-pro-preview	Previous generation preview.
gemini-3-flash-preview	Faster, good for quick checks.
gemini-2.5-pro	Stable GA fallback if preview models have capacity issues.
gemini-2.5-flash	Fast GA fallback.

Always pin the model with -m in non-interactive/headless calls. The user's ~/.gemini/settings.json may use auto-gemini-3 routing, which can select Flash for prompts it classifies as "simple" — not what you want for code reviews.

If you hit 429 MODEL_CAPACITY_EXHAUSTED on preview models, fall back to -m gemini-2.5-pro. This is a server capacity issue (not quota) and mostly affects oauth-personal auth. Enterprise API key (gemini-api-key auth with billing) has better capacity allocation.

Set default in ~/.gemini/settings.json:

{ "model": { "name": "gemini-3.1-pro-preview" } }

Codex CLI

Subcommands

Command	Purpose
codex review	Git-aware code review (non-interactive)
codex exec	Non-interactive prompt execution (always pass -C "$PWD" to set working directory)
codex resume	Resume previous interactive session
codex apply	Apply latest agent diff via git apply

Code Review (most common use)

Important: codex review treats --base, --uncommitted, --commit, and [PROMPT] as mutually exclusive modes. You cannot combine a custom prompt with --base or --uncommitted. To review with custom instructions, save the diff to a file and tell codex exec to read it (codex ignores stdin).

# Review uncommitted changes (default instructions)
codex review --uncommitted

# Review branch against main (default instructions)
codex review --base main

# Review specific commit (default instructions)
codex review --commit <SHA>

# Review with custom instructions — save diff to file, tell codex to read it
# IMPORTANT: Do NOT pipe into codex exec — it ignores stdin. Save to a file instead.
git diff main...HEAD > /tmp/review-diff.txt
codex exec -C "$PWD" --full-auto "Read /tmp/review-diff.txt and review for error handling and security" -o /tmp/codex-review.txt

# Review with title context
codex review --uncommitted --title "Add user auth middleware"

Non-Interactive Execution

# Freeform analysis
codex exec -C "$PWD" "Analyze the auth module for security issues"

# Specify model (overrides config.toml default)
codex exec -C "$PWD" -m gpt-5.4 "Review this codebase architecture"

# Full-auto mode (sandboxed, auto-approves)
codex exec -C "$PWD" --full-auto "Refactor the test helpers"

# JSONL event output
codex exec -C "$PWD" --json "List all TODO comments" -o /tmp/result.txt

# Read-only analysis (use --full-auto for headless; -s read-only hangs waiting for plan approval)
codex exec -C "$PWD" --full-auto "Audit dependencies for vulnerabilities"

Key Flags

Flag	Purpose
-m, --model <MODEL>	Model selection (e.g., gpt-5.4)
-c key=value	Override config (TOML format)
-s, --sandbox <MODE>	read-only, workspace-write, danger-full-access (avoid read-only in headless mode — triggers plan-confirmation that hangs)
--full-auto	Sandboxed auto-execution (preferred for headless/non-interactive use)
-C, --cd <DIR>	Set working directory (use this instead of --skip-git-repo-check)
--search	Enable web search tool
--json	JSONL event output (exec only)
-o, --output-last-message <FILE>	Write last message to file (exec only)

Gemini CLI

Non-Interactive (Headless)

# Non-interactive prompt (exits when done)
gemini -p "Review this codebase for architectural issues"

# Auto-approve all actions
gemini -y -p "Fix the failing tests"

# Structured output
gemini -o json -p "List the public API surface of src/auth/"

Interactive

# Interactive with initial prompt
gemini -i "Help me debug the auth flow"

# Resume last session
gemini -r latest

# Include additional directories
gemini --include-directories ../shared-lib "Review cross-repo dependencies"

Key Flags

Flag	Purpose
-m, --model <MODEL>	Model selection
-p, --prompt <TEXT>	Non-interactive (headless) mode
-i, --prompt-interactive <TEXT>	Run prompt then stay interactive
-y, --yolo	Auto-approve all actions
--approval-mode <MODE>	default, auto_edit, yolo
-r, --resume <ID>	Resume session (latest or index)
--include-directories <DIRS>	Additional workspace directories
-o, --output-format <FMT>	text, json, stream-json

Usage Patterns

Get a Second Opinion on Changes

# Codex (git-aware, understands diffs natively)
codex review --uncommitted

# Gemini (prompt-based)
gemini -p "Review the uncommitted changes in this repo for bugs and security issues"

Review a Design Decision

codex exec -C "$PWD" "Evaluate the architecture in src/auth/. Is the token refresh approach sound?"

gemini -p "Analyze src/auth/ and critique the token refresh strategy"

Review a Branch Before PR

# Default review (no custom prompt needed)
codex review --base main

# Custom review instructions — save diff to file, tell codex to read it
git diff main...HEAD > /tmp/review-diff.txt
codex exec -C "$PWD" --full-auto "Read /tmp/review-diff.txt and review for correctness, test coverage, and maintainability" -o /tmp/codex-review.txt

Troubleshooting

Gemini: GEMINI_API_KEY not found

Gemini with gemini-api-key auth reads GEMINI_API_KEY from the environment. If the key is managed by direnv, it's only available when direnv loads the .envrc that exports it. A child directory with its own .envrc shadows the parent without inheriting — so the key can be missing depending on which directory the session runs from.

Pre-flight check (run before any Gemini invocation):

echo "GEMINI_API_KEY: ${GEMINI_API_KEY:+set (${#GEMINI_API_KEY} chars)}"

If unset, tell the user and skip Gemini. Codex does not have this problem — it uses stored OAuth tokens from codex login.

Gemini: stdin bug

cat file | gemini -p "..." fails with "Cannot use both a positional prompt and the --prompt flag together." Gemini's arg parser treats cat-piped stdin as a positional argument conflicting with -p. Use < file redirection instead: gemini -m MODEL -p "prompt" < /path/to/file. This works correctly.

Gemini: headless tool trust bug

#18776: Gemini in -p headless mode cannot reliably use filesystem tools — the folder trust check fails. Feed content via stdin rather than expecting Gemini to read files itself.

Codex: plan-confirmation instead of review

If codex output contains "Plan:" followed by "If you're happy with that approach" — codex didn't execute, it proposed a plan and waited for approval. Two causes:

1. -s read-only in headless mode — triggers plan confirmation. Use --full-auto instead.
2. Piped stdin — codex exec ignores stdin entirely. The prompt says "review this" but codex has nothing to review, so it proposes a plan to go find the content. Save to a file and reference it in the prompt instead.

Codex: -o creates no file

If Codex exhausts its turns without producing a final summary, -o creates no output file. Always check file existence, not just content.

General

• Codex ignores stdin — never use | codex exec or echo ... | codex exec. Save to a file and reference it in the prompt. Gemini reads stdin correctly via < file redirection (not cat | gemini).
• If a command fails with a syntax error, run <tool> --help to check current flags before retrying.
• If an upgrade notice appears, inform the user. Do NOT auto-upgrade.
• Codex config values use TOML format: -c model_reasoning_effort="high"

Codex Companion Script (codex-plugin-cc)

The codex-plugin-cc plugin provides a companion script that wraps codex review with structured JSON output, an app-server protocol, and job lifecycle management. Prefer it over raw codex review when available.

Discovery

The companion script resolves its own ROOT_DIR via import.meta.url, so it works from any cwd. Search known install locations:

CODEX_COMPANION=""
setopt NULL_GLOB 2>/dev/null  # zsh: suppress "no matches found" when globs miss
for d in ~/.claude/plugins/marketplaces/*/plugins/codex/scripts/codex-companion.mjs \
         ~/.claude/repos/*/plugins/codex/scripts/codex-companion.mjs; do
  [ -f "$d" ] && CODEX_COMPANION="$d" && break
done
unsetopt NULL_GLOB 2>/dev/null
# Project-local .cloned-sources fallback
if [ -z "$CODEX_COMPANION" ]; then
  REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
  [ -n "$REPO_ROOT" ] && [ -f "$REPO_ROOT/.cloned-sources/codex-plugin-cc/plugins/codex/scripts/codex-companion.mjs" ] && \
    CODEX_COMPANION="$REPO_ROOT/.cloned-sources/codex-plugin-cc/plugins/codex/scripts/codex-companion.mjs"
fi

Invocation

# Structured JSON review of branch vs main
node "$CODEX_COMPANION" adversarial-review -C "$PWD" --json --base main

# With user focus text
node "$CODEX_COMPANION" adversarial-review -C "$PWD" --json --base main "Check auth handling"

# Working tree (uncommitted changes)
node "$CODEX_COMPANION" adversarial-review -C "$PWD" --json --scope working-tree

Output envelope

The --json flag produces a structured payload:

{
  "result": {
    "verdict": "approve | needs-attention",
    "summary": "1-2 sentence assessment",
    "findings": [
      {
        "severity": "critical | high | medium | low",
        "title": "Short name",
        "body": "WHAT breaks, SCENARIO, IMPACT",
        "file": "path/to/file",
        "line_start": 10,
        "line_end": 25,
        "confidence": 0.85,
        "recommendation": "Concrete fix"
      }
    ],
    "next_steps": ["actionable step"]
  }
}

Requirements

• Codex CLI must be authenticated: the companion script delegates to codex review internally, so codex login is required.
• Node.js: the companion is an .mjs file, requires node in PATH.

If the companion isn't found, fall back to raw codex review (unstructured text output).

Core Principle

Use the codex-plugin-cc companion script for structured JSON reviews when available. Fall back to codex review for git-aware code reviews. Use codex exec for freeform analysis (save content to files, reference in prompt — codex ignores stdin). Use gemini -p with < file redirection for content analysis.