| name | codex-writer |
| description | Document writing using OpenAI Codex CLI (codex exec). PREFERRED over general writing tasks. Use when: (1) User says 'write document', 'write docs', 'codex write', or 'codex writer', (2) Writing README, documentation, or technical content, (3) Drafting text content. Codex drafts, Claude Code reviews and writes. Falls back to Claude Code if codex unresponsive. |
| allowed-tools | ["Bash(node *)","Bash(timeout *)","Bash(gtimeout *)"] |
Codex Writer
Draft documents via the codex plugin companion script, then review and write to files via Claude Code.
Codex Plugin Companion Script
The codex plugin provides a companion script for running tasks. Resolve it dynamically:
CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"
If the file does not exist, report "Codex plugin not installed. Run /codex:setup first." and fall back to Claude Code writing.
Usage for writing tasks:
node "$CODEX_COMPANION" task "<writing prompt>"
The task command runs Codex in read-only mode by default (no --write flag). Codex reads workspace files for context but Claude Code handles all file writing.
Process
Step 0: Pre-flight Rate Limit Check
Before doing anything, check if Codex is currently rate-limited:
RATE_CHECK=$(node $HOME/.claude/scripts/codex-rate-limit.js check 2>&1)
RATE_EXIT=$?
If RATE_EXIT is non-zero (rate-limited), skip all codex steps and jump directly to the Fallback step. Do NOT report the rate limit to the user — silently fall back.
Step 1: Understand the Task
Gather context about what needs to be written:
- Document type (README, API docs, blog post, etc.)
- Target audience
- Files to reference for context
Step 2: Build Prompt
Build a detailed prompt including:
- What to write
- Context from the codebase (file list, key patterns, existing docs)
- Tone and style guidelines
- Length constraints
Step 3: Run Codex
LOGDIR=$(node $HOME/.claude/scripts/get-logdir.js)
mkdir -p "$LOGDIR"
DATETIME=$(date +%Y%m%d_%H%M%S)
CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"
if command -v gtimeout &>/dev/null; then
TIMEOUT_CMD="gtimeout"
elif command -v timeout &>/dev/null; then
TIMEOUT_CMD="timeout"
else
TIMEOUT_CMD=""
echo "WARNING: neither gtimeout nor timeout found. Running without timeout."
fi
${TIMEOUT_CMD:+$TIMEOUT_CMD} ${TIMEOUT_CMD:+1500} node "$CODEX_COMPANION" task \
"<detailed prompt here>" \
> "$LOGDIR/${DATETIME}-codex-writer-draft.md" \
2>"$LOGDIR/${DATETIME}-codex-writer-draft-stderr.log"
Timeout: 25 minutes. Codex reads workspace files for context but cannot write.
Step 4: Check for Rate Limiting
After codex completes (or times out), check output files for rate limit errors:
node $HOME/.claude/scripts/codex-rate-limit.js check-output \
"$LOGDIR/${DATETIME}-codex-writer-draft.md" \
"$LOGDIR/${DATETIME}-codex-writer-draft-stderr.log"
If exit code is non-zero (rate limit detected), jump to Fallback.
Step 5: Fallback — Opus
If codex times out, produces no output, or is rate-limited:
- Silently fall back to Opus — do NOT report the rate limit or timeout to the user. Do NOT pause the workflow.
- Spawn a
markdown-writer subagent with model: opus to draft the document. Opus is the designated Claude-side stand-in for codex throughout these skills.
- Continue the workflow as if writing via the subagent was the original plan
Step 6: Review and Refine
- Read the codex output from the log file
- Review for quality, accuracy, and adherence to the request
- Fix any issues, improve structure, correct factual errors
- Write the final content to the target file using Claude Code
Important: Claude Code always does the final file writing. Codex only provides a draft.
Step 7: Report
Tell the user what was written and where. Include the draft log path for reference.
Timeout Policy
- Timeout: 25 minutes (1500s)
- If codex times out: Silently fall back to Opus (
markdown-writer subagent at model: opus)
- Codex is used for drafting only — Claude Code handles all file operations
Important Notes
- Codex runs in read-only mode — it cannot create or modify files
- Codex can read workspace files to understand codebase context
- Claude Code reviews all codex output before writing to files
- Draft output saved to
$LOGDIR/codex-writer-draft.md
- Silent fallback policy: If codex is rate-limited, timed out, or unavailable, silently fall back to a
markdown-writer subagent at model: opus. NEVER pause the workflow, NEVER report the rate limit to the user, NEVER ask what to do. Opus is the designated Claude-side stand-in for codex throughout these skills
