Skip to main content
skill CX Codex

codex-cli · sugarforever — Claude Code skill: what it does, how to install

Enables an agent to hand off coding, review, and image generation tasks to OpenAI Codex CLI via non-interactive exec commands.

MIT 237 installs ★ 140 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sugarforever/01coder-agent-skills --skill codex-cli -a claude-code
Open on GitHub

What codex-cli does

This skill instructs an agent on how to run codex exec without interactive prompts. It starts by verifying the environment with command -v codex and codex --version. If the CLI is absent, execution stops immediately without simulating Codex output.

Delegated work uses sandbox levels: -s read-only for inspection or critiques and -s workspace-write when file edits are required. Large prompts or logs go through stdin, while images attach via -i. Workflows can also resume previous threads with codex exec resume <session-id>.

When Codex generates images, files land in $CODEX_HOME/generated_images/ or ~/.codex/generated_images/. The skill directs the agent to locate those files, inspect their aspect ratios with sips or file, and copy needed assets into the repo.

What it helps with

  • delegate repository code review to Codex CLI in read-only mode
  • feed screenshots or build logs into Codex CLI using stdin and -i flags
  • resume an earlier Codex execution thread by session id
  • locate and verify dimensions of images produced by Codex

Example prompts for the agent

  • Ask Codex CLI to inspect src/auth.ts and propose a plan in read-only mode
  • Send error.png to Codex CLI using -i and ask for the fix
  • Run codex exec to generate an image and copy it to the assets folder

How to install codex-cli

1Skills CLI (Vercel)

npx skills add sugarforever/01coder-agent-skills --skill codex-cli -a claude-code

2Manually: put the files in place

~/.claude/skills/codex-cli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/codex-cli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about codex-cli

How to install codex-cli in Claude Code?

Run npx skills add sugarforever/01coder-agent-skills --skill codex-cli -a claude-code in your terminal. You can also place the configuration at ~/.claude/skills/codex-cli/SKILL.md.

What is the purpose of codex-cli?

It equips host agents with standard workflows to delegate tasks to OpenAI Codex CLI, covering execution flags, resume commands, and artifact retrieval.

How does codex-cli handle missing binaries?

It checks command -v codex before taking action. If the command fails, the agent reports that Codex CLI is not available rather than faking an answer.

Source text

SKILL.md · MIT
---
name: codex-cli
description: Use when an agent needs to delegate a task to the OpenAI Codex CLI from another agent environment such as Claude Code, OpenClaw, or similar. Covers checking whether Codex CLI is installed, running one-off Codex prompts with `codex exec`, resuming sessions, collecting outputs, attaching images or files as input with `-i`/stdin, and handling Codex image generation including finding and reporting generated image file paths.
---

# Codex CLI

Use this skill when the user asks this agent to talk to Codex, consult Codex, delegate a coding/review/research task to Codex CLI, or ask Codex to generate an image.

The core interface is:

```bash
codex exec "prompt"
```

For automation, prefer non-interactive `codex exec` over interactive `codex`.

## First Check

Before using Codex CLI, verify it is available:

```bash
command -v codex
codex --version
codex exec --help
```

If `codex` is missing, tell the user Codex CLI is not available in this environment and stop. Do not simulate a Codex response.

If `codex exec --help` is available, use it as the source of truth for the installed CLI flags. Codex CLI changes over time.

## One-Off Task Workflow

Use this for normal delegation:

```bash
codex exec -C "$PWD" -s read-only "Review this repository and identify likely bugs"
```

For tasks that may edit files, use the sandbox the user requested or the host agent allows:

```bash
codex exec -C "$PWD" -s workspace-write "Implement the requested change"
```

For a response file:

```bash
codex exec -C "$PWD" -o /tmp/codex-last-message.md "Summarize this project"
```

For machine-readable events:

```bash
codex exec -C "$PWD" --json -o /tmp/codex-last-message.md "Analyze this project"
```

If the prompt is long, pass it via stdin:

```bash
codex exec -C "$PWD" - < /tmp/prompt.txt
```

When using shell commands from another agent, avoid dangerous flags unless the user explicitly asked for them. Prefer `read-only` for review, planning, critique, image generation, and analysis.

## Prompt Shape

For non-trivial tasks, shape the delegated prompt with OpenAI's Codex best-practices structure:

```text
Goal:
Context:
Constraints:
Done when:
```

Keep the prompt scoped to one task. For complex implementation work, ask Codex for a plan first in `read-only` mode, then run a separate write task after the plan is accepted.

## Session Resume

Codex emits a session id in normal startup output and in JSONL events as `thread.started`.

To resume:

```bash
codex exec resume <session-id> "Continue from the previous task"
```

If the installed CLI supports a different resume syntax, follow `codex exec resume --help`.

## Image and File Input

Codex cannot browse or read image files on its own. To let Codex *see* an image, attach it explicitly with `-i`/`--image`. This is the input side; image generation (below) is the output side.

Attach a single image:

```bash
codex exec -C "$PWD" -s read-only -i screenshot.png "Explain the error shown here"
```

Attach multiple images. Both forms work — comma-separated or a repeated flag:

```bash
codex exec -i before.png,after.png "Compare these two UI states"
codex exec -i mock1.png -i mock2.png "Which layout is closer to the spec?"
```

Best practices:

- Put `-i` flags before the prompt text.
- Use common raster formats: PNG (best for screenshots/UI, lossless) or JPEG. Keep images reasonably small; very large images slow the request.
- Combine images with a clear text instruction — the image alone is rarely enough context.
- For visual review/analysis, pair with `-s read-only` so Codex inspects but does not edit.

For **non-image files** there is no attach flag. Two options:

- Let Codex read the file from the workspace: point it at the directory with `-C "$PWD"` and name the file in the prompt (`"Review src/auth.ts"`). Use this for files already in the repo.
- Pipe file contents via stdin. With a prompt also present, stdin is appended to the prompt as a `<stdin>` block:

```bash
codex exec -C "$PWD" "Summarize the attached log" < /tmp/build.log
```

## Image Generation Workflow

Codex can generate images through its built-in image generation tool when asked through `codex exec`.

Example:

```bash
codex exec "Generate a black banana image with aspect ratio 16:9"
```

Important behavior:

- Built-in image generation commonly saves files under `$CODEX_HOME/generated_images/<codex-session-id>/`.
- If `CODEX_HOME` is unset, use `~/.codex/generated_images/<codex-session-id>/`.
- Codex may not print the path in its final response.
- The agent using this skill must proactively locate and report generated image paths after image generation.
- The PNG metadata may not expose the exact image model. Do not claim a specific backend model unless Codex output, CLI logs, or metadata clearly show it.

### Finding Generated Images

After any Codex image-generation request, find the image path before replying.

First extract the Codex session id from output if available. It may look like:

```text
session id: 019e8cbf-5054-7131-9440-ee592f0d8a17
```

Then check:

```bash
ls -l "${CODEX_HOME:-$HOME/.codex}/generated_images/<session-id>"
```

If the session id is not known, list recent generated images:

```bash
find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print
```

When possible, sort by modification time:

```bash
find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print0 \
  | xargs -0 ls -lt
```

If the user requested a project asset, copy or move the selected image into the project after generation if permissions allow. Never leave a project-referenced asset only under `$CODEX_HOME/generated_images`.

### Verifying Aspect Ratio

If the user requested a specific aspect ratio, verify dimensions before answering.

On macOS:

```bash
sips -g pixelWidth -g pixelHeight /path/to/image.png
```

Portable fallback:

```bash
file /path/to/image.png
```

Report actual dimensions and whether they match approximately or exactly. Many generated images use nearest integer dimensions, so a 16:9 request may produce dimensions like `1672 x 941`, which is effectively 16:9 but not mathematically exact.

## Reporting Results

For normal Codex tasks, report:

- command used, summarized if long
- Codex status or final answer
- any files Codex changed, if known
- any limitations, errors, or missing permissions

For image tasks, always report:

- generated image path
- actual dimensions if available
- whether the path is in `$CODEX_HOME` or copied into the project
- whether the exact image model is known or not

Example response:

```text
Codex generated the image here:
/Users/me/.codex/generated_images/019e.../ig_....png

Actual size: 1672 x 941, effectively 16:9.
The output does not expose the exact image backend model, so I cannot verify whether it was gpt-image-2.
```

## Failure Handling

If Codex exits with network, auth, or model refresh errors, report the error plainly and include the relevant stderr lines.

If Codex claims it generated an image but no image file exists under `$CODEX_HOME/generated_images`, say so explicitly and do not invent a path.

If the host agent cannot read `$CODEX_HOME/generated_images`, ask the user to grant access or run:

```bash
find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print0 | xargs -0 ls -lt
```

## Safety Notes

Do not pass secrets to Codex unless the user explicitly asks and understands the risk.

Use `read-only` for consultation. Use `workspace-write` only when Codex is expected to edit files. Avoid `danger-full-access` unless the user explicitly requested it in a controlled environment.

Do not claim Codex performed work solely from its final message. When file changes matter, inspect the filesystem or Git diff after the run.

© sugarforever · MIT · sugarforever/01coder-agent-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

codex-cli by other authors comes first.

codex-cli scarletkc codex-cli is a Claude Code skill for deciding when Codex CLI should review or implement a change. It activates for Codex requests, codex exec, or difficult checks. CX Codex +1 ★ 229repo stars multi-llm-mcp-server reason-machines The multi-llm-mcp-server skill connects Claude Code with Codex CLI and multiple language models. Use it to compare parallel model responses or hand code analysis to Codex. CX Codex +1 107installs codex-artist Sateezg codex-artist is a Claude Code subagent that generates and edits image files through the local Codex CLI. It handles icons, logos, banners, mockups, photos, and asset sets. CX Codex ★ 195repo stars codex giuseppe-trisciuoglio Delegates complex code generation, refactoring, and code reviews to the Codex CLI using GPT-5.3-codex, o3, or o4-mini models. CX Codex +1 3,600installs the-courtroom JustineDaveMagnaye the-courtroom is a Claude Code plugin that sends Claude's implementation plan to Codex CLI for review, then runs it after approval. ★ 8repo stars tavily-research tavily-ai tavily-research — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that runs tvly research, pulls sources from the web, and returns a cited report. Completes in 30–120 seconds. CX Codex +1 25,100installs bailian-cli modelstudioai bailian-cli manages Aliyun Bailian resources through the bl CLI. Useful for running batch inference, querying quotas, and extracting document data with ParseX. CX Codex +1 19,000installs

From the same set18

The whole set →
share-reading share-reading drafts social posts about an article, link or set of notes, with a few takes and the source link kept in every one. CX Codex +1 440installs personal-chinese-writing-style personal-chinese-writing-style enforces one set of Chinese typography rules while the agent writes, translates or edits: quote marks, dash, ellipsis, no stray ASCII punctuation. CX Codex +1 408installs fpl-copilot fpl-copilot analyzes Fantasy Premier League statistics, tracks squad drafts, and builds custom match reports in your agent workspace. CX Codex +1 295installs cover-image cover-image — a skill that builds article covers in hand-drawn style. Picks composition and palette from text or lets you set them manually. CX Codex +1 291installs promote-post promote-post generates teaser tweets for published articles using a post link or local file, hooking readers without giving away summaries. CX Codex +1 277installs claude-session-manager claude-session-manager turns local Claude Code JSONL logs into readable Markdown files with conversation, digest, and tool call history. CX Codex +1 207installs codex-session-manager codex-session-manager — a skill to work with local Codex session transcripts. Exports sessions to structured Markdown with timelines, tool calls, and archived data. CX Codex +1 199installs mining-session-skills mining-session-skills analyzes a completed Claude Code session and proposes which skill to create, update, or reuse so similar work runs faster next time. Works with exported markdown from claude-session-manager. CX Codex +1 196installs

Project sponsors

Companies that keep this analytics open