| name | codex-ideation |
| description | 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. |
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.
