Claude Code cannot make images. co-codex hands your image requests to OpenAI Codex on your ChatGPT plan and brings every image back into your project. It does the same for any other task you would rather run on your Codex quota than on Claude's.
What the skill gives Claude Code:
- Images from a plain request, in any wording, English or Polish. You do not have to mention Codex: Claude writes the brief, Codex generates the image with gpt-image-2, and the PNG lands in your project.
- Four quality tiers (
draft,standard,high,max) that pick the Codex model and reasoning effort for each task. - Every image a turn produced, including the ones Codex's subagents made, logged with its prompt and real pixel size.
- A read-only second opinion from Codex on a plan, a decision or a code change, when you ask for it, in addition to Claude's own review.
- Mockups before UI code: before Claude builds a new page or screen, it can ask whether Codex should first draw wireframes, mockups or style directions, so you pick a direction from pictures instead of from a finished page.
- Quota and reset times:
limitsshows how much of the five-hour and weekly windows you have used, and a turn that hits the limit stops with the reset time.
You need the Codex CLI, signed in with a ChatGPT plan that includes Codex, and Node.js 20 or newer.
Install as a Claude Code plugin:
/plugin marketplace add JK-G/co-codex
/plugin install co-codex@co-codex
Or as a plain skill: download the ZIP, unpack it and copy the co-codex-main/skills/co-codex folder into ~/.claude/skills/.
For another agent, or to check your setup first: npx -y github:JK-G/co-codex doctor runs the CLI without cloning.
Then ask Claude Code: "generate an image of a red apple".
Moodboards for a LinkedIn template, the first three posts in the chosen style, and a dashboard mockup, for Larkspur, a made-up B2B analytics company. Claude Code wrote the briefs, and Codex generated every image with AI (gpt-image-2) on a ChatGPT Plus plan on 3 November 2026 and reviewed the drafts before the final round. Each image run took 2 to 6 minutes, and the whole set, reviews included, used 5% of the five-hour window. Step by step, with the briefs: business examples.
co-codex grew out of a run of 300 image calls for a pixel-art game: see the case behind it.
Unofficial. Not affiliated with OpenAI or Anthropic.
spawnandsendgive Codex a task, in a new named session or in a window you have open.--waitblocks until Codex answers and prints the answer.--tier draft|standard|high|maxchooses the model and effort from the models your account offers: GPT-6 Luna for drafts, GPT-6.1 Sol for everyday and final work, GPT-6 Astra for the hardest jobs.imageslists or copies every image a turn produced, following subagent threads, and logs each file with its prompt and real pixel size inco-codex-images.jsonl.--names hero.png,icon.pnggives the copies the file names you asked for. Codex says which generation it kept for each name, and the retries go to_rejected/. On a correction turn,--replacekeeps the name for the new image and moves the old one to_rejected/.--networkstarts a session that can reach the network, for installs and deploys. co-codex reports each session's sandbox and warns when a task contains a command such asnpm install,git pushor "deploy to" and the session has no network. Image runs never get this warning.- In a session co-codex started, actions Codex was refused because they needed approval come back as data, with exit code 5, so Claude can tell you what to approve.
limitsshows how much of the five-hour and weekly windows you have used and when they reset. A turn that runs into the limit exits with code 4 and the reset time.limits --estimate 10says what 10 images usually cost, from your past image runs, with parallel runs measured together.--max-used 85sends nothing while a window is more than 85% used.cleanuplists, and with--yesdeletes, old sessions co-codex started that nobody has open.opinionasks Codex for an independent, read-only second opinion on a plan, a decision, a code change or a choice between options (--mode judge), in addition to Claude's own review.doctorchecks Codex, the daemon, your sign-in, the tier models, and every protocol method co-codex relies on, and says which co-codex version you run, which copy is older when the installed plugin and the copy you ran differ, and whether a newer one is out.
- Codex CLI, signed in with a ChatGPT plan that includes Codex. Tested with Codex CLI and app-server 0.166.0.
- Node.js 20 or newer. No npm dependencies.
- Windows, macOS or Linux (see Platform support).
The short path is in the TL;DR. The other ways:
From a shell instead of inside Claude Code: claude plugin marketplace add JK-G/co-codex, then claude plugin install co-codex@co-codex.
As a plain skill with git, without the plugin system:
git clone https://github.com/JK-G/co-codex
cp -r co-codex/skills/co-codex ~/.claude/skills/
On Windows PowerShell, use Copy-Item -Recurse co-codex\skills\co-codex $HOME\.claude\skills\ for the copy.
Then ask Claude Code to "run co-codex doctor", or run it yourself:
node ~/.claude/skills/co-codex/scripts/co-codex.mjs doctor
The CLI is a single Node script, so any agent that can run shell commands can use it. Only SKILL.md is specific to Claude Code.
Subagents and saved workflow scripts, which do not load the skill, call the launcher instead: node ~/.config/co-codex/bin/co-codex.mjs <command>. co-codex writes it on every run, and it runs whatever version Claude Code has installed, so a script keeps working after a plugin update. doctor prints its exact path, and references/subagent-brief.md is a block to paste into their prompts.
In Claude Code, just ask for the image: "generate an image of a red apple", "make me an app icon for a weather app", or in Polish "wygeneruj mi obraz". You do not have to mention Codex. Claude cannot draw by itself, so the skill takes over: it writes the brief, starts a Codex session, waits, copies the PNG into your project (./generated-images unless you name a folder or the project has an assets folder) and checks it before showing you the path. Follow-ups such as "make it bluer" go to the same session with the previous image attached.
Tasks for Codex work the same way: "Have Codex review this module and tell me what it found."
To drive it by hand (co-codex below stands for node <skill dir>/scripts/co-codex.mjs):
co-codex list # Codex sessions open on this machine
co-codex models # what each tier resolves to on your account
co-codex limits # quota used and reset times
co-codex spawn "Generate one game icon: a red apple, flat colours, transparent background." \
--name apple-icon --tier draft --images --wait --out art/icons --json
co-codex send apple-icon "Make it glossy and keep the silhouette." --tier high --images --wait --out art/icons
The first command, as it ran on 2026-10-16 (paths shortened):
{
"name": "apple-icon",
"status": "completed",
"tier": "draft",
"model": "gpt-6-luna",
"effort": "medium",
"answer": "Generated one draft apple icon with a transparent background.",
"images": [{ "path": "~/.codex/generated_images/01a145e3-.../exec-1a46....png", "transparent": true }],
"copied": ["art/icons/exec-1a46....png"],
"limit": null
}send with --tier high ran that one turn on GPT-6.1 Sol with high effort, then switched the session back to GPT-6 Luna. On send, a tier needs --wait (switch back after the turn) or --keep (stay on the new model).
| Tier | Models tried in order | Effort | What --images adds to the task |
|---|---|---|---|
draft |
gpt-6-luna, gpt-5.6-luna | medium | one attempt per image, no regenerating unless unusable |
standard |
gpt-6.1-sol, gpt-6-sol, gpt-5.6-sol | medium | check each result once, regenerate at most once |
high |
gpt-6.1-sol, gpt-6-sol, gpt-5.6-sol | high | check every point of the brief, up to 2 regenerations |
max |
gpt-6-astra, gpt-6.1-sol, gpt-6-sol | high | 2 variants per image, keep the better, up to 3 regenerations |
co-codex takes the first model on the list that your account offers right now, so a tier survives model renames. If a model does not support the tier's effort, it uses the strongest effort the model has below it.
What a tier does not change: Codex's built-in image generation always uses gpt-image-2 (OpenAI docs). The agent model decides how well the image prompt is written, how strictly the result is checked and how often it is redone. Output size does not shrink on draft: a draft run on GPT-6 Luna still returned a 1254x1254 image.
What it costs, per OpenAI's pricing page as of October 2026: per token, GPT-6 Luna costs 1/20 of GPT-6.1 Sol and GPT-6 Astra costs 5 times as much as Sol. Image generations use included limits about 3 to 5 times faster than similar turns without images.
Tiers are plain config. Change them or add your own in ~/.config/co-codex/config.json (all projects) or .co-codex.json (one project); details in references/tiers.md.
Raw art from that run, 15-16 October 2026, without retouching.
A 2D pixel-art game prototype needed character sprite sheets, armour and weapon sets, props, portraits and UI art. Claude Code wrote the task pack (style guide, specs, one prompt file per task) and fitted the finished art into the game. Codex generated the images with gpt-image-2 on a ChatGPT Plus plan: 222 image calls between one afternoon and the next morning. Each problem we hit became part of co-codex:
- Finding the right file. Picking the newest file in
~/.codex/generated_imagesbreaks once subagents generate in parallel. co-codex reads each image's ownsavedPathfrom the turn and follows subagent threads. One turn of that run produced 74 images across three subagents, andimages --outcopied all of them with their prompts. - Batches. One sequential art session filled 390k of its 475k-token context.
--subagentsasks Codex to split a batch across its own subagents, each with its own files. - Limits. On Plus, about 78 image calls in roughly an hour used up the five-hour window, and the next turns failed. co-codex now exits with code 4 and prints the reset time,
limitsshows the windows before you start, andimagesstill collects what finished. - Consistency. Redressing a finished base sheet, attached as the edit target, kept all eight figures in place. The brief templates make you name each reference image's role.
- Transparency. Asked for a real transparent background, gpt-image-2 in Codex returned images with an alpha channel.
UI mockups, moodboards and social media templates follow the same loop. Explore several variants on draft, pick one, then finalize it on high with the pick attached through --ref. references/image-briefs.md has brief templates for sprite sheets, UI mockups, moodboards, social media templates, ad creatives in several sizes, and icon sets.
Claude can ask Codex to review a plan, a decision, a design or a code change. Codex is a different model family, so it tends to miss different things than Claude does. It is always an extra layer: Claude still does its own review, and you decide.
- It runs only when you ask ("get a second opinion from Codex on this plan", "zapytaj Codexa o zdanie"), or when your CLAUDE.md or Claude's memory says to do it for that kind of work. The second time you ask on similar work, Claude offers to save it as a standing preference.
- Codex works in a fresh read-only session. It can read the project and check claims against the code, but it cannot change anything. When the material is about something else,
--no-projecttells it not to search the folder. - By default Codex does not see Claude's conclusion, so its view is not anchored to it.
--mode challengesends Claude's position and asks Codex to refute it. - Plans and decisions come back as a verdict (
sound,sound-with-changesorrethink), a confidence level, ranked concerns with evidence, alternatives and questions. Code changes go through Codex's built-in reviewer:--difffor uncommitted changes,--base <branch>, or--commit <sha>. Choices between options (--mode judge) come back as a winner, every option ranked with reasons and evidence, and what must change in the winner. - Designs can be images. Pass the PNG files with
--file(with--mode judgeto rank them) and Codex opens them: on three dashboard mockups it found a chart that contradicted the KPI cards, and on three moodboards it measured a 2.99:1 text contrast by sampling pixels. Both runs are in the business examples, with a review of a pricing plan. - Claude then reports where both agree, what Codex found that Claude missed, and where Claude disagrees with Codex and why.
A run from 2026-10-16 on a deliberately flawed migration plan (trimmed):
co-codex opinion "Goal: rename users.email to users.login_email in a production Postgres database, zero downtime.
Plan: 1. Deploy the app version that uses login_email. 2. ALTER TABLE users RENAME COLUMN email TO login_email.
3. No rollback plan needed, a rename is instant." --on "database migration plan"
Verdict: rethink (confidence high)
The proposed ordering breaks live requests and does not meet zero-downtime requirements.
Concerns:
[high] Step 1 deploys code against a column that does not exist yet.
[high] A fast metadata operation can still cause an outage through locking.
evidence: PostgreSQL specifies ACCESS EXCLUSIVE as the default ALTER TABLE lock ...
[medium] Execution speed does not eliminate the need for rollback and validation.
Alternatives:
- Use expand-and-contract: add a nullable login_email, ... finally remove email after every old consumer is retired.
On a small diff that changed a bill-splitting function to round every share, opinion --diff returned a P1 finding with the file and line: split(10, 3) now returns [3, 3, 3], which no longer adds up to the total.
| Command | What it does |
|---|---|
list [--all] |
Open sessions with status, name and model; --all adds saved sessions of this project |
spawn <task> --name <name> |
Start a named session with the task |
send <session> <task> |
Queue a message; it runs after the session's current turn |
wait <session> [--message id] |
Wait for a turn and print its answer: the message send queued, else the last queued one, else the latest turn |
read <session> [--turns n] |
Print recent answers |
stop <session> |
Interrupt the running turn |
images <session> [--turns n] [--out dir] |
List or copy the images of recent turns, subagents included |
opinion <text> [--on what] [--mode challenge|judge] [--file path] [--no-project] |
Read-only second opinion on a plan, decision, design or text, or a ranked choice between options |
opinion --diff | --base <branch> | --commit <sha> |
Codex's built-in code review of a change |
cleanup [--older-than 2d] [--name-prefix p] [--yes] |
Old sessions co-codex started in this project that no window has open: listed, or deleted with --yes |
models |
Models on your account and how each tier resolves |
limits [--estimate n] [--tier t] |
Usage of the current windows and reset times, or the expected share for n images |
doctor |
Check the setup and the protocol, show Codex's sandbox settings next to co-codex's, the co-codex version, the launcher path and whether an update is out |
init [--write] |
Print the AGENTS.md note for Codex, or append it to ./AGENTS.md |
Options for spawn and send: --tier, --model, --effort, --images, --subagents, --ref <image> (repeatable), --wait, --timeout <s>, --out <dir>, --names <list>, --replace, --retries <0-3>, --max-used <pct>, --json. spawn also takes --cwd, --sandbox, --network and --fast; the sandbox is fixed per session, so send accepts only the session's own --sandbox or --network. wait takes --out, --names and --replace too. <session> is a session id, an exact name, or open for the one Codex window open in the current project. Pass - as the task to read it from stdin.
Exit codes: 0 answered, 1 co-codex error, 2 timed out (Codex keeps working, run wait), 3 turn failed or was interrupted, 4 usage limit reached or --max-used sent nothing, 5 answered, but some actions were refused because they need approval.
--names a.png,b.png(with--imagesand--out) asks Codex to make the images in that order and to end its answer with a line such asKEEP: a.png=1, b.png=3: the position of the kept image among all generations of the turn, retries included. co-codex copies the kept images under those names and the others to<out>/_rejected/. Without a usableKEEP:line it maps the images in order when the count matches, and says so; otherwise it keeps the item-id names. It never overwrites a different file: a taken name becomesa-2.png, or with--replacethe name gets the new image and the old file moves to<out>/_rejected/a-replaced.png. Not with--subagents, whose images are numbered in their own threads; images from subagents Codex starts on its own go to_rejected/too.- gpt-image-2 picks its own output size (seen: 1536x1024 for most landscape images, 1254x1254 square, 1024x1536 portrait, 1122x1402 for 4:5, 941x1672 for 9:16, and wide ones such as 1641x958), whatever the brief asks. Every image in the JSON results and the log carries its real
widthandheight. co-codex has no image library, so it does not resize; use your project's tools when exact pixels matter. Codex is told not to regenerate an image only for its size or for small colour drift from the given hex codes, and--retries 0or1limits regenerations further when you measure and fix the images yourself. - Runs with
--wait, and everyopinionthat finishes, reportusage: the five-hour and weekly windows before and after the turn. Opinions are not logged, because the log is for image estimates. Each completed--imagesrun adds a line to~/.config/co-codex/usage.jsonl($XDG_CONFIG_HOMErespected), andlimits --estimate <n>divides the summed window use of those runs by their summed image count. The windows count whole percents, so one small run often reads 0; pooling the runs keeps the ones that moved the window. Runs that overlap in time are measured together, from the first one's start to the last one's end, so parallel runs do not count each other's use. Other Codex use at the same time still counts, so treat the estimate as rough. --max-used <pct>(ormaxUsedPercentin the config) makesspawn,sendandopinionsend nothing while the five-hour or weekly window is above that share. They exit with code 4 and the reset time.--jsonresults also carrycontext: the session's tokens against its context window. A long session close to full is better replaced by a fresh one.
co-codex works without a config file. To change defaults, create ~/.config/co-codex/config.json or a .co-codex.json in the project; the project file wins, and only the fields you set change:
{
"defaultTier": "standard",
"spawn": { "sandbox": "workspace-write", "approvalPolicy": "never" },
"tiers": { "draft": { "effort": "low" } },
"maxUsedPercent": 85
}templates/co-codex.config.json lists every setting.
- Every task spends the Codex quota of your ChatGPT plan. The skill tells Claude to say so each time it sends work, to check
limitsbefore a batch, and to pass a quota ceiling you set as--max-used. - Spawned sessions run in the
workspace-writesandbox without network access and with approval prompts off: nobody watches them, so a blocked command goes back to Codex instead of waiting forever.--networkadds network access for one session. Set"sandbox": "danger-full-access"in your config if you want spawned sessions to run without the sandbox. - Which sandbox for which task:
read-onlyfor images and questions,workspace-writefor code edits,--network(ordanger-full-accessif you allow it) for installs, deploys and anything else online. - co-codex never answers approval prompts. It prints a line starting with
!and leaves the decision to the person at the Codex window. When a spawned session was refused an action that needed approval (inviting someone to a site, for example), co-codex lists it and exits with code 5, so you can opencodex resume <name> -a on-requestand let Codex retry it there, approving each step. If the retry needs the network, add-c sandbox_workspace_write.network_access=true(or-s danger-full-access). In a window you hold, a decline was your own choice: co-codex reports it and exits 0. cleanuponly touches sessions co-codex started, in the current project, that no window has open, and deletes nothing without--yes.- co-codex cannot see which Codex features (such as Sites) your account has. Asking Codex in a read-only session gives its own claim, not a verified answer.
- It refuses to send to one of your saved sessions that no window has open, because nobody could answer that session's prompts.
init --writeappends a short note toAGENTS.md, and the skill asks before running it.
Every Codex client on a machine (terminal, desktop app, IDE extension) talks to one local app-server daemon. co-codex starts codex app-server proxy, which connects to the daemon's socket, and speaks JSON-RPC over WebSocket frames on the proxy's stdin and stdout. That makes it one more client of the same daemon: it can queue a message on a session your terminal holds, and you watch the turn happen in your window. If the daemon is not running, co-codex starts it.
OpenAI marks the app-server protocol as experimental, and Codex ships often. doctor exports the protocol schema of the installed Codex and checks every method co-codex uses, so a breaking change shows up as a clear message.
- Windows: tested live on Windows 11 with Codex CLI 0.166.0 (3 November 2026).
- macOS and Linux: the same code. CI runs the full test suite against a mock Codex on Ubuntu, macOS and Windows. It has not yet been run against a real Codex on macOS or Linux, so reports are welcome.
Paths are compared case-insensitively on Windows and macOS and through realpath everywhere. If codex is not on your PATH, set CO_CODEX_BIN to the executable. More in references/troubleshooting.md.
If you mainly want Codex to review code from inside Claude Code, look at OpenAI's official plugin openai/codex-plugin-cc first. co-codex is built around handing whole tasks to Codex, choosing the model per task, and getting images back.
npm testruns 107 unit and end-to-end tests against a mock Codex. CI runs them on Ubuntu, macOS and Windows with Node 20, 22 and 24.claude plugin eval . --no-publishruns the trigger evals inevals/: 11 requests that must load the skill (image requests in English and Polish that never name Codex, a task for Codex, two requests for a second opinion, two new pages to build in HTML and CSS) and 6 that must not (image-processing code, a question about images on a website, a plan review and a code review that do not mention Codex, a general question, a small CSS fix). On 2026-10-16 the first 14 passed twice each with Claude Code 2.1.301, and on 2026-10-24 the three UI evals added in 0.4.0 passed twice each with Claude Code 2.1.310. A full run cost about $4 of Claude usage.
MIT. Issues and pull requests are welcome; please include your OS and the output of doctor.

