codex-bridge

Hand a single, bounded task to the Codex CLI and bring the result back for your review. Codex runs headless in this pod against Bedrock (openai.gpt-5.5); auth is the pod's IRSA credential chain — there are no secrets to manage.

You (the supervising Claude agent) stay in the loop: Codex's output is a proposal, not a commit. You read its diff/output, decide whether it's correct, and only then integrate it.

When to use this skill

Use it only when the person who triggered this run explicitly asked for Codex. Concrete triggers (in the issue body or the comment that summoned you):

• "use Codex to …"
• "ask Codex to review this diff / this file / this PR"
• "pass this to Codex" / "have Codex write / implement …"
• "get a second opinion from Codex"

If you scan the triggering text and find no explicit mention of Codex, stop — do not run this skill. Complete the task with your own tools. This gate is a hard requirement: firing autonomously spends Bedrock budget on a model the user did not choose and produces code authored by an unintended model.

How to use it

1. Confirm the explicit request

Re-read the triggering issue/comment. Confirm it names Codex and identifies a concrete, bounded task (write X, review file Y). If the ask is vague, ask the requester to narrow it rather than guessing.

2. Run the wrapper

The wrapper is scripts/run-codex.sh. It closes stdin, enforces a hard timeout, resets AWS credentials to the pod's IRSA defaults, and passes your instruction to Codex as a single argument (no shell interpretation of the text).

Write mode — Codex authors/edits code in the current working directory:

.claude/skills/codex-bridge/scripts/run-codex.sh write "Add a hello_world() function to hello.py that prints 'hello world'."

Review mode — Codex reviews a single file and reports findings (read-only intent):

.claude/skills/codex-bridge/scripts/run-codex.sh review path/to/changed_file.py

Review-diff mode — Codex reviews a whole PR-level diff at once (read-only intent), so it has cross-file context instead of one file at a time:

# Review the working tree vs. the default base (origin/main):
.claude/skills/codex-bridge/scripts/run-codex.sh review-diff
# …or against an explicit base ref:
.claude/skills/codex-bridge/scripts/run-codex.sh review-diff main

review-diff builds git diff <base>... (three-dot / merge-base semantics), caps it at CODEX_DIFF_MAX_BYTES (default 262144; a truncation marker is added and Codex is told when the diff is cut), and passes it to Codex as a single literal argument — the diff content is data, never shell-evaluated. An empty diff exits 0 without invoking Codex (no spend on nothing); running outside a git repo or against a bad base ref exits 2 before Codex runs.

Persona-calibrated review. In both review and review-diff, when a distilled persona pack resolves (${CODEX_DISTILLED_DIR}/${AGENT_TYPE}.md, the same file used for the AGENTS.md render), its conventions + quality bar are prepended to the review instruction so findings are persona-aware. If no pack resolves, the review prompt is byte-identical to the un-calibrated default. The AGENTS.md render still applies in review modes too — the prepend is additive calibration of the task, not a replacement.

The script prints Codex's final message to stdout. A non-zero exit means Codex failed or timed out — its stderr is surfaced; report it, do not silently retry in a loop.

3. Review before committing

Treat the result as a proposal:

• Write mode: run git diff and read every change. Verify it does what was asked, matches the repo's conventions, and introduces nothing unexpected. Run the relevant tests/linters. Only commit if it passes your review; otherwise fix or discard it. You own the final diff.
• Review mode: treat Codex's findings as input to your own judgment — a cross-model second opinion. Decide which points are valid before acting.

4. Restate the run summary (so it lands on the live run page)

The wrapper prints a compact, per-step summary of what Codex did — one line per reasoning step / command / file edit, Codex's final message, and a trailer with the session id, token usage, and the raw JSONL log path. That output sits inside the Bash tool result, so it does not reach the live run page on its own.

In your next message after the wrapper returns, restate that summary so it reaches operators watching the run (it lands one turn late) and appears in the completion comment. Keep it compact — ≤ ~20 lines:

• the per-step lines Codex emitted (reasoning / exec / edit), trimmed;
• Codex's final message (or a short paraphrase if it's long);
• the session id and token usage from the trailer.

Do not paste the raw JSONL — it stays on disk. Reference its path (shown in the trailer, under /tmp/codex-runs/) only if you need to point at it for deep debugging.

Guardrails

• The explicit-trigger gate is mandatory. No Codex mention → do not run this skill.
• One bounded task per invocation. Don't script open-ended loops of Codex calls; each run is supervised.
• You review the output. Codex authors a proposal; you are accountable for what gets committed.
• Never pass secrets in the instruction. The instruction text is the task description, not a place for credentials.