SKILL.md

$28

Minimal invocation:

~/.claude/skills/codex/scripts/ask_codex.sh "Your request in natural language"

With file context:

~/.claude/skills/codex/scripts/ask_codex.sh "Refactor these components to use the new API" \

  --file src/components/UserList.tsx \

  --file src/components/UserDetail.tsx

Multi-turn conversation (continue a previous session):

~/.claude/skills/codex/scripts/ask_codex.sh "Also add retry logic with exponential backoff" \

  --session <session_id from previous run>

Windows (PowerShell)

The script path is:

~/.claude/skills/codex/scripts/ask_codex.ps1

Minimal invocation:

&#x26; ~/.claude/skills/codex/scripts/ask_codex.ps1 "Your request in natural language"

With file context:

&#x26; ~/.claude/skills/codex/scripts/ask_codex.ps1 "Refactor these components to use the new API" `

  -f src/components/UserList.tsx `

  -f src/components/UserDetail.tsx

Multi-turn conversation (continue a previous session):

&#x26; ~/.claude/skills/codex/scripts/ask_codex.ps1 "Also add retry logic with exponential backoff" `

  -Session <session_id from previous run>

Output format

The script prints on success:

session_id=<thread_id>

output_path=<path to markdown file>

Read the file at output_path to get CodeX's response. Save session_id if you plan follow-up calls.

Workflow

Understand the problem: read the key files to grasp what's broken or needed. Focus on being able to describe the problem and goal clearly — you don't need to design the full solution or enumerate every affected file. Codex will explore the codebase itself.

Run the script with a focused task description: the goal, key constraints, and any non-obvious context. For discussion or analysis without changes, use --read-only.

Pass 1-4 entry-point files with --file as starting hints. Codex has the same tools as Claude and will discover related files on its own — no need to enumerate everything upfront.

Read the output — Codex executes changes and reports what it did.

Review the changes in your workspace.

For multi-step projects, use --session <id> to continue with full conversation history. For independent parallel tasks, use the Task tool with run_in_background: true.

Failure handling

**script: tcgetattr/ioctl: Operation not supported on socket** (exit code 1): the script command probes stdin with tcgetattr at startup and only tolerates ENOTTY/ENODEV errors. When Claude Code connects stdin via a socketpair, the kernel returns EOPNOTSUPP instead — which script doesn't whitelist, so it exits immediately. The script detects this automatically by probing with script -q /dev/null true first and falls back to direct execution. Update to the latest version if you still see this error.

Exit code 137: the task was interrupted (user cancel or OOM). Not a Codex bug — retry or break the task into smaller pieces.

**ERROR codex_core::codex: failed to load skill ...** in stderr: one of Codex's own installed skills has a broken YAML file. This warning is harmless and doesn't affect the current task — ignore it.

**(no response from codex)** in the output file: Codex ran but produced no readable output. Check stderr for clues; the task may have hit a sandbox restriction.

Options

--workspace <path> — Target workspace directory (defaults to current directory).

--file <path> — Point CodeX to key entry-point files (repeatable, workspace-relative or absolute). Don't duplicate their contents in the prompt.

--session <id> — Resume a previous session for multi-turn conversation.

--model <name> — Override model (default: uses Codex config).

--reasoning <level> — Reasoning effort: low, medium, high (default: medium). Use high for code review, debugging, complex refactoring, or root cause analysis.

--sandbox <mode> — Override sandbox policy (default: workspace-write via full-auto).

--read-only — Read-only mode for pure discussion/analysis, no file changes.

Resume mode limitations

When using --session to resume a previous conversation, note these limitations:

Must run in a git repository — The codex exec resume command requires a git-trusted directory. It does not support --skip-git-repo-check.

Limited options — Resume mode only supports -c/--config and --last. The following options are not supported in resume mode:

--sandbox

--full-auto

--read-only

--model

--workspace (resumes in the original session's context)

Text output only — Resume mode returns plain text instead of JSON-structured output.

codex