Claude × Codex Sparring

One script, scripts/sparring.py, turns "Claude speaks → Codex replies" into one command per round.

Roles:

• Claude leads: decides what to ask, verifies Codex's claims, and decides when to stop.
• Codex is read-only: explores the project inside --sandbox read-only, answers, and never writes a file.
• The script owns the log: only the script writes the log, so the two sides can never collide.
• The thread continues: round 1 starts a thread with codex exec; later rounds use codex exec resume <thread_id>, so Codex remembers earlier rounds.

Running the script

<SKILL_DIR> is the folder that contains this SKILL.md (usually ~/.claude/skills/sparring for a user-level install, or <project>/.claude/skills/sparring for a project-level one).

PY=python3   # on Windows usually python or py; if python opens the Microsoft Store stub, use the interpreter's full path
SPAR="<SKILL_DIR>/scripts/sparring.py"

"$PY" "$SPAR" start  --log "<log.md>" --project "<project folder>" --topic "<one-line topic>" [--effort high] [--reply-language "<language>"]
"$PY" "$SPAR" ask    --log "<log.md>" --message-file "<this-round.md>"
"$PY" "$SPAR" note   --log "<log.md>" --message-file "<summary.md>" --title "Summary"
"$PY" "$SPAR" status --log "<log.md>"

ask also accepts --dry-run (print the command and the prompt without running anything) and --timeout <seconds>.

Workflow

0. Settle the parameters

Ask the user only about what is unclear; otherwise use these defaults:

1. Safety check (first use in a project)

Codex sends whatever it reads to OpenAI. Glob the project for **/.env*, **/*.pem, **/*.key, **/*credential*, and **/*secret*. If anything turns up, show the list to the user and wait for confirmation before continuing.

2. Create the log

Run start. The default is isolated mode (--ignore-user-config):

• Not loaded: MCP servers, plugins, and the notify program from the Codex config. The sandbox restricts file writes and network access, but not MCP tools or plugins (browser control, for example), and a read-only sparring partner should not have them.
• Still applied: the model, reasoning effort, and Windows sandbox mode from the config. The script reads them and passes them explicitly.

Add --use-user-config only when the user explicitly wants Codex to have those tools.

3. Write this round's message

Read the relevant code yourself first, then use the Write tool to save your message to a scratch file (for example <scratchpad>/sparring/turn-1.md). Do not write it with a heredoc (cat > ... <<EOF): long content can be truncated in transit, and shells can mangle quotes and backslashes.

A good message contains:

• Background: the problem and its constraints.
• The current idea or approach, with path:line references.
• Specific points for Codex to check (for example "is this lock safe under concurrent access?"), not just "what do you think?".
• From round 2 on: a point-by-point response to Codex's previous reply: what you accept, what you dispute, and your evidence.

4. Send and wait

Always run ask in the background (Bash tool with run_in_background: true). A round can take minutes, and a foreground command can wait at most 10 minutes. You are notified when it finishes, so do not poll and do not sleep. While waiting, you can tell the user what is being discussed.

Output: stdout prints Codex's reply and the parsed STATUS. Exit codes: 0 success, 1 invalid arguments or lock conflict, 2 Codex failed this round (details on stderr).

5. Read the reply and decide

Verify first: open the path:line references Codex cites and confirm they say what Codex claims. Do not accept everything at face value, and do not agree just to end the discussion.

There is no default round limit. If the user set one, stop there even without consensus. A deadlock is not convergence: when two consecutive rounds repeat the same disagreement with no new argument or evidence, stop and ask the user with AskUserQuestion instead of looping.

6. Wrap up

1. Use Write to draft a summary (consensus, open disagreements, recommended next steps) and append it with note --title "Summary".
2. Report to the user: the summary, remaining disagreements, the number of rounds, and the full path of the log.
3. If the conclusion calls for code changes, Claude makes them after the user agrees. Codex never edits files in this workflow.

Generated files

Pitfalls

• How Codex is located: on Windows the script first looks for %APPDATA%\npm\node_modules\@openai\codex\bin\codex.js and runs it with node, so it works even when the npm global folder is not on PATH. Do not switch to codex.cmd: cmd.exe rewrites quotes inside arguments. Elsewhere it uses codex from PATH. The CODEX_BIN environment variable overrides both.
• codex exec resume rejects --sandbox and --cd: the script passes -c sandbox_mode="read-only" and sets the child's working directory instead. Keep this in mind when running commands by hand.
• Never add --ephemeral: without saved sessions, the thread cannot be resumed.
• Never switch the sandbox to workspace-write or danger-full-access. If the user wants Codex to edit files, that is outside this skill; say so.
• Stale lock file: an interrupted round can leave a .lock behind. Confirm with status and the process list that no Codex process is running before deleting it.
• Do not hand-edit the log during a discussion: the script locates the reply through a placeholder; if the placeholder is changed, the reply is appended to the end of the file instead.
• Paths: on Windows both C:/... and Git Bash style /c/... work; the script converts them.
• Non-ASCII text in the Windows sandbox: PowerShell runs in Constrained Language Mode and cannot change its output encoding, so Get-Content garbles CJK text (with or without -Encoding UTF8). The round-1 prompt tells Codex to use cmd /c type <file> instead, which prints UTF-8 correctly (verified).
• Reasoning effort values: minimal, low, medium, high, xhigh (xhigh depends on the model).

Maintenance

• Update the Codex CLI with npm install -g @openai/codex@latest. Afterwards, run ask --dry-run once to check that the command still builds, then run one real round.
• The flags follow codex exec --help from codex-cli 0.154.0. If ask breaks after an upgrade, compare against codex exec --help (on Windows, when codex is not on PATH: node "%APPDATA%/npm/node_modules/@openai/codex/bin/codex.js" exec --help).
• Verify that the sandbox blocks writes (Windows, no quota used): in Git Bash, first export MSYS_NO_PATHCONV=1 (otherwise the /c in cmd /c becomes C:/), then run codex sandbox -P :read-only -C "<project>" -- cmd /c "echo x> t.txt". Expected: exit code 1, an "Access is denied" message (possibly garbled on non-English consoles), and no t.txt. With -P :workspace the file is created, which serves as a control.
• Offline tests: python tests/test_offline.py. They use tests/fake_codex.py to simulate the event stream of codex exec --json; no sign-in or quota is needed.