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)

1. 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.

2. 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.

3. 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.

4. 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.

5. 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 <link>", "framing for <topic>", "call on <trade-off>"
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:

1. $CODEX_BIN env var (if set and the path exists)
2. OpenAI ChatGPT VS Code extension bundle (~/.vscode/extensions/openai.chatgpt-*/bin/<arch>/codex[.exe])
3. 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.