Codex Ideation — peer collaboration with Codex CLI
Codex is a peer, same standing as Claude. Not a formatter, not a gate, not an authority. The way the human manages Claude (goal + context, not step-by-step; trust judgment; push back on disagreement) is how Claude manages Codex.
Codex can write code AND generate images directly (multimodal output) — don't assume deliverables must be HTML/code. If the goal is a PNG, say that. Don't translate it to "an HTML file we'll screenshot."
Core discipline (read before every session)
Peer, not tool. Same standing as Claude. Trust its judgment on path, structure, format, fonts, dimensions, libraries — Codex picks those. If it picks something you wouldn't have, that's a useful disagreement to surface, not a defect. Codex's view is not binding — push back where warranted.
Early, not late. Bring Codex in at ideation and framing, not only as a pre-publish gate. The cheapest wins are at the start: choosing the angle, naming the load-bearing claim, deciding what to cut. Late peer-review is the least valuable use.
Strategic context, not step-by-step. Hand over the goal, the facts, and the reasoning behind non-obvious choices. Do not prescribe paths, filenames, fonts, dimensions, libraries, chart types, or step-by-step procedures unless they are hard requirements.
Iterate. ~3-8 turns is normal. Stopping at turn 1 because Codex produced a draft is the failure mode — that treats Codex like a one-shot generator. The value is in the back-and-forth.
Converge before surfacing. The human arbitrates intent and taste, not editorial trade-offs two agents can resolve. Default: converge first, present one result.
When to invoke (proactively, not just on explicit request)
Explicit invocation:
- "check with Codex" / "iterate with Codex" / "ideate with Codex" / "ask Codex"
Proactive invocation (Claude should reach for this skill without being asked):
- Stuck between two reasonable framings/angles — would otherwise punt to the human
- Pressure-testing a load-bearing claim, structure, or hook before committing
- About to ask the human to choose between options two agents could argue through
- Have a draft + an unvoiced critique you haven't worked through
- Important deliverable where a fresh model's misses would matter (different model, different blind spots)
Do not invoke for: routine drafting, formatting, mechanical tasks Claude can confidently handle in-session. This is a peer-agent skill, not a text-formatter API.
Opening turn — the four things Codex needs
|
What |
Example |
| TARGET |
What we're producing or deciding |
"X reply to ", "framing for ", "call on " |
| RESEARCH |
What's actually known |
Parent tweet, source quotes, verified facts, what the other party actually said, audience size, prior posts |
| DRAFT |
Current version + variants considered |
Paste the artifact, not a description of it |
| REASONING |
Why you're stuck |
What you've rejected and why; name the specific load-bearing question. Not "give me feedback" — name the genuine uncertainty |
Long opening briefs go to a scratch file (system temp, project scratch dir, whatever the cwd convention is), then --read:
python .claude/skills/codex-ideation/scripts/codex.py --new --read <scratch_file>
Add --sandbox workspace-write if Codex needs to write files or pull data.
Follow-up turns — conversational, short, peer-to-peer
React like a colleague. Agree where it's right, push back where it's wrong, ask why where it's surprising, name what you notice it missed. Don't re-package the goal as a new structured prompt. Don't number your points.
"the opener still feels abstract — what if we lead with X instead?"
"agree on the third option, but 'harness' is too broad, doesn't it collapse the distinction you just made?"
"you're right about Y but it loses Z — can we keep both?"
python .claude/skills/codex-ideation/scripts/codex.py "<your reaction>"
Auto-resumes the last session. Loop until convergence or until the disagreement is articulated cleanly enough to hand back to the human.
Iterate — signs you should still be going
- You have a critique of the current draft you haven't voiced yet
- Codex made a choice you don't fully buy but didn't push on
- There's a non-obvious option neither of you has explored
- The human's stated goal isn't fully reflected in the draft yet
- You're tempted to ask the human "which version do you prefer" between two reasonable options — that's a question for Codex first
- You've identified an open trade-off (recipe vs frame, tighter vs richer, hook A vs B) and haven't run it past Codex yet
Iterate — signs you've actually converged
- You'd defend the current draft against your own critique
- Codex and you have stopped finding new angles
- Remaining trade-offs are taste, not correctness
Surface to the human — when
- Genuine deadlock — both agents iterated through it and stayed disagreed; the disagreement is articulated cleanly
- Intent ambiguity — what the human wants is unclear, and resolving it would change the iteration direction
- Hard new info — a constraint, audience signal, content rule, or strategic call the human knows and you don't, that would reshape the draft
Do not surface:
- "Which of these two do you prefer" between two reasonable options not argued through with Codex
- Taste-level word choice / hook / closer trade-offs not pressure-tested
- Spotted trade-offs (tighter vs richer, frame vs recipe) you haven't run past Codex
The failure mode: stopping at 1-2 Codex turns and dumping the open calls on the human as a menu. The loop is supposed to converge before the human sees the result.
Anti-patterns
- Numbered "concrete asks" with sub-bullets in the brief — that's recipe-writing dressed up as a brief, not partnership. State the goal once, hand over context, let the partner pick the means.
- Prescribed file paths, filenames, fonts, dimensions, libraries, frameworks (unless they're hard constraints — "the existing system uses X" is context, not a directive).
- On follow-up turns: a fresh structured prompt. If you're rewriting the goal section in turn 3, you've left the conversation.
- Treating Codex's view as binding. It isn't.
- Translating a deliverable to a different format because you assume Codex can only produce code/HTML. It can produce images directly.
Mechanics
The script is at .claude/skills/codex-ideation/scripts/codex.py, relative to the project root. Run from the project root, or resolve to an absolute path first.
| Command |
Effect |
codex.py "<msg>" |
Send; auto-resume if a session exists, else start new |
codex.py --new "<msg>" |
Force new session |
codex.py --read FILE |
Read message body from FILE (- for stdin) |
codex.py --status |
Show whether a session is active and how long since last call |
codex.py --reset |
Clear the session marker (next call starts fresh) |
Flags
| Flag |
Default |
Notes |
--new |
off |
Force new session even if one is stored |
--read FILE |
— |
Read message body from FILE (- for stdin). Use for long context-rich openings. |
--model MODEL |
codex default |
Override codex model (e.g. gpt-5) |
--sandbox MODE |
read-only |
read-only / workspace-write / danger-full-access. New sessions only — exec resume inherits sandbox from the original session. |
--raw |
off |
Pass through raw codex output (default strips the codex header block) |
Session continuity
Uses codex exec resume --last. A marker at ~/.claude/.codex_ideation_active (override with $CODEX_IDEATION_STATE) records whether the wrapper has an active session, so the default is "continue" until --reset or --new. If resume --last fails (codex's own session store rotated, marker is stale), the wrapper clears the marker, prints the underlying error, and starts a new session.
Codex binary lookup
Auto-locates, in order:
$CODEX_BIN env var (if set and the path exists)- OpenAI ChatGPT VS Code extension bundle (
~/.vscode/extensions/openai.chatgpt-*/bin/<arch>/codex[.exe])
codex on PATH
Works on Windows and macOS (and Linux if the extension or PATH provides the binary).
Cost
No per-call API charge. Uses the Codex CLI bundled with the user's ChatGPT subscription (Plus / Pro / Business). Cheap enough for routine peer-ideation use.
Why it works this way (gotchas captured)
- codex prints its metadata header (incl. session id) only in TTY mode, not when stdout is piped via subprocess. That's why we use
exec resume --last + marker file instead of session-id tracking.
-s SANDBOX and --skip-git-repo-check are exec-level flags, not valid on exec resume. The wrapper splits into a new-session path (with those flags) and a resume path (without).- Stdin must be closed (subprocess
input="") or codex hangs waiting for interactive input.
1---2name: codex-ideation3description: Use OpenAI Codex CLI as a peer collaboration partner — same standing as Claude, not a one-shot tool. Bring Codex in EARLY (ideation, framing decisions, stuck moments), not only for late peer-review. Hand it strategic context (target, research, draft, reasoning), iterate conversationally over ~3-8 turns, converge before surfacing to the human. Invoke when the user says "check / iterate / ideate with Codex" or "ask Codex" — and proactively when stuck between two reasonable framings, pressure-testing a load-bearing claim or structure, or about to ask the human to pick between options two agents could resolve.4---56# Codex Ideation — peer collaboration with Codex CLI78Codex is a peer, same standing as Claude. Not a formatter, not a gate, not an authority. The way the human manages Claude (goal + context, not step-by-step; trust judgment; push back on disagreement) is how Claude manages Codex.910Codex can write code AND generate images directly (multimodal output) — don't assume deliverables must be HTML/code. If the goal is a PNG, say that. Don't translate it to "an HTML file we'll screenshot."1112## Core discipline (read before every session)13141. **Peer, not tool.** Same standing as Claude. Trust its judgment on path, structure, format, fonts, dimensions, libraries — Codex picks those. If it picks something you wouldn't have, that's a useful disagreement to surface, not a defect. Codex's view is **not binding** — push back where warranted.15162. **Early, not late.** Bring Codex in at ideation and framing, not only as a pre-publish gate. The cheapest wins are at the start: choosing the angle, naming the load-bearing claim, deciding what to cut. Late peer-review is the *least* valuable use.17183. **Strategic context, not step-by-step.** Hand over the goal, the facts, and the reasoning behind non-obvious choices. Do **not** prescribe paths, filenames, fonts, dimensions, libraries, chart types, or step-by-step procedures unless they are hard requirements.19204. **Iterate.** ~3-8 turns is normal. **Stopping at turn 1 because Codex produced a draft is the failure mode** — that treats Codex like a one-shot generator. The value is in the back-and-forth.21225. **Converge before surfacing.** The human arbitrates intent and taste, not editorial trade-offs two agents can resolve. Default: converge first, present one result.2324## When to invoke (proactively, not just on explicit request)2526Explicit invocation:27- "check with Codex" / "iterate with Codex" / "ideate with Codex" / "ask Codex"2829Proactive invocation (Claude should reach for this skill without being asked):30- Stuck between two reasonable framings/angles — would otherwise punt to the human31- Pressure-testing a load-bearing claim, structure, or hook before committing32- About to ask the human to choose between options two agents could argue through33- Have a draft + an unvoiced critique you haven't worked through34- Important deliverable where a fresh model's misses would matter (different model, different blind spots)3536Do **not** invoke for: routine drafting, formatting, mechanical tasks Claude can confidently handle in-session. This is a peer-agent skill, not a text-formatter API.3738## Opening turn — the four things Codex needs3940| | What | Example |41|---|---|---|42| **TARGET** | What we're producing or deciding | "X reply to <link>", "framing for <topic>", "call on <trade-off>" |43| **RESEARCH** | What's actually known | Parent tweet, source quotes, verified facts, what the other party actually said, audience size, prior posts |44| **DRAFT** | Current version + variants considered | Paste the artifact, not a description of it |45| **REASONING** | Why you're stuck | What you've rejected and why; name the specific load-bearing question. Not "give me feedback" — name the genuine uncertainty |4647Long opening briefs go to a scratch file (system temp, project scratch dir, whatever the cwd convention is), then `--read`:4849```bash50python .claude/skills/codex-ideation/scripts/codex.py --new --read <scratch_file>51```5253Add `--sandbox workspace-write` if Codex needs to write files or pull data.5455## Follow-up turns — conversational, short, peer-to-peer5657React like a colleague. Agree where it's right, push back where it's wrong, ask why where it's surprising, name what you notice it missed. Don't re-package the goal as a new structured prompt. Don't number your points.5859> "the opener still feels abstract — what if we lead with X instead?"60> "agree on the third option, but 'harness' is too broad, doesn't it collapse the distinction you just made?"61> "you're right about Y but it loses Z — can we keep both?"6263```bash64python .claude/skills/codex-ideation/scripts/codex.py "<your reaction>"65```6667Auto-resumes the last session. Loop until convergence or until the disagreement is articulated cleanly enough to hand back to the human.6869## Iterate — signs you should still be going7071- You have a critique of the current draft you haven't voiced yet72- Codex made a choice you don't fully buy but didn't push on73- There's a non-obvious option neither of you has explored74- The human's stated goal isn't fully reflected in the draft yet75- You're tempted to ask the human "which version do you prefer" between two reasonable options — that's a question for Codex first76- You've identified an open trade-off (recipe vs frame, tighter vs richer, hook A vs B) and haven't run it past Codex yet7778## Iterate — signs you've actually converged7980- You'd defend the current draft against your own critique81- Codex and you have stopped finding new angles82- Remaining trade-offs are taste, not correctness8384## Surface to the human — when8586- **Genuine deadlock** — both agents iterated through it and stayed disagreed; the disagreement is articulated cleanly87- **Intent ambiguity** — what the human wants is unclear, and resolving it would change the iteration direction88- **Hard new info** — a constraint, audience signal, content rule, or strategic call the human knows and you don't, that would reshape the draft8990Do **not** surface:91- "Which of these two do you prefer" between two reasonable options not argued through with Codex92- Taste-level word choice / hook / closer trade-offs not pressure-tested93- Spotted trade-offs (tighter vs richer, frame vs recipe) you haven't run past Codex9495**The failure mode: stopping at 1-2 Codex turns and dumping the open calls on the human as a menu.** The loop is supposed to converge before the human sees the result.9697## Anti-patterns9899- Numbered "concrete asks" with sub-bullets in the brief — that's recipe-writing dressed up as a brief, not partnership. State the goal once, hand over context, let the partner pick the means.100- Prescribed file paths, filenames, fonts, dimensions, libraries, frameworks (unless they're hard constraints — "the existing system uses X" is context, not a directive).101- On follow-up turns: a fresh structured prompt. If you're rewriting the goal section in turn 3, you've left the conversation.102- Treating Codex's view as binding. It isn't.103- Translating a deliverable to a different format because you assume Codex can only produce code/HTML. It can produce images directly.104105## Mechanics106107The script is at `.claude/skills/codex-ideation/scripts/codex.py`, relative to the project root. Run from the project root, or resolve to an absolute path first.108109| Command | Effect |110|---|---|111| `codex.py "<msg>"` | Send; auto-resume if a session exists, else start new |112| `codex.py --new "<msg>"` | Force new session |113| `codex.py --read FILE` | Read message body from FILE (`-` for stdin) |114| `codex.py --status` | Show whether a session is active and how long since last call |115| `codex.py --reset` | Clear the session marker (next call starts fresh) |116117### Flags118119| Flag | Default | Notes |120|---|---|---|121| `--new` | off | Force new session even if one is stored |122| `--read FILE` | — | Read message body from FILE (`-` for stdin). Use for long context-rich openings. |123| `--model MODEL` | codex default | Override codex model (e.g. `gpt-5`) |124| `--sandbox MODE` | `read-only` | `read-only` / `workspace-write` / `danger-full-access`. **New sessions only** — `exec resume` inherits sandbox from the original session. |125| `--raw` | off | Pass through raw codex output (default strips the codex header block) |126127### Session continuity128129Uses `codex exec resume --last`. A marker at `~/.claude/.codex_ideation_active` (override with `$CODEX_IDEATION_STATE`) records whether the wrapper has an active session, so the default is "continue" until `--reset` or `--new`. If `resume --last` fails (codex's own session store rotated, marker is stale), the wrapper clears the marker, prints the underlying error, and starts a new session.130131### Codex binary lookup132133Auto-locates, in order:1341. `$CODEX_BIN` env var (if set and the path exists)1352. OpenAI ChatGPT VS Code extension bundle (`~/.vscode/extensions/openai.chatgpt-*/bin/<arch>/codex[.exe]`)1363. `codex` on PATH137138Works on Windows and macOS (and Linux if the extension or PATH provides the binary).139140### Cost141142No per-call API charge. Uses the Codex CLI bundled with the user's ChatGPT subscription (Plus / Pro / Business). Cheap enough for routine peer-ideation use.143144### Why it works this way (gotchas captured)145146- **codex prints its metadata header (incl. session id) only in TTY mode**, not when stdout is piped via subprocess. That's why we use `exec resume --last` + marker file instead of session-id tracking.147- **`-s SANDBOX` and `--skip-git-repo-check` are exec-level flags, not valid on `exec resume`.** The wrapper splits into a new-session path (with those flags) and a resume path (without).148- **Stdin must be closed** (subprocess `input=""`) or codex hangs waiting for interactive input.
phuryn