run-codex

A guide for sending clearly specified coding tasks to GPT-5.5 through the Codex command-line tool, with fallback to Claude models when needed.

In plain words
What is it for?
Use it for migrations, codemods, large refactors, log analysis, and independent code reviews. It supports read-only investigations, file edits, and scoped reviews of changes.
Why use it?
It frees the main agent from repetitive or large tasks and provides an independent review when a second opinion is useful.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/tarekkharsa/agentstack/run-codex
Any agent
npx skills add Tarekkharsa/agentstack --skill run-codex
Clone the repo
git clone --depth 1 https://github.com/Tarekkharsa/agentstack

Made for: Claude Code, Codex.

Per session 54 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 736 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00054 $0.00736
Opus 5 $0.00027 $0.00368
Sonnet 5 $0.00011 $0.00147
Haiku 4.5 $0.00005 $0.00074

Measured yesterday against content hash 31baf3662a47, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

run-codex scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

crates/cli/catalog/skills/run-codex/SKILL.md · 76 lines

How it starts

The opening of the file, as written. The whole thing — 76 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Run Codex (gpt-5.5)

Use this skill when you want to hand a well-specified chunk of work to gpt-5.5 (via OpenAI's Codex CLI) instead of doing it inline — because it's bulk/mechanical, or because you want a second, independent perspective on something that ships.

When to reach for Codex

  • Bulk / mechanical work you can fully specify — migrations, codemods, repetitive refactors, large data or log analysis.
  • An independent review — a second opinion on a diff or plan, from a different model than the one that wrote it.
  • Not for taste-critical UI/copy/API design, or vague tasks you can't pin down — those stay with the orchestrating model.

Rule of thumb: if you can fully specify the task in the prompt, it's a good Codex job. If you can't specify it, don't delegate it.

Commands

# Investigate / review — read-only, cannot edit files:
codex exec -s read-only "<self-contained prompt>"

# Make edits — can modify the working tree:
codex exec "<self-contained prompt>"

# Review a diff — scope is required (bare `codex review` errors):
codex review --base <branch>        # or --uncommitted, or --commit <sha>

Write self-contained prompts

Codex starts fresh — it does not see your conversation. Every prompt must carry its own context: the goal, the exact files/paths, the acceptance criteria, and any conventions that matter.

Codex reads AGENTS.md, not CLAUDE.md. If the project's conventions live in CLAUDE.md (build/test commands, style, commit format), paste the relevant ones into the prompt.

Timeouts

Codex runs can exceed a 10-minute command timeout. Pass an explicit longer timeout, or run it in the background and poll for its output / report file.

Parallel edits → isolate

If you run several editing Codex jobs at once, give each its own git worktree so their edits don't collide in the shared checkout.

Quota-aware fallback (important)

Codex access is usually a finite quota, not unlimited.

  • On a usage-limit / quota / 429 error: do not retry — quota errors don't clear by retrying. Redo the task with a Claude model instead (clear-spec/mechanical → a small model; tricky, user-facing, or review work → a strong model).
  • Once Codex reports a limit, treat it as exhausted for the session — stop routing new work to it, and tell the user, so they know the token mix shifted.
  • A transient failure (network, timeout, malformed output) is different: one retry is fine before falling back.

Read the full file on GitHub · 76 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 76 lines · 54 tokens per session scan A 31baf3662a47

Subscribe to this mod's changes

run-codex is a skill published in the GitHub repository Tarekkharsa/agentstack (3 stars, last pushed 18d ago), licensed Apache-2.0. It adds 54 tokens to every session and 736 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.