Ck:codex

Codex CLI Skill

Use the codex CLI (OpenAI GPT-5.5 + GPT-5.4 Image 2) as a complementary tool to Claude. Codex's strengths are careful file reading, edge-case spotting, role-play fidelity, and unlimited high-quality image generation under subscription auth.

When To Use Codex (Decision Tree)

User intent
├── "Review/audit my code/PR/diff"        → Codex review  (see references/code-review-workflows.md)
├── "Audit/review my plan or spec"        → Codex plan audit (see references/plan-audit-workflows.md)
├── "Generate an image/banner/illustration/icon/infographic/visual asset" → Codex image gen (see references/image-generation.md)
├── "Get a second opinion from Codex"     → Codex exec one-shot
├── "Pretend to be Gemini/Qwen/o3"        → Codex role-play (see references/best-practices.md)
└── "Just run codex on X programmatically" → Codex exec (see references/cli-reference.md)

Do NOT use Codex when:

• The task is small, mechanical, or fully solvable by Claude in the current session (waste of latency/credits).
• The user wants a final implementation pushed to disk by Codex — prefer Claude for in-session edits, use Codex for analysis only unless explicitly asked.
• Sensitive data is in the working dir without user clearance (Codex sends content to OpenAI).

Why Codex Beats Claude For Certain Tasks

| Task | Why Codex | |------|-----------| | Plan/spec audit | Codex (GPT-5.5) reads files carefully — catches edge cases Opus skims. Uses ~4× fewer tokens than Claude on equivalent work | | PR review | Independent reader, fresh context, no shared bias with the implementing Claude session. Native GitHub integration via @codex review | | Image generation | gpt-image-2 (announced Oct 2025) via subscription counts toward limits but no per-image dollar charge; iterate fast in terminal. Field reports prefer it over Gemini Nano Banana Pro for mockups/decorations/banners. Invoke via bundled $imagegen skill. Native transparency NOT supported — uses official chroma-key workflow (see image-generation.md) | | Style/persona prompting | Persona instructions in AGENTS.md or one-off prompts shift Codex's voice/verbosity reliably. Cross-model mimicry (Codex behaving as Gemini/Qwen/o3) is community-reported but unverified — use for prompt iteration only, not production routing |

Core Invocation Patterns

All Codex calls are non-interactive (codex exec or codex review). NEVER call bare codex in a script — it opens the TUI.

Pattern 1: One-shot prompt

codex exec -C "$PWD" --skip-git-repo-check /ig_*.png` (built-in tool) OR CWD (if prompt says "Save as X"). `scripts/codex-generate-image.sh` snapshots both.
- **`gpt-image-2` does NOT support native transparent PNG** — official chroma-key workflow: generate on `#00ff00` background then run `scripts/codex-strip-chroma-key.sh`. Only escalate to `gpt-image-1.5 --background transparent` after asking user (upstream rule: never silently downgrade).
- **`gpt-image-2` ignores exact pixel dimensions** — verified empirically (a "256x256" request returned 1254x1254). Resize via ImageMagick if exact dimensions matter.
- **Don't double-instruct**: Codex respects `AGENTS.md` cascading from project root → CWD. Don't repeat global rules in the prompt.
- **Don't pipe huge files**: prefer `-i path` for images; let Codex read text files via its own tools. Stdin >100KB is slow/truncatable.
- **Codex sessions persist** in `~/.codex/sessions/`. Use `--ephemeral` for one-off prompts you don't want logged.
- **Watch the dual-window rate limit** (subscription): 5-hour window AND weekly window both must have budget. Check via `/status`.
- **Platform sandbox gotchas** (see `references/best-practices.md`): Windows error 1385, macOS MCP shell-exec blocked in workspace-write, Linux symlinked `.codex/` panics.

## Workflows

| Task | Script | Reference |
|------|--------|-----------|
| Review a GitHub PR with Codex | `scripts/codex-review-pr.sh ` | `references/code-review-workflows.md` |
| Audit a plan file | `scripts/codex-audit-plan.sh ` | `references/plan-audit-workflows.md` |
| Generate + relocate image (auto-prepends `$imagegen`) | `scripts/codex-generate-image.sh "" [out-dir]` | `references/image-generation.md` |
| Strip chroma-key → transparent PNG (uses upstream `remove_chroma_key.py`) | `scripts/codex-strip-chroma-key.sh  ` | `references/image-generation.md` |
| Persona prompting (style/tone only) | inline `codex exec` with persona prompt | `references/best-practices.md` |
| All CLI flags | — | `references/cli-reference.md` |

## Output Handling

After every Codex call:
1. **Read the output** — never assume Codex succeeded silently.
2. **Surface findings to user verbatim** when Codex audits something; do not summarize away edge cases (that defeats the point of asking Codex).
3. **If Codex generated images**, run the post-move logic in `scripts/codex-generate-image.sh` or manually:
   ```bash
   latest_session=$(ls -t ~/.codex/generated_images/ | head -1)
   mv ~/.codex/generated_images/"$latest_session"/* ./assets/ && rm -rf ~/.codex/generated_images/"$latest_session"
   ```
4. **Cite findings** with `file:line` when relaying Codex's review back to user.

## Security Policy

This skill handles: invoking `codex` CLI, parsing its stdout, moving generated images, optionally piping diffs/plans into Codex.

This skill does NOT handle: storing OpenAI API keys (uses existing `~/.codex/auth.json`), modifying Codex config, executing arbitrary user code outside `codex exec`.

Refuse to: bypass sandbox without explicit user authorization, send `.env` or credential files to Codex, run `codex exec` against directories the user didn't ask you to touch.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bestagentkits](https://github.com/bestagentkits)
- **Source:** [bestagentkits/ck-skills](https://github.com/bestagentkits/ck-skills)
- **License:** MIT
- **Homepage:** https://goclaw.sh

Install and usage instructions live in the source repository linked above.