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 <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`: ```bash 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?" ```bash 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.