--- slug: "codex" source_type: "skill_md" source_url: "https://cdn.jsdelivr.net/gh/oil-oil/codex@main/SKILL.md" repo: "https://github.com/oil-oil/codex" source_file: "SKILL.md" branch: "main" --- --- name: codex description: Delegate coding and image-generation tasks to Codex CLI for execution. Only invoke this skill when the user explicitly asks to use Codex — e.g., "用 codex 来做", "让 codex 执行", "ask codex to...", "codex 帮我写", "让 codex 生成/画一张图". Do not proactively delegate to Codex for requests the user didn't specifically ask Codex to handle. Codex is an autonomous agent with the same tools as Claude (file read/write, grep, bash) plus a built-in image_gen tool — it explores the codebase and implements changes on its own. Codex is strong at execution and writing code but comparatively weak at understanding ambiguous problems and high-level design, so Claude's job is to do the understanding and design first, then hand Codex a clear, well-scoped task to execute. --- ## What Codex is good and bad at Codex is an autonomous agent with the same tools as Claude (file read/write, grep, bash) plus a built-in image generator. Match the work to its profile: - **Strong at execution and coding.** Once a task is well-defined, it implements quickly and competently — writing code, refactoring, applying mechanical changes across many files, wiring boilerplate, and generating images from a clear brief. - **Weaker at understanding and design.** It is comparatively poor at disambiguating vague requirements, weighing architectural trade-offs, or judging what the *right* solution is. It tends to take the prompt literally and run with the first plausible interpretation. So **Claude owns the thinking; Codex owns the doing.** Before delegating, do the understanding and design yourself: figure out what's actually needed, make the key decisions, and hand Codex a clear, well-scoped task with explicit constraints. Don't hand it an open-ended "figure out the best approach" — decide the approach, then let it execute. ## Critical rules - Use the bundled shell script rather than calling `codex` CLI directly — the script handles output capture, session tracking, and real-time progress streaming correctly. - Run the script once per task. If it succeeds (exit code 0), read the output file and proceed. Don't re-run just because the output seems short — Codex often makes changes quietly without narrating every step. - Quote file paths containing `[`, `]`, spaces, or special characters (e.g. `--file "src/app/[locale]/page.tsx"`). Without quotes, zsh treats `[...]` as a glob pattern and fails with "no matches found". - **Keep the task prompt to the goal and constraints, not the implementation steps.** Aim for under ~500 words. Codex has the same tools as Claude and will explore the codebase itself — spelling out every file to change or every step tends to constrain it rather than help. - **Don't paste file contents into the prompt.** Use `--file` to point Codex to key files — it reads them directly at their current version. Pasting contents wastes tokens and risks passing stale code. - **Don't mention this skill or its configuration in the prompt.** Codex doesn't need to know about it. ## How to call the script ### Linux/macOS (bash) The script path is: ``` ~/.claude/skills/codex/scripts/ask_codex.sh ``` Minimal invocation: ```bash ~/.claude/skills/codex/scripts/ask_codex.sh "Your request in natural language" ``` With file context: ```bash ~/.claude/skills/codex/scripts/ask_codex.sh "Refactor these components to use the new API" \ --file src/components/UserList.tsx \ --file src/components/UserDetail.tsx ``` Multi-turn conversation (continue a previous session): ```bash ~/.claude/skills/codex/scripts/ask_codex.sh "Also add retry logic with exponential backoff" \ --session ``` ### Windows (PowerShell) The script path is: ``` ~/.claude/skills/codex/scripts/ask_codex.ps1 ``` Minimal invocation: ```powershell & ~/.claude/skills/codex/scripts/ask_codex.ps1 "Your request in natural language" ``` With file context: ```powershell & ~/.claude/skills/codex/scripts/ask_codex.ps1 "Refactor these components to use the new API" ` -f src/components/UserList.tsx ` -f src/components/UserDetail.tsx ``` Multi-turn conversation (continue a previous session): ```powershell & ~/.claude/skills/codex/scripts/ask_codex.ps1 "Also add retry logic with exponential backoff" ` -Session ``` ### Output format The script prints on success: ``` session_id= output_path= elapsed=s ``` Read the file at `output_path` to get Codex's response. Save `session_id` if you plan follow-up calls. The response file is structured for fast scanning: - `## Summary` — Codex's final message (what it concluded or did), surfaced first so it isn't buried under the execution log. - `## Details` — execution trace (commands run, files written/patched) plus any intermediate narration. Pure read/search commands are filtered out; the section is omitted entirely when there's nothing to show (e.g. a read-only discussion). - A footer line with run metrics, e.g. `elapsed 16s · 1 cmds · tokens in=53435 (cached 37504) out=125 reasoning=0`. ## Workflow 1. Understand the problem: read the key files to grasp what's broken or needed. Focus on being able to describe the problem and goal clearly — you don't need to design the full solution or enumerate every affected file. Codex will explore the codebase itself. 2. Run the script with a focused task description: the goal, key constraints, and any non-obvious context. For discussion or analysis without changes, use `--read-only`. 3. Pass 1-4 entry-point files with `--file` as starting hints. Codex has the same tools as Claude and will discover related files on its own — no need to enumerate everything upfront. 4. Read the output — Codex executes changes and reports what it did. 5. Review the changes in your workspace. For multi-step projects, use `--session ` to continue with full conversation history. For independent parallel tasks, use the Task tool with `run_in_background: true`. ## Generating images Codex has a built-in image generator — the `image_gen` tool (callable name `image_gen.imagegen`), backed by OpenAI's gpt-image model. (Codex's own tool schema does not expose the exact model id, so don't rely on a specific version.) You invoke it like any other task: just ask Codex, in plain language, to generate the image. There is no extra script flag. - **Prompt is the only knob.** The tool exposes a single input: a natural-language `prompt`. There are **no structured parameters** for size, aspect ratio, quality, output format, image count, or transparent background. Put all of that art direction *into the prompt text itself* (e.g. "a square logo…", "on a transparent background", "photorealistic, soft morning light"). Editing an attached reference image is mentioned by the tool but is not exposed as a separate parameter. - **Output goes outside the workspace.** Generated images are always written as **PNG** to `~/.codex/generated_images//ig_.png` — *not* into `--workspace`. Output is large and roughly square (≈1254×1254 observed); you cannot set exact pixel dimensions via a parameter, only describe them in the prompt. - **Make Codex hand you the file.** The cleanest pattern is to tell Codex, in the same prompt, to copy the generated PNG to a known path and report it — e.g. "after generating, copy the PNG to ./out/logo.png and print its absolute path." Codex has bash access and will do this. Otherwise, the result is the newest file under `~/.codex/generated_images/`. - **Use the default (workspace-write) run.** Generation is confirmed working in the normal run; don't pair it with `--read-only`. It needs network access, and is subject to the image tool's content policy. Exact rate limits and max resolution are not exposed. ## Failure handling - **`script: tcgetattr/ioctl: Operation not supported on socket`** (exit code 1): the `script` command probes stdin with `tcgetattr` at startup and only tolerates `ENOTTY`/`ENODEV` errors. When Claude Code connects stdin via a socketpair, the kernel returns `EOPNOTSUPP` instead — which `script` doesn't whitelist, so it exits immediately. The script detects this automatically by probing with `script -q /dev/null true` first and falls back to direct execution. Update to the latest version if you still see this error. - **Exit code 137**: the task was interrupted (user cancel or OOM). Not a Codex bug — retry or break the task into smaller pieces. - **`ERROR codex_core::codex: failed to load skill ...`** in stderr: one of Codex's own installed skills has a broken YAML file. This warning is harmless and doesn't affect the current task — ignore it. - **`(no response from codex)`** in the output file: Codex ran but produced no readable output. Check stderr for clues; the task may have hit a sandbox restriction. ## Options - `--workspace ` — Target workspace directory (defaults to current directory). - `--file ` — Point CodeX to key entry-point files (repeatable, workspace-relative or absolute). Don't duplicate their contents in the prompt. - `--session ` — Resume a previous session for multi-turn conversation. - `--model ` — Override model (default: uses Codex config). - `--reasoning ` — Reasoning effort: `low`, `medium`, `high` (default: `medium`). Use `high` for code review, debugging, complex refactoring, or root cause analysis. - `--sandbox ` — Override sandbox policy (default: workspace-write via full-auto). - `--read-only` — Read-only mode for pure discussion/analysis, no file changes. - `--notify` — Fire a desktop notification when a long run finishes (macOS/Linux via the bash script, Windows via PowerShell). Opt-in: also enabled by `CODEX_NOTIFY=1`, and only fires past a minimum duration (`CODEX_NOTIFY_MIN_SECONDS`, default 30) so quick tasks stay quiet. Useful when kicking off a long task and stepping away. ## Resume mode limitations When using `--session` to resume a previous conversation, note these limitations: - **Must run in a git repository** — The `codex exec resume` command requires a git-trusted directory. It does not support `--skip-git-repo-check`. - **Limited options** — Resume mode only supports `-c/--config` and `--last`. The following options are **not supported** in resume mode: - `--sandbox` - `--full-auto` - `--read-only` - `--model` - `--workspace` (resumes in the original session's context) - **Text output only** — Resume mode returns plain text instead of JSON-structured output.