external-agents

What this skill does

# 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`:
```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).

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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):
```bash
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