kylesnowschwartz/simpleclaude/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. Subagents cannot approve Bash permissions interactively, so the command gets denied. run_in_background: true is fine for long runs.

1. End every non-interactive `codex` call with `</dev/null` unless you pipe content in. When stdin is not a terminal, codex exec reads it and waits for end of file before it starts, so an inherited pipe that never closes hangs it with no output. Piping content in on purpose works: when stdin is piped and a prompt is also given, codex appends stdin to the prompt as a <stdin> block.

1. Capture the final message and stderr. Pass -o <file> for the final message and redirect stderr to a file (2><file>). The session id: line you need to resume a run is printed on stderr, not stdout. Check that the -o file exists before reading it.

1. Pair every read-only Codex call with `-c 'approval_policy="never"'`. The sandbox alone does not block writes: when the user's ~/.codex/config.toml sets approval_policy = "on-request", Codex can ask to run a command outside the sandbox, and an approved request writes files. With the policy set to never, Codex cannot escalate and writes fail with "operation not permitted". codex exec and codex exec resume have no -a flag, so -c is the only way to set it.

Prerequisites

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

Models

Codex

Use the default model from ~/.codex/config.toml (model = "..."). Pass -m <model> only when the user names a model.

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

Gemini

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

Code Review (most common use)

codex review has no -s flag, so the examples set the sandbox and approval policy with -c.

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, pipe the diff into codex exec, or save it to a file and name the file in the prompt.

# Review uncommitted changes (default instructions)
codex review -c 'sandbox_mode="read-only"' -c 'approval_policy="never"' --uncommitted </dev/null
 
# Review branch against main (default instructions)
codex review -c 'sandbox_mode="read-only"' -c 'approval_policy="never"' --base main </dev/null
 
# Review specific commit (default instructions)
codex review -c 'sandbox_mode="read-only"' -c 'approval_policy="never"' --commit <SHA> </dev/null
 
# Review with title context
codex review -c 'sandbox_mode="read-only"' -c 'approval_policy="never"' --uncommitted --title "Add user auth middleware" </dev/null
 
# Review with custom instructions: pipe the diff in; codex appends it as a <stdin> block
git diff main...HEAD | codex exec -s read-only -c 'approval_policy="never"' -o /tmp/codex-review.md "Review the diff in the stdin block for error handling and security" 2>/tmp/codex-review.err
 
# Or save the diff to a file and name it in the prompt
git diff main...HEAD > /tmp/review-diff.txt
codex exec -s read-only -c 'approval_policy="never"' -o /tmp/codex-review.md "Read /tmp/review-diff.txt and review it for error handling and security" </dev/null 2>/tmp/codex-review.err

Non-Interactive Execution

Use -s read-only together with -c 'approval_policy="never"' for reviews, questions, and analysis. Use -s workspace-write only when Codex must change files in the repository.

# Read-only analysis
codex exec -s read-only -c 'approval_policy="never"' -o /tmp/codex-out.md "Analyze the auth module for security issues" </dev/null 2>/tmp/codex-err.txt
 
# A model the user named (otherwise omit -m)
codex exec -s read-only -c 'approval_policy="never"' -m <model> -o /tmp/codex-out.md "Review this codebase architecture" </dev/null 2>/tmp/codex-err.txt
 
# Changes that need writes inside the repository
codex exec -s workspace-write -o /tmp/codex-out.md "Refactor the test helpers" </dev/null 2>/tmp/codex-err.txt
 
# JSONL event output on stdout
codex exec -s read-only -c 'approval_policy="never"' --json "List all TODO comments" </dev/null >/tmp/codex-events.jsonl 2>/tmp/codex-err.txt
 
# Outside a git repository
codex exec --skip-git-repo-check -C /path/to/dir -s read-only -c 'approval_policy="never"' -o /tmp/codex-out.md "Summarize the notes in this directory" </dev/null 2>/tmp/codex-err.txt

Follow-up questions

Resume the same session by its id, so Codex keeps the context of the first run. Take the id from the session id: line in the stderr file. Use the explicit id rather than --last when several Codex runs may be active.

A resumed session does not inherit the first run's sandbox or model: it falls back to ~/.codex/config.toml, which may allow writes and network access. Pass the sandbox with -c sandbox_mode=... (resume has no -s flag), set -c 'approval_policy="never"' so the resumed run cannot escalate out of the sandbox, and pass -m again if the first run used it.

SESSION_ID=$(sed -n 's/^session id: //p' /tmp/codex-err.txt)
codex exec resume -c 'sandbox_mode="read-only"' -c 'approval_policy="never"' -o /tmp/codex-followup.md "$SESSION_ID" "Expand on the second finding" </dev/null 2>/tmp/codex-followup.err
 
# The first run used a model the user named
codex exec resume -c 'sandbox_mode="read-only"' -c 'approval_policy="never"' -m <model> -o /tmp/codex-followup.md "$SESSION_ID" "Expand on the second finding" </dev/null 2>/tmp/codex-followup.err

The sandbox: line in the stderr file shows the sandbox the resumed run used. A resumed run that was not given approval_policy="never" can write outside a read-only sandbox when the user's config allows approval requests. codex exec resume accepts -o and --json. It has no -C flag. Outside a git repository, run it from the same directory as the first run and add --skip-git-repo-check.

Key Flags

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

Usage Patterns

Get a Second Opinion on Changes

# Codex (git-aware, understands diffs natively)
codex review -c 'sandbox_mode="read-only"' -c 'approval_policy="never"' --uncommitted </dev/null
 
# Gemini (prompt-based)
gemini -p "Review the uncommitted changes in this repo for bugs and security issues"

Review a Design Decision

codex exec -s read-only -c 'approval_policy="never"' -o /tmp/codex-out.md "Evaluate the architecture in src/auth/. Is the token refresh approach sound?" </dev/null 2>/tmp/codex-err.txt
 
gemini -p "Analyze src/auth/ and critique the token refresh strategy"

Review a Branch Before PR

# Default review (no custom prompt needed)
codex review -c 'sandbox_mode="read-only"' -c 'approval_policy="never"' --base main </dev/null
 
# Custom review instructions: pipe the diff in
git diff main...HEAD | codex exec -s read-only -c 'approval_policy="never"' -o /tmp/codex-review.md "Review the diff in the stdin block for correctness, test coverage, and maintainability" 2>/tmp/codex-review.err

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