/external-agents

name: external-agents
description: >
  Invoke external AI CLIs (Codex, Gemini) for second opinions, code reviews, or alternative analysis.
  This skill SHOULD be used when the user asks for a "second opinion", "outside review",
  says "ask codex", "ask gemini", "run codex", "run gemini", "get another AI's take",
  or needs verification from a different model.

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.

2. **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.

3. **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.

4. **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

| 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

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

| 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 | | `codex exec resume <id>` | Send a follow-up prompt to an earlier `codex exec` session | | `codex resume` | Resume previous interactive session | | `codex apply` | Apply latest agent diff via `git apply` |

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 mod