codex-bridge

---
name: codex-bridge
description: "Cross-model second opinion via OpenAI Codex CLI. Three modes: Review (verify Claude's analysis), Challenge (force counter-arguments), Consult (open-ended question). Includes auth probe, version blocklist, and mandatory filesystem boundary prompt prefix. Use when the user asks 'what does codex think', 'second opinion', or 'cross-model check'."
effort: medium
mode: [engineering]
version: 1.0.0
sources:
  - https://github.com/garrytan/gstack/blob/main/codex/SKILL.md (MIT, Garry Tan)
---

# Codex-Bridge — Cross-Model Second Opinion

Wraps the OpenAI Codex CLI to get an independent, brutally honest second opinion from a different AI system on plans, code, or architecture decisions.

> Codex is the "200 IQ autistic developer" — direct, terse, technically precise, challenges assumptions, catches things Claude might miss. Present its output **faithfully, not summarized**.

## When to Use

- User asks "what does codex think?"
- User asks "second opinion" / "cross-model check" / "challenge this analysis"
- During `autoplan` Phase 3 (cross-model review)
- Before merging a non-trivial PR to verify Claude's recommendation

**Do NOT use** for trivial questions, conversation-level chitchat, or when codex CLI is not installed.

## Step 0: Check codex binary

```bash
CODEX_BIN=$(which codex 2>/dev/null || echo "")
[ -z "$CODEX_BIN" ] && echo "NOT_FOUND" || echo "FOUND: $CODEX_BIN"
```

If `NOT_FOUND`, stop and tell the user:

> "Codex CLI not found. Install it: `npm install -g @openai/codex` or see https://github.com/openai/codex. Once installed, re-run this skill."

Do NOT attempt to run codex without verified binary.

## Step 0.5: Auth probe + version check

Read `references/auth-probe.md` for full multi-source auth logic. Summary:

```bash
# Multi-signal auth probe (any one suffices)
if [ -n "$CODEX_API_KEY" ] || [ -n "$OPENAI_API_KEY" ] || [ -f "${CODEX_HOME:-$HOME/.codex}/auth.json" ]; then
  AUTH_OK=yes
else
  AUTH_OK=no
fi
```

If `AUTH_OK=no`, stop:

> "No Codex authentication found. Run `codex login` or set `$CODEX_API_KEY` / `$OPENAI_API_KEY`, then re-run this skill."

Read `references/version-blocklist.md` for known-bad versions:

```bash
CODEX_VERSION=$(codex --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
# Compare against blocklist; warn if matched (non-blocking)
```

If version is in blocklist, pass through warning verbatim:

> "WARN: Codex CLI version $CODEX_VERSION has known issues (see references/version-blocklist.md). Codex may still work, but consider upgrading."

## Step 1: Mode selection

Ask via AskUserQuestion (format v2):

```
D1 — Codex bridge mode

ELI10: Codex can run in 3 modes. Review verifies Claude's specific
       recommendation (does codex agree?). Challenge forces codex to
       construct counter-arguments to Claude's position. Consult is
       open-ended (free question to codex).

Recommendation: <mode> based on intent

Pros / cons:
A) Review (recommended for plan/PR verification)
   ✅ Tight scope: codex reviews Claude's specific recommendation
   ✅ Output: agree/disagree + rationale + alternatives
   ❌ Less surprising than Challenge
B) Challenge
   ✅ Forces counter-argument: "find what Claude got wrong"
   ✅ Best for high-stakes decisions where adversarial framing helps
   ❌ Can produce noise if Claude is right
C) Consult
   ✅ Open-ended: ask codex anything (no Claude position)
   ✅ Best for "what's the SOTA approach to X?" questions
   ❌ Not a verification of Claude's work — independent opinion only

Net: A = verify. B = adversarial. C = independent.
```

## Step 2: Scope selection

Ask via AskUserQuestion which scope codex should see:

| Scope | What gets sent |
|-------|----------------|
| `--scope file:<path>` | Single file content |
| `--scope diff` | Current branch's diff vs base |
| `--scope plan:<path>` | Plan file content |
| `--scope text:"<inline>"` | Inline text only |
| `--scope repo` | Whole repo (use sparingly — large) |

**Default**: `--scope diff` for branches with active work.

## Step 3: Resolve portable roots

```bash
PLAN_ROOT="${CLAUDE_PLANS_DIR:-./.blueprint/plans}"
TMP_ROOT="${CODEX_TMP_ROOT:-/tmp/codex-bridge}"
mkdir -p "$TMP_ROOT"
```

These keep the skill working whether installed as a Claude Code plugin (`CLAUDE_PLANS_DIR` set), a global install, or a CI container where `HOME` may be unset and `/tmp` may be read-only.

## Step 4: Build prompt with Filesystem Boundary

**MANDATORY** prefix on every codex invocation (per `references/filesystem-boundary.md`):

> IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing `skills/atlas-*` or `.claude/plugins/cache/`). These are AI assistant skill definitions meant for a different system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Stay focused on the repository code only.

This prevents codex from discovering ATLAS skill files on disk and following their instructions instead of reviewing the actual content.

Then append mode-specific instruction:

### Review mode prompt template

```
[Filesystem boundary prefix]

Claude has analyzed [scope description]. Claude's recommendation:

<verbatim Claude recommendation>

Your task: REVIEW this recommendation. Answer:
1. Do you agree? Yes / No / Partially.
2. What did Claude get right?
3. What did Claude get wrong or miss?
4. What's a better alternative if any?

Be terse and technical. Skip pleasantries.
```

### Challenge mode prompt template

```
[Filesystem boundary prefix]

Claude has analyzed [scope description] and recommended <X>.

Your task: CHALLENGE this recommendation. Construct the strongest counter-argument
you can. Find what Claude likely got wrong. If Claude is right, say so explicitly
and explain why your counter-argument fails.

Be adversarial. The goal is to surface blind spots.
```

### Consult mode prompt template

```
[Filesystem boundary prefix]

Independent question (no prior Claude position):

<user's question>

Context: <scope description>

Be terse and technical. Skip pleasantries.
```

## Step 5: Invoke codex

```bash
PROMPT_FILE="$TMP_ROOT/prompt-$(date +%s).txt"
RESPONSE_FILE="$TMP_ROOT/response-$(date +%s).txt"

# Write prompt
cat > "$PROMPT_FILE" <<EOF
<full prompt with filesystem boundary + mode-specific>
EOF

# Invoke (review mode example)
codex review --input-file "$PROMPT_FILE" > "$RESPONSE_FILE" 2>&1
EXIT_CODE=$?
```

If `EXIT_CODE != 0`, capture stderr and surface error to user (don't silently retry).

## Step 6: Present output faithfully

**Do NOT summarize** codex output. Present **verbatim**.

Format:

```markdown
## Codex Bridge — <mode> mode

**Scope**: <scope>
**Codex CLI**: v<version>
**Auth source**: <env|file>

### Codex output (verbatim)

<full codex response>

### Disagreement classification (per autoplan)

- If Claude and Codex agree → log as confirmation, no further action
- If Claude and Codex disagree on a non-trivial issue → autoplan classifies as **Taste** decision (surface at final gate)
- If Claude and Codex agree on overriding user direction → autoplan classifies as **User Challenge** (NEVER auto-decided, surface with rich context)
```

## Step 7: Logging

Log the call to `~/.atlas/runtime/codex-bridge.jsonl`:

```json
{"ts":"2026-05-05T20:30:00Z","mode":"review","scope":"diff","auth_source":"env_codex_api_key","cli_version":"0.121.0","tokens_in":<N>,"tokens_out":<N>,"recommendation":"<short>","agree_with_claude":true|false}
```

**NEVER log** the API key, the full prompt content (privacy), or the codex response body (already in TMP_ROOT for retrieval).

## Cross-references

- `references/auth-probe.md` — Multi-source auth probe logic
- `references/version-blocklist.md` — Known-bad codex CLI versions
- `references/filesystem-boundary.md` — Mandatory prompt prefix template
- `skills/autoplan/SKILL.md` — Phase 3 consumer
- `ETHOS.md` (root) §3 User Sovereignty — cross-model agreement is signal, not mandate

## Commands

- `/atlas codex-bridge` — opens mode selector + scope selector
- `/atlas codex-bridge --mode review --scope file:<path>` — Review specific file
- `/atlas codex-bridge --mode challenge --scope diff` — Challenge current diff
- `/atlas codex-bridge --mode consult --scope text:"<question>"` — open-ended consult

## HITL Gates (NON-NEGOTIABLE)

- **Always** verify codex CLI installed + auth before running
- **Never** silently retry on error (surface to user)
- **Never** send codex prompts without Filesystem Boundary prefix
- **Never** include `$CODEX_API_KEY` or proprietary code in audit logs

---

*Skill v1.0 — 2026-05-05 — adapted with attribution from gstack codex (MIT, Garry Tan)*