Codex CLI Skill
Run OpenAI Codex CLI directly from the terminal. This skill covers one-shot execution,
multi-turn sessions, code review, session resume/fork, and output capture.
Constraints
- Always use
codex CLI — never fall back to mcp__codex__codex or mcp__codex__codex-reply MCP tools.
- OpenAI API key must be configured (
codex login or OPENAI_API_KEY env var).
- Always use
--full-auto for non-interactive execution (sets -a on-request --sandbox workspace-write).
- Always capture output via
-o <file> and read the file back — raw stdout may contain ANSI escape codes or progress indicators.
- For read-only analysis, use
-s read-only instead of --full-auto.
- Default model is whatever
~/.codex/config.toml's model key currently says — read it at runtime with grep '^model' ~/.codex/config.toml if you need to know it; never hardcode a specific version in instructions or scripts, it drifts. Override per-call with -m <model>.
- Default to background execution. Codex calls routinely take 2–10 minutes — well past the Bash tool's 2-minute default timeout. Launch with
run_in_background: true and Monitor the -o file, OR pass timeout: 600000 for foreground. Do NOT rely on default timeouts. See Adaptive Execution.
Preflight Check
Before running any codex command, verify the installation:
codex --version
If this fails:
- "command not found" — codex-cli is not installed.
Suggest:
npm install -g @openai/codex or check the Codex CLI installation docs.
- Authentication errors — API key not configured.
Suggest:
codex login (interactive) or set OPENAI_API_KEY env var.
Output Handling
Always use the -o flag to write the final response to a file, then read it:
codex exec "your prompt" --full-auto -o /tmp/codex-out.txt -C "$(pwd)"
cat /tmp/codex-out.txt
For session ID extraction (when you need to resume a specific session later):
# Redirect JSONL to file (do NOT pipe through head — broken pipe kills codex)
codex exec "your prompt" --full-auto --json -o /tmp/codex-out.txt -C "$(pwd)" > /tmp/codex-events.jsonl 2>/dev/null
# Extract thread_id from the first event (jq not required — use grep+cut)
head -1 /tmp/codex-events.jsonl | grep -o '"thread_id":"[^"]*"' | cut -d'"' -f4
cat /tmp/codex-out.txt
The --json flag streams JSONL events to stdout. The first event is thread.started containing thread_id (the session UUID). The -o flag independently captures the final text response.
Important: Do NOT pipe --json output through head or other commands that close the pipe early — this causes a broken pipe signal that kills the codex process. Always redirect to a file first, then extract.
Adaptive Execution
Codex CLI calls are slow — typically 2–10 minutes, sometimes longer for complex prompts or high reasoning effort. The Bash tool's default timeout is 2 minutes. Without explicit handling, the call gets killed mid-flight and the agent gives up before a response arrives.
Pick a pattern for every codex call:
Pattern A — Background + Monitor (preferred for any non-trivial prompt)
Launch the codex command with the Bash tool's run_in_background: true, then wait for the -o file to be written before reading.
# 1. Launch in background — Bash tool param: run_in_background=true
rm -f /tmp/codex-out.txt # clear stale output if reusing the path
codex exec "your prompt" --full-auto -o /tmp/codex-out.txt -C "$(pwd)"
Then use the Monitor tool with a bounded for loop to wait for completion without polling burn AND without infinite-looping if codex crashes:
# Monitor tool: 120 iterations × 5s = 10 minutes max
for i in $(seq 1 120); do
[ -s /tmp/codex-out.txt ] && break
sleep 5
done
[ -s /tmp/codex-out.txt ] || { echo "ERROR: codex produced no output within 10 min" >&2; exit 1; }
-s is true once the file exists and is non-empty (codex writes the final message at the end). The bound matters: an unbounded until loop will hang forever if codex crashes silently (network drop, OOM, killed) — same "agent gives up" failure mode in disguise. Always bound the wait.
If you also need to confirm the codex process has fully exited (e.g., before resuming), pair the success check with a pgrep check:
for i in $(seq 1 120); do
[ -s /tmp/codex-out.txt ] && ! pgrep -f "codex exec" >/dev/null && break
sleep 5
done
Caveat: pgrep -f "codex exec" matches all running codex processes. If you have concurrent codex calls in flight, scope it tighter (pgrep -f "codex exec.*<unique-marker>") or skip the pgrep check.
Pattern B — Foreground with extended timeout (only for short, simple prompts)
When you're confident the call will finish quickly (small prompt, low reasoning, no tool use), pass an explicit timeout to the Bash tool:
# Bash tool param: timeout=600000 (10 minutes — the maximum)
codex exec "short prompt" --full-auto --ephemeral -o /tmp/codex-out.txt -C "$(pwd)"
cat /tmp/codex-out.txt
Never rely on the default 2-minute timeout for codex calls.
Tune for speed
When latency matters more than depth, reduce the work codex does:
| Lever | Flag | Effect |
|---|
| Reasoning effort | -c model_reasoning_effort="low" | Fastest. Use medium (default) or high only when needed. |
| Smaller model | -m <mini-model-name> (check codex --help or the model family docs for the current mini variant — don't hardcode one) | Faster, cheaper, less capable. |
| Disable web search | (omit --search) | Search adds round-trips. |
| Tighter prompt | — | Less to read = less to think about. |
| Read-only sandbox | -s read-only | No tool-use round-trips. Pure analysis. |
Combine for fastest responses:
codex exec "quick question" --full-auto --ephemeral \
-c model_reasoning_effort="low" \
-o /tmp/codex-out.txt -C "$(pwd)"
Decision rule
- Default: Pattern A (background + Monitor). Safe for any prompt length.
- Pattern B: only when the prompt is small AND you've tuned for speed AND you'd rather block than context-switch.
- Never: foreground + default timeout. Codex will outlast it and the agent will give up.
Quick Reference
Note: For every command below, the Bash tool should use run_in_background: true (default) or timeout: 600000 (foreground). Codex calls outlast the 2-min default timeout. See Adaptive Execution.
| Task | Command |
|---|
| One-shot (no session) | codex exec "prompt" --full-auto --ephemeral -o /tmp/codex-out.txt -C "$(pwd)" |
| Persistent session | codex exec "prompt" --full-auto -o /tmp/codex-out.txt -C "$(pwd)" |
| Fast/low-latency query | codex exec "prompt" --full-auto --ephemeral -c model_reasoning_effort="low" -o /tmp/codex-out.txt -C "$(pwd)" |
| Follow-up (last session) | codex exec resume --last "follow-up" --full-auto -o /tmp/codex-out.txt |
| Resume by ID | codex exec resume <SESSION_ID> "follow-up" --full-auto -o /tmp/codex-out.txt |
| Fork last session | codex fork --last "new direction" --full-auto |
| Code review (uncommitted) | codex exec review --uncommitted --full-auto -o /tmp/codex-review.txt |
| Code review (vs branch) | codex exec review --base main --full-auto -o /tmp/codex-review.txt |
| Code review (specific commit) | codex exec review --commit <SHA> --full-auto -o /tmp/codex-review.txt |
| Custom review instructions | codex exec review "Focus on security" --base main --full-auto -o /tmp/codex-review.txt |
| Override model | codex exec "prompt" --full-auto -m o3 -o /tmp/codex-out.txt |
| Attach image | codex exec "describe this" --full-auto -i screenshot.png -o /tmp/codex-out.txt |
| Read-only analysis | codex exec "analyze this code" -s read-only -o /tmp/codex-out.txt -C "$(pwd)" |
Session Workflows
One-shot (ephemeral)
For quick, throwaway queries that don't need session persistence:
codex exec "Explain the purpose of this function" --full-auto --ephemeral -o /tmp/codex-out.txt -C "$(pwd)"
cat /tmp/codex-out.txt
--ephemeral prevents session files from being written to disk.
Start a persistent session
For multi-turn conversations where you need follow-ups:
codex exec "Analyze the authentication module architecture" --full-auto -o /tmp/codex-out.txt -C "$(pwd)"
cat /tmp/codex-out.txt
Without --ephemeral, the session is automatically persisted to ~/.codex/sessions/YYYY/MM/DD/.
Follow-up (continue last session)
Send a follow-up to the most recent session:
codex exec resume --last "Now suggest improvements to the error handling" --full-auto -o /tmp/codex-out.txt
cat /tmp/codex-out.txt
--last picks the most recent session filtered by current working directory. The follow-up inherits the full conversation context.
CWD filtering caveat: --last only finds sessions started from the same CWD. If resuming from a different directory, use --all to disable CWD filtering, and add --skip-git-repo-check if the directory is not a git repo:
codex exec resume --last --all "follow-up" --full-auto -o /tmp/codex-out.txt --skip-git-repo-check
Resume a specific session by ID
When working with multiple sessions, resume by UUID:
codex exec resume "019d3942-55ab-7ac1-b77f-8d5bcb1cd80c" "What about the edge cases?" --full-auto -o /tmp/codex-out.txt
cat /tmp/codex-out.txt
To capture the session ID when starting a session:
# Start session and capture JSONL events to file
codex exec "Start analyzing the API layer" --full-auto --json -o /tmp/codex-out.txt -C "$(pwd)" > /tmp/codex-events.jsonl 2>/dev/null
# Extract thread_id (no jq needed)
SESSION_ID=$(head -1 /tmp/codex-events.jsonl | grep -o '"thread_id":"[^"]*"' | cut -d'"' -f4)
echo "Session ID: $SESSION_ID"
cat /tmp/codex-out.txt
# Later, resume with explicit ID (works across any CWD):
codex exec resume "$SESSION_ID" "Now check the middleware" --full-auto -o /tmp/codex-out.txt
cat /tmp/codex-out.txt
Fork a session
Create a new branch of conversation from an existing session:
# Fork the most recent session
codex fork --last "Try a different approach — use middleware instead"
# Fork a specific session by ID
codex fork "019d3942-55ab-7ac1-b77f-8d5bcb1cd80c" "What if we used a queue instead?"
Note: codex fork starts an interactive TUI session. For non-interactive forking, use codex exec resume with a new prompt instead — it achieves a similar effect.
List/find sessions
Sessions are stored as JSONL files in ~/.codex/sessions/YYYY/MM/DD/. To find recent sessions:
ls -lt ~/.codex/sessions/$(date +%Y/%m/%d)/ 2>/dev/null || ls -lt ~/.codex/sessions/$(date -d yesterday +%Y/%m/%d)/ 2>/dev/null
Code Review
Run AI-powered code review non-interactively:
# Review uncommitted changes (staged + unstaged + untracked)
codex exec review --uncommitted --full-auto -o /tmp/codex-review.txt
cat /tmp/codex-review.txt
# Review changes against a base branch
codex exec review --base main --full-auto -o /tmp/codex-review.txt
cat /tmp/codex-review.txt
# Review a specific commit
codex exec review --commit abc1234 --full-auto -o /tmp/codex-review.txt
cat /tmp/codex-review.txt
# Custom review focus
codex exec review "Focus on security vulnerabilities and SQL injection risks" --base develop --full-auto -o /tmp/codex-review.txt
cat /tmp/codex-review.txt
# Add a title for the review summary
codex exec review --base main --title "Auth middleware refactor" --full-auto -o /tmp/codex-review.txt
cat /tmp/codex-review.txt
The standalone codex review command (without exec) also works but runs interactively.
Agent Tips
- Always
--full-auto: Required for non-interactive execution. Without it, codex will wait for TTY approval prompts that can't be answered.
- Always
-o <file>: Captures clean text output. Parsing raw stdout is unreliable due to ANSI codes and progress indicators.
--ephemeral for throwaway: Use when context persistence isn't needed — avoids cluttering session history.-C "$(pwd)" for CWD: Pass the current working directory explicitly so codex operates on the right files.run_in_background by default: Codex routinely takes 2–10 minutes, exceeding the Bash tool's 2-minute default timeout. Launch every non-trivial codex call with run_in_background: true and use the Monitor tool to wait on the -o file. Foreground calls require explicit timeout: 600000. See Adaptive Execution.- Tune reasoning effort for latency: For quick queries, pass
-c model_reasoning_effort="low". The default (medium) is balanced; reserve high for genuinely hard problems where you're willing to wait.
-s read-only for safe analysis: When codex only needs to read and analyze (not write), use read-only sandbox mode.-m for model override: Switch models per-query without changing config, e.g. -m o3 or -m <model-name> — never hardcode a specific dated/versioned model name in scripts, since ~/.codex/config.toml's default drifts over time.-i for image input: Attach screenshots or diagrams: -i screenshot.png.--search for web search: Enable web search capability: codex exec "what's new in React 19" --search --full-auto -o /tmp/codex-out.txt.- Pipe from stdin: Use
- as prompt to read from stdin: echo "explain this" | codex exec - --full-auto -o /tmp/codex-out.txt.
--json + -o together: --json streams JSONL events to stdout (redirect to file, do NOT pipe through head); -o independently captures the final message. First event's thread_id is the session UUID.--all for cross-CWD resume: codex exec resume --last filters sessions by CWD. Add --all to find sessions started from any directory.--skip-git-repo-check: Required when running codex from a directory that is not a git repository.- Config overrides: Use
-c key=value for one-off config changes: -c model_reasoning_effort="low".
--add-dir: Grant write access to additional directories beyond the workspace: --add-dir /tmp/output.--output-schema: Constrain the response shape with a JSON Schema file for structured output.
Error Handling
| Error | Cause | Fix |
|---|
command not found: codex | codex-cli not installed | Install via npm or check PATH |
Authentication required / invalid API key | OpenAI API key missing or expired | Run codex login or set OPENAI_API_KEY |
No sessions found | No session to resume, or CWD mismatch | Start a new session, or add --all to disable CWD filtering |
Session not found: <ID> | Invalid or deleted session UUID | Check ~/.codex/sessions/ for valid IDs |
timed out / agent gives up before response | Bash 2-min default timeout shorter than typical codex latency (2–10 min) | Default to run_in_background: true + Monitor on the -o file. For foreground, set timeout: 600000. Tune speed via -c model_reasoning_effort="low" or a smaller -m. See Adaptive Execution. |
Permission denied / sandbox error | Sandbox policy too restrictive | Use --full-auto or -s workspace-write / -s danger-full-access |
Not a git repository | codex exec requires git repo by default | Use --skip-git-repo-check or cd to a git repo |
| ANSI escape codes in output | Reading stdout instead of -o file | Always use -o <file> and read the file |
Broken pipe / empty -o file | Piping --json stdout through head or other early-close commands | Redirect --json to a file (> events.jsonl), then extract from the file |
| Resume finds wrong session | --last filtered by CWD, picked a different session | Use explicit session ID, or add --all to search all sessions |
Read references/cli-reference.md for the full flag-by-flag reference of all subcommands.
Retrospective
After completing the workflow, reflect on the entire execution session:
- Consider: Were there mid-session corrections? Rejected outputs? Plan changes? Errors? Did codex calls time out or hang?
- Ask the user: "Quick feedback on this run? (1-5 rating, note any issues, or press enter to skip)"
- If the user provides feedback OR if corrections/issues occurred during this session:
a. Create
feedback/ directory if it does not exist
b. Read feedback/log.md (create with # Feedback Log header if it does not exist)
c. Prepend a new entry after the header using the log format from my-skill-factory/references/skill-improvement-guide.md
d. Fill in: current timestamp, skill version from frontmatter, task description, outcome assessment,
corrections that occurred during the session, issues encountered, user's note
- If the user skips AND no corrections or issues occurred, end without recording.
Behavior Scenarios
Scenario: One-shot Codex query
Given codex CLI is installed and authenticated
When the user asks to run a quick Codex prompt
Then run `codex exec "<prompt>" --full-auto --ephemeral -o /tmp/codex-out.txt -C "$(pwd)"`
And read the output file and present the result
Scenario: Multi-turn session with follow-up (same CWD)
Given a Codex session was started with `codex exec` from directory X
When the user asks to continue from the same directory X
Then run `codex exec resume --last "<follow-up>" --full-auto -o /tmp/codex-out.txt`
And present the continued conversation result with prior context preserved
Scenario: Multi-turn session with follow-up (different CWD)
Given a Codex session was started from directory X
When the user asks to continue from a different directory Y
Then run `codex exec resume --last --all "<follow-up>" --full-auto --skip-git-repo-check -o /tmp/codex-out.txt`
And present the continued conversation result
Scenario: Code review via Codex
Given codex CLI is installed and user is in a git repository
When the user asks Codex to review code changes
Then run `codex exec review` with appropriate flags (--uncommitted, --base, --commit)
And capture output via -o and present the review findings
Scenario: Resume or fork a specific session
Given the user has previous Codex sessions
When the user asks to resume or fork a specific session by ID
Then run `codex exec resume <SESSION_ID> "<prompt>"` or `codex fork <SESSION_ID>`
And present the result
Scenario: Codex CLI not installed or not authenticated
Given codex CLI is not installed or not logged in
When the user asks to perform any Codex operation
Then check with `codex --version`, guide installation or `codex login` as needed
Scenario: Long-running Codex query without timing out
Given a Codex prompt is expected to take longer than 2 minutes
When the user asks to run any non-trivial codex command
Then launch with the Bash tool's `run_in_background: true` and `-o /tmp/codex-out.txt`
And use the Monitor tool with a bounded `for i in $(seq 1 120); do [ -s /tmp/codex-out.txt ] && break; sleep 5; done`
And after the loop, verify the file is non-empty (codex may have crashed) and surface an error if not
And read /tmp/codex-out.txt only after the loop exits with a non-empty file
And never rely on the default 2-minute Bash timeout
Scenario: Latency-sensitive Codex query
Given the user wants a fast answer and depth is not critical
When running codex exec
Then add `-c model_reasoning_effort="low"` and consider a smaller `-m` model
And still use background execution (Pattern A) unless the prompt is trivially short