Skip to content
Back to search

codex-bridge

SkillWorks with CodexGitHub

Image generation (gpt-image-2) and GPT-5 subagents for Claude Code — through the Codex CLI login you already have. No OpenAI API key.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sateezg-codex-bridge/badge.svg)](/listings/sateezg-codex-bridge)

HTML

<a href="/listings/sateezg-codex-bridge"><img src="/api/listings/sateezg-codex-bridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites**

| | | | :-- | :-- | | Codex CLI | `npm i -g @openai/codex` or `brew install codex` | | Logged in | `codex login` → verify with `codex login status` (should say *Logged in using ChatGPT*) | | ChatGPT plan | Plus, Pro, or Team | | Claude Code | any current version |

**Then:**

/plugin marketplace add Sateezg/codex-bridge
/plugin install codex-bridge@codex-bridge

Run `/reload-plugins` if Claude Code asks you to.

<details> <summary>Other install methods</summary>

Try it for one session, no install:

git clone https://github.com/Sateezg/codex-bridge.git
claude --plugin-dir ./codex-bridge

Auto-load from your skills directory:

git clone https://github.com/Sateezg/codex-bridge.git ~/.claude/skills/codex-bridge
chmod +x ~/.claude/skills/codex-bridge/bin/*

Loads as `codex-bridge@skills-dir` on your next session.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 36 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "codex-bridge",
  3. "metadata": {
  4. "description": "Image generation and GPT-5 subagents for Claude Code, powered by your existing Codex CLI login."
  5. },
  6. "owner": {
  7. "name": "Sateezg",
  8. "url": "https://github.com/Sateezg"
  9. },
  10. "plugins": [
  11. {
  12. "name": "codex-bridge",
  13. "source": "./",
  14. "description": "Give Claude Code image generation (gpt-image-2) and a team of GPT-5 subagents for review, debugging, and bulk implementation - all through your existing Codex CLI ChatGPT login. Heavy work runs on your ChatGPT quota instead of your Claude context. No OpenAI API key required.",
  15. "version": "1.1.2",
  16. "author": {
  17. "name": "Sateezg",
  18. "url": "https://github.com/Sateezg"
  19. },
  20. "homepage": "https://github.com/Sateezg/codex-bridge",
  21. "repository": "https://github.com/Sateezg/codex-bridge",
  22. "license": "MIT",
  23. "category": "productivity",
  24. "keywords": [
  25. "codex",
  26. "image-generation",
  27. "gpt-image-2",
  28. "gpt-5",
  29. "subagent",
  30. "openai",
  31. "code-review",
  32. "token-savings"
  33. ]
  34. }
  35. ]
  36. }
README.md · README · 251 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # codex-bridge
  3. **Give Claude Code image generation and a team of GPT-5 subagents — using the Codex CLI login you already have.**
  4. [![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757)](https://code.claude.com/docs/en/plugins)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  6. [![No API key required](https://img.shields.io/badge/OpenAI%20API%20key-not%20required-brightgreen)](#why-no-api-key)
  7. </div>
  8. Claude Code can't generate images, and everything it does runs on your Claude quota. The Codex CLI can generate images with **gpt-image-2**, and runs on your **ChatGPT plan** — a completely separate budget. This plugin bridges the two.
  9. Two things you get:
  10. **1. Claude can produce images.** Ask for an icon, a mockup, a hero image, a full favicon set — Claude writes the prompt, drives gpt-image-2 through Codex, then *looks at the result* and regenerates if it missed.
  11. **2. Claude can delegate to GPT-5.** Four Codex-powered subagents handle review, debugging, bulk implementation, and image work. Claude stays the orchestrator: it scopes the task, Codex does the volume, Claude verifies the result. Heavy work runs on your ChatGPT quota and its intermediate output never enters your Claude context.
  12. <a id="why-no-api-key"></a>
  13. > **No OpenAI API key.** Everything routes through `codex login`, so it bills against your ChatGPT plan rather than API credits.
  14. ## Demo
  15. <div align="center">
  16. ![Claude generating an icon through Codex, in a real terminal](assets/demo.gif)
  17. </div>
  18. One style contract across a set. Each sibling was generated with an earlier icon passed as `--ref`, so the palette, stroke weight, glyph scale and margins carry over instead of being re-described and re-interpreted every time:
  19. <div align="center">
  20. <img src="assets/icon-rocket.png" width="170" alt="Paper rocket icon"> <img src="assets/icon-gear.png" width="170" alt="Settings gear icon"> <img src="assets/icon-shield.png" width="170" alt="Shield with checkmark icon">
  21. </div>
  22. > **Every image in this repository was generated by this plugin** — the GIF above, these icons, and the social preview card. The exact commands and the VHS recording script are in [`assets/README.md`](assets/README.md), so you can reproduce all of it.
  23. ## Contents
  24. - [Demo](#demo) · [Install](#install) · [Quickstart](#quickstart) · [What's inside](#whats-inside)
  25. - [Feature 1 — images](#feature-1--images) · [Feature 2 — GPT-5 subagents](#feature-2--gpt-5-subagents)
  26. - [How it works](#how-it-works) · [Limitations](#limitations) · [Troubleshooting](#troubleshooting)
  27. ## Install
  28. **Prerequisites**
  29. | | |
  30. | :-- | :-- |
  31. | Codex CLI | `npm i -g @openai/codex` or `brew install codex` |
  32. | Logged in | `codex login` → verify with `codex login status` (should say *Logged in using ChatGPT*) |
  33. | ChatGPT plan | Plus, Pro, or Team |
  34. | Claude Code | any current version |
  35. **Then:**
  36. ```
  37. /plugin marketplace add Sateezg/codex-bridge
  38. /plugin install codex-bridge@codex-bridge
  39. ```
  40. Run `/reload-plugins` if Claude Code asks you to.
  41. <details>
  42. <summary>Other install methods</summary>
  43. Try it for one session, no install:
  44. ```bash
  45. git clone https://github.com/Sateezg/codex-bridge.git
  46. claude --plugin-dir ./codex-bridge
  47. ```
  48. Auto-load from your skills directory:
  49. ```bash
  50. git clone https://github.com/Sateezg/codex-bridge.git ~/.claude/skills/codex-bridge
  51. chmod +x ~/.claude/skills/codex-bridge/bin/*
  52. ```
  53. Loads as `codex-bridge@skills-dir` on your next session.
  54. </details>
  55. ## Quickstart
  56. Nothing to configure. Just ask in plain language:
  57. ```
  58. generate a hero image for the landing page, save it in assets/
  59. make the sky in assets/hero.png sunset orange, keep everything else
  60. set up favicons and an OG card for this project
  61. review my changes before I commit
  62. ask codex why this test only fails under --parallel
  63. rename useSession to useAuthSession across the whole repo
  64. ```
  65. The last one is the interesting case. Claude notices it's mechanical work across many files and offers the split before starting:
  66. > This touches 34 files with the same change. I can hand the edits to Codex — runs on your ChatGPT quota and keeps 34 file dumps out of this context — then review its diff here. Want me to?
  67. ## What's inside
  68. **Skills** — Claude picks these up automatically; you can also call them as `/codex-bridge:<name>`.
  69. | Skill | Fires when |
  70. | :-- | :-- |
  71. | `generate-image` | a task needs a new image that doesn't exist yet |
  72. | `edit-image` | you point at an image file and ask to change or restyle it |
  73. | `asset-set` | favicons, app icons, OG cards, or a matching icon family |
  74. | `ask-codex` | you want GPT-5's take on one question about this repo |
  75. | `codex-review` | "review my changes" — diff, branch, or module |
  76. | `codex-delegate` | a task is big or repetitive enough that delegating saves you tokens |
  77. **Subagents** — Claude launches these itself, or you can name them.
  78. | Subagent | Does | Can write files? |
  79. | :-- | :-- | :-- |
  80. | `codex-artist` | images, icon sets, style-matched asset families | images only |
  81. | `codex-reviewer` | review a diff, then verifies every finding against the code | no |
  82. | `codex-debugger` | root-cause a failure, proposes a patch | no |
  83. | `codex-implementer` | bulk mechanical edits and scaffolding | **yes** — after you agree |
  84. | `codex-second-opinion` | general independent opinion on an approach | no |
  85. **Executables** — on your `PATH` while the plugin is enabled, and usable straight from a shell.
  86. | | |
  87. | :-- | :-- |
  88. | `codex-imagegen` | generate or edit an image; prints the output path |
  89. | `codex-run` | run any task on Codex; prints only its final answer |
  90. ## Feature 1 — images
  91. ```bash
  92. codex-imagegen "flat vector rocket icon, #2563EB on white, 2px stroke, minimal" ./rocket.png
  93. codex-imagegen "change the sky to sunset orange, keep everything else identical" ./out.png --ref ./hero.png
  94. codex-imagegen "settings gear, same style as the reference" ./settings.png --ref ./home.png
  95. ```
  96. | Option | |
  97. | :-- | :-- |
  98. | `--size WxH` | `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`, … — see note below |
  99. | `--ref <file>` | source or style reference, repeatable up to 4 — turns the call into an edit |
  100. | `--model <name>` | model override |
  101. | `--timeout <sec>` | default 600 |
  102. A custom size is only accepted if all of these hold: longest edge ≤ 3840px, both edges multiples of 16, long-to-short ratio ≤ 3:1, total pixels between 655,360 and 8,294,400. Square is fastest. For anything outside that — favicons, a 1200×630 OG card — generate a large master and resample locally.
  103. The wrapper prints the path it actually wrote. Codex is instructed not to overwrite existing assets, so it occasionally saves `out-v2.png`; the wrapper detects that (and the `~/.codex/generated_images/<session>/` default location) and reports the real path.
  104. What makes this better than pasting prompts into a chat window: the skills teach Claude to pull your **actual palette** out of `tailwind.config.*` or your design tokens, to reuse one style contract across a whole set so the assets match, to derive size variants with ImageMagick instead of regenerating, and to **open the PNG and check it** before telling you it's done.
  105. ## Feature 2 — GPT-5 subagents
  106. The point isn't "Claude can also call GPT-5". It's the division of labour: **Claude scopes and verifies, Codex does the volume.**
  107. ```
  108. you ──▶ Claude scopes the work, writes the brief, reviews the result
  109. │
  110. ▼
  111. codex-run ──▶ Codex CLI ──▶ GPT-5 / gpt-image-2
  112. (your ChatGPT quota)
  113. ```
  114. Because Codex runs as a separate process, its intermediate output — the 40 files it read, the search results, the generated boilerplate — never enters your Claude context. You pay Claude tokens only for the brief and the review.
  115. **What gets delegated**, per the `codex-delegate` rubric: mechanical edits across many files, bulk generation, exhaustive repo sweeps, all image work, and self-contained subtasks. **What doesn't:** architecture calls, ambiguous requirements, anything needing the conversation history, and small edits — round-tripping a two-line fix costs *more*, not less.
  116. Every subagent follows the same contract: read-only by default, verify before reporting, and never claim success on unverified work. Only `codex-implementer` writes to your files, only after you've agreed, and only with a clean working tree so its changes land as a reviewable diff.
  117. Straight from a shell:
  118. ```bash
  119. codex-run -C . "which module owns rate limiting? name the file"
  120. codex-run -C . -r "now show me the minimal patch" # -r continues the session
  121. git diff main...HEAD | codex-run -C . --timeout 1200 - # pipe a diff in
  122. ```
  123. | Option | |
  124. | :-- | :-- |
  125. | `-C, --cd <dir>` | working directory (default: cwd) |
  126. | `-s, --sandbox <mode>` | `read-only` (default), `workspace-write`, `danger-full-access` |
  127. | `-m, --model <name>` | e.g. `gpt-5-codex` |
  128. | `-r, --resume` | continue the previous session instead of starting fresh |
  129. | `--schema <file>` | constrain the answer to a JSON Schema |
  130. | `--raw` | also dump Codex's event log to stderr |
  131. | `--timeout <sec>` | default 900 |
  132. ## How it works
  133. Both wrappers shell out to `codex exec`, Codex's non-interactive mode.
  134. **Images** run in a `workspace-write` sandbox scoped to the output directory:
  135. ```bash
  136. codex exec -C <outdir> -s workspace-write --skip-git-repo-check [-i <ref>...] \
  137. "Use the \$imagegen image generation tool to ... save to ./<file>.png ..."
  138. ```
  139. `$imagegen` is Codex's built-in image skill; it calls gpt-image-2 with your ChatGPT credentials and writes the PNG into the working directory. The wrapper verifies the file landed — falling back to `$CODEX_HOME/generated_images/` if Codex saved it there instead — and prints the absolute path so Claude can read the image back.
  140. **Text tasks** capture the final message with `-o` instead of scraping the event log, so subagents get a clean answer rather than a transcript:
  141. ```bash
  142. codex exec -C <dir> -s read-only --skip-git-repo-check -o <tmpfile> "<task>"
  143. ```
  144. Both fail fast and loudly: a missing `codex` binary or a logged-out session exits `1` with an actionable message rather than hanging. Timeouts exit `124`. Both handle BSD and GNU `stat`, and degrade gracefully when `timeout`/`gtimeout` isn't installed.
  145. ## Limitations
  146. - **Quota, not free.** Image turns burn ChatGPT plan quota roughly 3–5× faster than text turns. Set `OPENAI_API_KEY` and Codex switches to API billing instead.
  147. - **Transparency takes two steps.** The default path can't emit alpha, so the skills generate on a flat `#00FF00` key and strip it with the `remove_chroma_key.py` helper Codex already ships. True native transparency needs Codex's CLI fallback plus an `OPENAI_API_KEY`; the skills surface that as a choice rather than switching silently.
  148. - **Slow.** 1–4 minutes per image; a repo-wide Codex task can take 10+ minutes. Skills set long Bash timeouts accordingly.
  149. - **Codex is blind to your conversation.** Every brief has to stand alone. This is exactly why the subagents verify before reporting.
  150. - **macOS and Linux.** Not tested on Windows.
  151. ## Troubleshooting
  152. | Symptom | Fix |
  153. | :-- | :-- |
  154. | `codex CLI not found on PATH` | install Codex CLI, then reopen your shell |
  155. | `codex is not logged in` | run `codex login`; confirm with `codex login status` |
  156. | `Operation not permitted` from codex | ownership on `~/.codex` — `sudo chown -R $(whoami) ~/.codex` |
  157. | Got `out-v2.png` instead of `out.png` | expected — Codex won't overwrite; use the path the wrapper printed |
  158. | Image lands somewhere unexpected | the wrapper also checks `$CODEX_HOME/generated_images/<session>/`; pass an absolute output path |
  159. | `failed to load models cache: missing field base_instructions` | harmless Codex cache warning; clear it with `rm -rf ~/.codex/cache` if it persists |
  160. | Codex output full of MCP/hook errors | your Codex config, not this plugin — the wrapper ignores them. Prune unused MCP servers in `~/.codex/config.toml` to speed runs up |
  161. | Skills don't show up | `/reload-plugins`, then `/help` → Custom commands |
  162. | Wrapper "permission denied" | `chmod +x ~/.claude/skills/codex-bridge/bin/*` |
  163. | Everything times out | raise `--timeout`; check `codex exec -C . -s read-only "say hi"` works standalone |
  164. ## Contributing
  165. Issues and PRs welcome.
  166. ```bash
  167. claude plugin validate .
  168. bash -n bin/codex-imagegen && bash -n bin/codex-run
  169. ```
  170. ## Credits
  171. - [openai/codex](https://github.com/openai/codex) — the Codex CLI and its `$imagegen` skill
  172. - [Codex CLI image generation write-up](https://codex.danielvaughan.com/2026/04/27/codex-cli-image-generation-gpt-image-2-visual-development-workflows/)
  173. ## License
  174. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.