# Codex Ideation
> 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.
- Skill: `phuryn/codex-ideation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add phuryn/codex-ideation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/phuryn/codex-ideation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: phuryn (https://skillmd.com/u/phuryn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/phuryn/codex-ideation
---
# 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 ", "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`:
```bash
python .claude/skills/codex-ideation/scripts/codex.py --new --read
```
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?"
```bash
python .claude/skills/codex-ideation/scripts/codex.py ""
```
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 ""` | Send; auto-resume if a session exists, else start new |
| `codex.py --new ""` | 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//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.