--- name: Codex Fleet slug: codex-fleet category: AI Engineering description: Executes Codex CLI tasks, generates images with gpt-image-2, and orchestrates parallel fleets of codex delegates for high-throughput AI-driven code work and asset creation. github: "https://github.com/avenoxai/avenoxskills/tree/main/skills/codex-fleet" language: Shell stars: 37 forks: 1 install: "npx degit https://github.com/avenoxai/avenoxskills/tree/main/skills/codex-fleet ~/.claude/skills/codex-fleet" installs_to: ~/.claude/skills/codex-fleet source_path: skills/codex-fleet/SKILL.md collection_size: 10 category_size: 2451 collection_url: "https://dirskills.com/collections/avenoxai/avenoxskills" added: 2026-08-11T07:21:42.194Z last_synced: 2026-08-11T07:21:42.194Z canonical_url: "https://dirskills.com/skills/codex-fleet" --- # Codex Fleet Executes Codex CLI tasks, generates images with gpt-image-2, and orchestrates parallel fleets of codex delegates for high-throughput AI-driven code work and asset creation. **Install:** ```bash npx degit https://github.com/avenoxai/avenoxskills/tree/main/skills/codex-fleet ~/.claude/skills/codex-fleet ``` ## README # Codex Fleet — Standalone Action Runner > A single self-contained skill for driving the [Codex CLI](https://github.com/openai/codex) from any agent (Claude Code, Cursor, or your own harness). No external control plane required — everything here runs against a plain local `codex` install. Drop this file into `.claude/skills/codex-fleet/SKILL.md` (or your agent's skills dir) and go. > > Built and battle-tested by [Avenox](https://avenox.lol). Share freely. This skill does three things and ALWAYS executes them, never describes them: 1. **General Codex CLI tasks** — code review, refactor, multi-file edits, analysis, diagnosis, anything you'd hand to a peer-AI for parallel processing. 2. **Image generation** — real rendered images via Codex's built-in `gpt-image-2` tool: backgrounds, portraits, icons, sigils, banners, UI assets, sprites, mockups, photoreal, infographics. 3. **Fleets** — spawning many `codex exec` delegates in parallel (one lane or twenty), with worktree isolation for concurrent write lanes. ## CRITICAL: This is an ACTION skill, not commentary When invoked you MUST: 1. **Actually invoke `codex exec` via the Bash tool.** Never write instructions for the user to run themselves. 2. **Default to background execution** (`run_in_background: true`) for any task likely to take >10s. This lets the main agent continue other work in parallel while Codex runs. The harness notifies on completion. 3. **For multiple independent jobs, fire them ALL in parallel.** Codex sessions don't contend. Compute is not the bottleneck — throughput is. If the user asks for 4 images or 3 codex investigations, that's 4 or 3 simultaneous Bash calls in one message, all `run_in_background: true`. 4. **Summarize results from logs** after each background job completes — don't dump raw stdout unless asked. If the user's request is "use codex to X" or "run codex on X", run `codex exec ... "X"`. Don't wrap, don't paraphrase, don't ask "should I proceed" — just go. ## Prerequisites - Codex CLI 0.128+ installed and authenticated (`codex --version`). Reasoning tiers `low`/`medium`/`high`/`xhigh` require 0.128+. - For the image-gen **CLI fallback** and `gpt-image-1.5` transparency path only: `OPENAI_API_KEY`. The built-in `image_gen` tool uses your Codex subscription and needs no key. ## Defaults (locked in) | Setting | Value | When to override | |---|---|---| | Model | `gpt-5.6-sol` | `-m ` only if user specifies | | Reasoning effort | `high` | `xhigh` ONLY on explicit user request ("use xhigh", "max reasoning", "deep"); `medium`/`low` for cheap mechanical lanes | | Service tier | **standard — fast is OFF** | see the note below; opt in per-call only | | Sandbox | `read-only` | `workspace-write` for edits; `danger-full-access` for image gen or network (ask first) | | `--skip-git-repo-check` | always | always | | Stderr | suppressed (`2>/dev/null`) | only show when debugging | | `--color never` | recommended | when you need to grep stdout cleanly | Reasoning levels available (codex 0.128+): `low`, `medium`, `high`, `xhigh`. Lean toward `high`. Don't downgrade to "save effort" unless the lane is genuinely mechanical. > **Fast tier is OFF by default — do not add it.** `-c service_tier=fast -c fast_default_opt_out=false` buys ~1.5× speed at ~2.5× rate cost. That trade is wrong for how this skill is used: everything here is background-first and parallel, so nobody is staring at a single lane's latency, and burning 2.5× rate on twenty lanes drains your limits for no wall-clock gain. Standard tier gives you the same quality plus rate-limit headroom. Every example in this file omits it deliberately. Opt in per-call only when a human is actively blocked on one foreground result — never for fleets, never as a global default. --- ## Part 1 — General Codex Tasks ### Base command ```bash codex exec --skip-git-repo-check \ -m gpt-5.6-sol \ -c model_reasoning_effort=high \ --sandbox read-only \ "" 2>/dev/null ``` ### Sandbox quick reference | Use case | Flags | |---|---| | Read-only review / analysis / diagnosis (default) | `--sandbox read-only` | | Apply local edits | `--sandbox workspace-write --full-auto` | | Network access or broad system access | `--sandbox danger-full-access --full-auto` (confirm with user first) | For a working dir other than CWD: add `-C `. For escalated reasoning: replace `model_reasoning_effort=high` with `=xhigh`. ### Background-first invocation pattern Run any non-trivial codex task in the background. Don't block the main thread: ``` Bash tool call: command: codex exec --skip-git-repo-check -m gpt-5.6-sol \ -c model_reasoning_effort=high \ --sandbox read-only \ "Review src/foo.ts for race conditions and report findings." 2>/dev/null run_in_background: true ``` Then continue other work. When the background notification fires, read the log/output and summarize. For tasks where you genuinely need the result before doing anything else (rare), run foreground. ### Parallelization (the default for multiple jobs) If the user asks for N independent codex investigations, fire all N as separate `run_in_background: true` Bash calls **in a single message**. They run simultaneously. Compute is not constrained. Example: "have codex review the contracts AND the backend AND the frontend" → 3 parallel codex jobs, not sequential. ### Resume To continue a previous session (preserves model, reasoning, sandbox of the original): ```bash echo "follow-up prompt" | codex exec --skip-git-repo-check resume --last 2>/dev/null ``` When resuming, **do not pass `-m`, `-c model_reasoning_effort`, or `--sandbox`** — they inherit. Only add flags if the user is explicitly changing the configuration. ### Critical evaluation of Codex output Codex runs on OpenAI's models with their own training cutoffs. Treat it as a peer, not an authority: - Trust your own knowledge when confident; push back on Codex claims you know to be wrong. - Verify via web search or live docs when uncertain — especially for model names, recent library versions, post-cutoff API changes. - For substantive disagreements, resume and discuss as a peer: ```bash echo "I disagree with [X] because [Y]. What's your take?" \ | codex exec --skip-git-repo-check resume --last 2>/dev/null ``` - Frame as discussion, not correction. Either AI can be wrong. If genuine ambiguity remains, surface it to the user. ### Error handling - If `codex --version` or `codex exec` exits non-zero, stop and report. Do not retry blindly. - High-impact flags (`--full-auto`, `--sandbox danger-full-access`, `--dangerously-bypass-approvals-and-sandbox`) require explicit user OK before first use in a session — after that you can keep using them within the same task scope. --- ## Part 1.5 — Multi-Image Reference Chains (CRITICAL) For both general codex tasks (passing images for analysis) AND image generation (passing reference images for style/character consistency), codex supports `-i, --image ...` to attach images to the prompt context. ### THE BUG: greedy `-i` parse eats your prompt The `-i FILE...` flag is **variadic-greedy** — without termination it consumes the prompt itself as another `` argument and codex falls through to stdin, which is empty, and errors out: ``` Reading prompt from stdin... No prompt provided via stdin. ``` **WRONG (silently fails):** ```bash codex exec [opts] -i ref1.png -i ref2.png "prompt text" > log 2>&1 ``` **RIGHT (use `--` separator):** ```bash codex exec [opts] -i ref1.png -i ref2.png -- "prompt text" > log 2>&1 ``` The `--` terminates the `-i` flag's greedy parse and the prompt is correctly passed as a positional argument. This is the single most important pattern for any multi-reference image-gen workflow. ### Sequential reference chaining for series consistency When generating a series of frames where each new frame must reference the previous one (key frames of a video sequence, multi-shot scenes, character continuity across beats), chain codex calls with `&&` so each call waits for the previous output to materialize before starting: ```bash mkdir -p output/dir && \ codex exec [opts] -i char_sheet.png \ -- "frame1 prompt → save to output/dir/frame1.png" > /tmp/log1 2>&1 && \ codex exec [opts] -i char_sheet.png -i output/dir/frame1.png \ -- "frame2 prompt → save to output/dir/frame2.png" > /tmp/log2 2>&1 && \ codex exec [opts] -i char_sheet.png -i output/dir/frame1.png -i output/dir/frame2.png \ -- "frame3 prompt → save to output/dir/frame3.png" > /tmp/log3 2>&1 ``` This guarantees temporal/visual continuity: frame N has frame N-1 (and earlier) loaded as visual references. Each frame's prompt explicitly tells codex which attached image is the "character bible" vs the "previous frame" so the model knows what to match. Run the whole chain as ONE background bash call (`run_in_background: true`) — you get a single notification when the entire chain completes. Per-frame failures stop the chain via `&&` short-circuit. ### Parallel non-dependent generation For independent assets with NO continuity needed (e.g., 5 different characters in 5 different scenes), use **5 separate background bash calls in a single message** instead of chaining — much faster (5x parallel rather than serial). ### Reference image hierarchy (recommended pattern) For viral content, character drama, multi-shot work: build a reusable reference hierarchy. Three levels: 1. **Character bible (turnaround sheet)** — 3-pose model sheet on white background, locks body / material / proportion / wardrobe. The canonical reference for ALL downstream generations of that character. 2. **Key art** — single dramatic environment shot, locks the character's persona vibe in their canonical world. Optional secondary reference for tone-matching. 3. **Stage / scene frames** — actual story-beat frames generated using the bible + previous frames as references. **Rule of thumb when adding `-i` flags to a generation call:** - Need character consistency? Pass the character bible. - Need scene/environment continuity from a previous beat? Pass that previous frame. - Need multi-character scene? Pass each character's bible. - For style-only continuity across different scenes? Pass an earlier frame from the series as a "production-style anchor." The model will use whichever attached images are visually relevant to your prompt's instructions. Be explicit in the prompt about which attached image plays which role ("reference 1 is the character bible, reference 2 is the immediately preceding beat"). --- ## Part 2 — Image Generation (gpt-image-2) Generate real rendered images via Codex CLI's built-in `image_gen` tool, defaulting to **`gpt-image-2`** (snapshot `gpt-image-2-2026-04-21`). This is for actual painted/rendered output — backgrounds, portraits, sigils, banners, sprites, icons, hero images, photorealistic shots, mockups, infographics. Studio-grade when invoked correctly. ### CRITICAL — Always force the imagegen tool Codex defaults to writing Python+PIL when asked to "generate an image" or "make pixel art." That produces low-fidelity procedural output (10–20KB files, no real artistic rendering). To get the real `image_gen` tool (gpt-image-2), the prompt MUST contain something like: ``` TOOL DIRECTIVE: You MUST use the built-in image generation tool (image_gen / gpt-image-2). DO NOT write Python. DO NOT use PIL/Pillow/canvas/sharp/any drawing library. DO NOT generate procedurally with code. You MAY use shell commands (cp, mv, ls, find) to relocate the resulting file from ~/.codex/generated_images/ to the target output path. If the image gen tool is unavailable, refuse and say so explicitly. ``` That last line about `cp/mv` is essential — without it, Codex over-interprets the constraint and refuses to copy the generated PNG out of its cache directory, leaving the asset orphaned. **Alternative trigger:** Codex 0.128+ supports `$imagegen` as an explicit skill marker. Including the literal string `$imagegen` in the prompt biases Codex to invoke the official imagegen skill workflow. Use both together for maximum reliability. ### Base command (image generation) ```bash codex exec --skip-git-repo-check --ephemeral -s danger-full-access \ -m gpt-5.6-sol \ -c model_reasoning_effort=high \ --ignore-rules \ --color never \ "" 2>/dev/null ``` Flag breakdown: - `-s danger-full-access` — required to write files. Image-gen tool needs this sandbox level to copy the result to disk. - `-m gpt-5.6-sol` — agent model that decides to call `image_gen`. Best prompt-following for image workflows. - `-c model_reasoning_effort=high` — default per skill policy. `xhigh` only on explicit request. - `--ephemeral` — fresh session each call, no history pollution between image jobs. - `--ignore-rules` — skips repo-rule scanning (avoids policy hits on prompts). - `--skip-git-repo-check` — runs anywhere. - `--color never` — clean stdout for log parsing. ### Output handling The built-in `image_gen` tool does NOT take a target file path. Generated images land at: ``` ~/.codex/generated_images//ig_.png ``` (`$CODEX_HOME` is `~/.codex` by default; respect `$CODEX_HOME` if the user has overridden it.) Two ways to get them where you want them: 1. **Let Codex copy them itself.** Include the target path in your prompt and explicitly authorize `cp/mv` (see the directive block above). Codex will `find` the result and `cp` it. 2. **Find and copy yourself afterwards.** If Codex refuses to copy (over-cautious), the files are still in the cache: ```bash find ~/.codex/generated_images -type f -name '*.png' -mmin -5 ``` …then `cp` them to where you need them. This is the reliable fallback. ### Parallelization (default for ≥2 assets) For multiple assets, fire each as a separate `codex exec` Bash call with `run_in_background: true`. Don't serialize — Codex sessions are independent. ``` Single message with 4 Bash tool calls, all run_in_background: true: codex exec [...flags...] "PROMPT_BG" > /tmp/codex-bg.log 2>&1 codex exec [...flags...] "PROMPT_PORTRAITS" > /tmp/codex-portraits.log 2>&1 codex exec [...flags...] "PROMPT_SIGIL" > /tmp/codex-sigil.log 2>&1 codex exec [...flags...] "PROMPT_BANNER" > /tmp/codex-banner.log 2>&1 ``` After each completes, inspect the log to confirm the image-gen tool was invoked (look for `ig_.png` in the log — that's the cache path indicator) and confirm the target file exists. **Default rule:** if generating ≥2 distinct assets, always parallelize. ONE prompt per `codex exec` call — do not stuff multiple unrelated assets into a single prompt; quality drops and recovery is harder. **Note on `n`:** the underlying API supports `n` (1–10) for **variants of the same prompt**. Don't use `n` as a substitute for separate prompts when you want different assets — that's what parallel `codex exec` calls are for. ### Sizes (gpt-image-2) `gpt-image-2` accepts `auto` or any `WIDTHxHEIGHT` that meets ALL of: - Max edge ≤ **3840px** - Both edges multiples of **16px** - Long-edge / short-edge ratio ≤ **3:1** - Total pixels between **655,360** and **8,294,400** - Outputs above **2560×1440** are technically supported but flagged as experimental — quality variance is higher Popular sizes (use these unless there's a reason not to): | Use | Size | |---|---| | Square (default fast) | `1024x1024` | | Landscape | `1536x1024` | | Portrait | `1024x1536` | | 2K square | `2048x2048` | | 2K landscape (widescreen) | `2048x1152` | | 4K landscape | `3840x2160` | | 4K portrait | `2160x3840` | | Auto | `auto` | Square is fastest. Don't ask for tiny output (e.g. `256x256`) — the tool will reject it (below min-pixels). Generate at a supported size and downscale with `sips` afterwards. ### Quality (gpt-image-2) Four levels: `low`, `medium`, `high`, `auto`. - `low` — fast drafts, thumbnails, candidate sweeps, "show me the rough idea" - `medium` — fine for most preview/draft work - `high` — **default for finals.** Final assets, dense text inside the image, tight composition, identity-sensitive edits, large outputs - `auto` — let the model pick The built-in tool doesn't expose `--quality` directly to the prompt, but you can ask for it ("high quality, fine detail") and the tool tends to honor it. For deterministic quality control, use the CLI fallback (see below). ### Prompt craft (gpt-image-2) The OpenAI prompting guide is explicit: **structure prompts as scene/backdrop → subject → key details → constraints**, and state intended use to set polish level. gpt-image-2 rewards specificity in this rough order: 1. **Use case / intended surface** — "landing page hero," "tarot card icon," "game faction crest," "infographic frame" 2. **Subject + composition** — what's centered, what's around it, camera angle 3. **Material / medium** — "obsidian shard," "bronze cupped hands," "filigree gold ornament," "matte ceramic," "35mm film" 4. **Lighting / mood** — "deep amber inner glow," "cold sapphire light bleeding from cracks," "soft studio softbox" 5. **Style anchor** — "Octopath Traveler / Triangle Strategy / Disco Elysium portrait icon caliber" — these references work consistently. For photoreal: avoid "studio polish" language; prompt as if capturing a real moment. 6. **Palette** — give hex codes when colors matter: `warm orange (#ff6a3d), sapphire (#4a8eff), jade (#3dd47b)` 7. **Negative space** — "leave the upper third calm for UI overlay readability" 8. **Background instruction** — "deep midnight starfield" / "flat #00ff00 chroma-key for removal" / "warm sunset gradient" 9. **Constraints / avoid list** — "no text, no watermark, no logos" / for edits: "change only X; keep Y unchanged" For game-asset icons / sigils: ask for "tarot card icon" or "videogame faction crest" — these style references reliably produce iconic centered compositions with ornate frames. For atmospheric backgrounds: cinematic + painterly + name a specific game or visual ref. Avoid "pure pixel art" — you'll get blocky low-fi. Instead: "high-fidelity digital painting in the visual language of detailed pixel art" gets you the polished JRPG-screenshot look. For text inside the image (gpt-image-2 is strong at this): put the literal text in **straight quotes**, specify font style and placement, and use `quality: high`. For tricky words: spell letter-by-letter and demand verbatim rendering. ### Transparency — chroma-key workflow (preferred) `gpt-image-2` does NOT support `background=transparent`. The official Codex skill ships a workflow that's just as good for most subjects: 1. Generate the subject on a flat solid chroma-key background (default `#00ff00`; use `#ff00ff` for green subjects; avoid `#0000ff` for blue subjects). 2. Run the bundled helper to convert the key color to alpha. **The bundled helper is at:** ``` $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py ``` (typically `~/.codex/skills/.system/imagegen/scripts/remove_chroma_key.py`) Standard invocation: ```bash python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \ --input .png \ --out .png \ --auto-key border \ --soft-matte \ --transparent-threshold 12 \ --opaque-threshold 220 \ --despill ``` Prompt the chroma-key generation like this (paste into your `codex exec` prompt): ``` Create the requested subject on a perfectly flat solid #00ff00 chroma-key background for background removal. The background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation. Keep the subject fully separated from the background with crisp edges and generous padding. Do not use #00ff00 anywhere in the subject. No cast shadow, no contact shadow, no reflection, no watermark, and no text unless explicitly requested. ``` If a thin fringe remains after removal, retry once with `--edge-contract 1`. Use