Codex

{
  "sections": {
    "Safety Guidelines": "**HPC Clusters - `--yolo` is SAFE and REQUIRED**:\r\n- HPC login nodes already have strict permissions (no root access, no network modification)\r\n- `--yolo` bypasses Codex sandbox but you still operate within HPC user restrictions\r\n- Always use `--yolo` on HPC to avoid Landlock errors\r\n\r\n**General Use - Exercise Caution**:\r\n- Don't use `--yolo` on unrestricted systems (your laptop, cloud VMs with full sudo)\r\n- Prefer `--full-auto` + `-s workspace-write` for normal development\r\n\r\n**Always verify before**:\r\n- Using `danger-full-access` sandbox (outside HPC)\r\n- Disabling approval prompts on production systems\r\n- Running with `--yolo` on personal machines with sudo access\r\n\r\n**Ask user approval for**:\r\n- First-time `workspace-write` usage\r\n- System-wide access requests\r\n- Destructive operations (deletions, migrations)",
    "Model Selection Guide": "| Task Type | Recommended Model | Reasoning Effort |\r\n|-----------|------------------|------------------|\r\n| Quick syntax fixes | `gpt-5` | minimal |\r\n| Code review | `gpt-5` | medium |\r\n| Refactoring | `gpt-5-codex` | medium |\r\n| Architecture analysis | `gpt-5` | high |\r\n| Security audit | `gpt-5` | high |\r\n| Algorithm optimization | `gpt-5-codex` | high |\r\n| Documentation generation | `gpt-5` | low |",
    "Best Practices": "### Reasoning Effort Selection\r\n- **minimal**: Syntax fixes, simple renaming\r\n- **low**: Standard refactoring, basic analysis\r\n- **medium**: Complex refactoring, architecture review\r\n- **high**: Security audits, algorithm optimization, critical bugs\r\n\r\n### Sandbox Mode Selection\r\n- **read-only**: Default for any analysis or review\r\n- **workspace-write**: File modifications only\r\n- **danger-full-access**: Network operations, system commands (rare)\r\n\r\n### Stderr Suppression\r\n- **Always use `2>/dev/null`** unless:\r\n  - User explicitly requests thinking tokens\r\n  - Debugging failed commands\r\n  - Troubleshooting configuration issues\r\n\r\n### Profile Usage\r\nCreate profiles for common workflows:\r\n- `review`: High reasoning, read-only\r\n- `refactor`: Medium reasoning, workspace-write\r\n- `quick`: Low reasoning, read-only\r\n- `security`: High reasoning, workspace-write\r\n\r\n### Stdin vs File Reference\r\n- **Stdin**: Single file analysis, avoids permissions\r\n- **File reference**: Multi-file context, codebase-wide changes",
    "Error Handling": "### Validation Loop\r\n1. Execute command\r\n2. Check exit code (non-zero = failure)\r\n3. Report error with context\r\n4. Ask user for direction via `AskUserQuestion`\r\n5. Retry with adjustments or escalate\r\n\r\n### Permission Requests\r\nBefore using high-impact flags, request user approval via `AskUserQuestion`:\r\n- `--full-auto`: Automated execution\r\n- `-s danger-full-access`: System-wide access\r\n- `--yolo` / `--dangerously-bypass-approvals-and-sandbox`:\r\n  - **HPC clusters**: No approval needed (required for operation)\r\n  - **Personal machines**: Request approval (full system access)\r\n\r\n### Partial Success Handling\r\nWhen output contains warnings:\r\n1. Summarize successful operations\r\n2. Detail failures with context\r\n3. Use `AskUserQuestion` to determine next steps\r\n4. Propose specific adjustments",
    "Command Patterns": "codex exec -m gpt-5 -c model_reasoning_effort=\"high\" --skip-git-repo-check --full-auto \\\r\n  \"Analyze this Python code: $(cat file.py)\" 2>/dev/null\r\n```\r\nOr for large files, use heredoc:\r\n```bash\r\ncodex exec --yolo -m gpt-5 -c model_reasoning_effort=\"high\" --skip-git-repo-check \"$(cat <<'ENDCODE'\r\nAnalyze the following code comprehensively:\r\n\r\n$(cat file.py)\r\n\r\nFocus on: architecture, algorithms, multi-GPU optimization, potential bugs, code quality.\r\nENDCODE\r\n)\" 2>/dev/null\r\n```\r\n\r\n**Note**: `--yolo` is short for `--dangerously-bypass-approvals-and-sandbox` and is safe on HPC login nodes where you have limited permissions anyway. **Do not combine --yolo with --full-auto as they are incompatible.**\r\n\r\n### Code Modification\r\n```bash\r\ncodex exec -m gpt-5 -c model_reasoning_effort=\"high\" -s workspace-write \\\r\n  --skip-git-repo-check --full-auto \"refactor @module.py to async/await\" 2>/dev/null\r\n```\r\n\r\n### Resume Session\r\n```bash\r\necho \"fix the remaining issues\" | codex exec --skip-git-repo-check resume --last 2>/dev/null\r\n```\r\n\r\n### Cross-Directory Execution\r\n```bash\r\ncodex exec -C /path/to/project -m gpt-5 -c model_reasoning_effort=\"medium\" \\\r\n  -s read-only --skip-git-repo-check --full-auto \"analyze architecture\" 2>/dev/null\r\n```\r\n\r\n### Using Profiles\r\n```bash\r\ncodex exec --profile production -c model_reasoning_effort=\"high\" \\\r\n  --full-auto \"optimize performance in @app.py\" 2>/dev/null\r\n```",
    "Configuration Management": "codex exec -c model=\"gpt-5\" -c model_reasoning_effort=\"high\" \"task\"\r\n```\r\n\r\n### Using Profiles\r\nDefine in `config.toml`:\r\n```toml\r\n[profiles.research]\r\nmodel = \"gpt-5\"\r\nmodel_reasoning_effort = \"high\"\r\nsandbox = \"read-only\"\r\n\r\n[profiles.development]\r\nmodel = \"gpt-5-codex\"\r\nsandbox = \"workspace-write\"\r\n```\r\n\r\nUse with:\r\n```bash\r\ncodex exec --profile research \"analyze codebase\"\r\n```",
    "When to Escalate": "If errors persist after troubleshooting:\r\n\r\n1. **Check documentation**:\r\n   ```bash\r\n   WebFetch https://developers.openai.com/codex/cli/reference\r\n   ```\r\n   ```bash\r\n   WebFetch https://developers.openai.com/codex/local-config#cli\r\n   ```\r\n\r\n2. **Report to user**:\r\n   - Error message verbatim\r\n   - Attempted solutions\r\n   - Configuration details\r\n   - Exit codes and stderr output\r\n\r\n3. **Request guidance**:\r\n   - Alternative approaches\r\n   - Configuration adjustments\r\n   - Manual intervention points",
    "Advanced Usage": "echo \"implement suggested refactoring\" | \\\r\n  codex exec -s workspace-write resume --last 2>/dev/null\r\n```",
    "Workflow Checklist": "**For every Codex task, follow this sequence**:\r\n\r\n1. ☐ **Detect HPC/Slurm environment**:\r\n   - Check if running on HPC cluster (look for `/home/woody/`, `/home/hpc/`, Slurm env vars)\r\n   - If HPC detected: **Always use `--yolo` flag to bypass Landlock sandbox restrictions**\r\n\r\n2. ☐ **Ask user for execution parameters** via `AskUserQuestion` (single prompt):\r\n   - Model: `gpt-5`, `gpt-5-codex`, or default\r\n   - Reasoning effort: `minimal`, `low`, `medium`, `high`\r\n\r\n3. ☐ **Determine sandbox mode** based on task:\r\n   - `read-only`: Code review, analysis, documentation\r\n   - `workspace-write`: Code modifications, file creation\r\n   - `danger-full-access`: System operations, network access\r\n   - **HPC override**: Always add `--yolo` flag (bypasses Landlock restrictions)\r\n\r\n4. ☐ **Build command** with required flags:\r\n   ```bash\r\n   codex exec [OPTIONS] \"PROMPT\"\r\n   ```\r\n   Essential flags:\r\n   - `-m <MODEL>` (if overriding default)\r\n   - `-c model_reasoning_effort=\"<LEVEL>\"`\r\n   - `-s <SANDBOX_MODE>` (skip on HPC)\r\n   - `--skip-git-repo-check` (if outside git repo)\r\n   - `-C <DIRECTORY>` (if changing workspace)\r\n   - `--full-auto` (for non-interactive execution, **cannot be used with --yolo**)\r\n\r\n   **HPC command pattern** (with `--yolo` to bypass Landlock):\r\n   ```bash\r\n   codex exec --yolo -m gpt-5 -c model_reasoning_effort=\"high\" --skip-git-repo-check \\\r\n     \"Analyze this code: $(cat /path/to/file.py)\" 2>/dev/null\r\n   ```\r\n\r\n   **Note**: `--yolo` is an alias for `--dangerously-bypass-approvals-and-sandbox` and is REQUIRED on HPC clusters to avoid Landlock sandbox errors. **Do not use --full-auto with --yolo as they are incompatible.**\r\n\r\n5. ☐ **Execute with stderr suppression**:\r\n   - Append `2>/dev/null` to hide thinking tokens\r\n   - Remove only if user requests verbose output or debugging\r\n\r\n6. ☐ **Validate execution**:\r\n   - Check exit code (0 = success)\r\n   - Summarize output for user\r\n   - Report errors with actionable solutions\r\n   - If Landlock/sandbox errors on HPC: verify `--yolo` flag was used, retry if missing\r\n\r\n7. ☐ **Inform about resume capability**:\r\n   - \"Resume this session anytime: `codex resume`\"",
    "Troubleshooting": "### File Access Blocked\r\n\r\n**Symptom**: \"shell is blocked by the sandbox\" or permission errors\r\n\r\n**Root cause**: Sandbox `read-only` mode restricts file system\r\n\r\n**Solutions** (priority order):\r\n\r\n1. **Stdin piping** (recommended):\r\n   ```bash\r\n   cat target.py | codex exec -m gpt-5 -c model_reasoning_effort=\"medium\" \\\r\n     --skip-git-repo-check --full-auto - 2>/dev/null\r\n   ```\r\n\r\n2. **Explicit permissions**:\r\n   ```bash\r\n   codex exec -m gpt-5 -s read-only \\\r\n     -c 'sandbox_permissions=[\"disk-full-read-access\"]' \\\r\n     --skip-git-repo-check --full-auto \"@file.py\" 2>/dev/null\r\n   ```\r\n\r\n3. **Upgrade sandbox**:\r\n   ```bash\r\n   codex exec -m gpt-5 -s workspace-write \\\r\n     --skip-git-repo-check --full-auto \"review @file.py\" 2>/dev/null\r\n   ```\r\n\r\n### Invalid Flag Errors\r\n\r\n**Symptom**: \"unexpected argument '--add-dir' found\"\r\n\r\n**Cause**: Flag does not exist in Codex CLI\r\n\r\n**Solution**: Use `-C <DIR>` to change directory:\r\n```bash\r\ncodex exec -C /target/dir -m gpt-5 --skip-git-repo-check \\\r\n  --full-auto \"task\" 2>/dev/null\r\n```\r\n\r\n### Exit Code Failures\r\n\r\n**Symptom**: Non-zero exit without clear message\r\n\r\n**Diagnostic steps**:\r\n1. Remove `2>/dev/null` to see full stderr\r\n2. Verify installation: `codex --version`\r\n3. Check configuration: `cat ~/.codex/config.toml`\r\n4. Test minimal command: `codex exec -m gpt-5 \"hello world\"`\r\n5. Verify model access: `codex exec --model gpt-5 \"test\"`\r\n\r\n### Model Unavailable\r\n\r\n**Symptom**: \"model not found\" or authentication errors\r\n\r\n**Solutions**:\r\n1. Check configured model: `grep model ~/.codex/config.toml`\r\n2. Verify API access: Ensure valid credentials\r\n3. Try alternative model: `-m gpt-5-codex`\r\n4. Use OSS fallback: `--oss` (requires Ollama)\r\n\r\n### Session Resume Fails\r\n\r\n**Symptom**: Cannot resume previous session\r\n\r\n**Diagnostic steps**:\r\n1. List recent sessions: `codex history`\r\n2. Verify session ID format\r\n3. Try `--last` flag instead of specific ID\r\n4. Check if session expired or was cleaned up\r\n\r\n### HPC/Slurm Sandbox Failures\r\n\r\n**Symptom**: \"Landlock sandbox error\", \"LandlockRestrict\", or all file operations fail\r\n\r\n**Root Cause**: HPC clusters use Landlock/seccomp kernel security modules that block Codex's default sandbox\r\n\r\n**✅ SOLUTION: Use the `--yolo` flag** (priority order):\r\n\r\n1. **YOLO Flag** (PRIMARY SOLUTION - WORKS ON HPC):\r\n   ```bash\r\n   # Bypasses Landlock restrictions completely\r\n   codex exec --yolo -m gpt-5 -c model_reasoning_effort=\"high\" --skip-git-repo-check \\\r\n     \"Analyze this code: $(cat /full/path/to/file.py)\" 2>/dev/null\r\n   ```\r\n\r\n   **Why this works**: `--yolo` (alias for `--dangerously-bypass-approvals-and-sandbox`) disables the Codex sandbox entirely, allowing direct file access on HPC systems. **Note: Do not use --full-auto with --yolo as they are incompatible.**\r\n\r\n2. **Manual Code Injection** (fallback if --yolo unavailable):\r\n   ```bash\r\n   # Pass code directly in prompt via command substitution\r\n   codex exec -m gpt-5 -c model_reasoning_effort=\"high\" --skip-git-repo-check --full-auto \\\r\n     \"Analyze this code comprehensively: $(cat /full/path/to/file.py)\" 2>/dev/null\r\n   ```\r\n\r\n3. **Heredoc for Long Code**:\r\n   ```bash\r\n   codex exec --yolo -m gpt-5 -c model_reasoning_effort=\"high\" --skip-git-repo-check \"$(cat <<'EOF'\r\n   Analyze the following Python code for architecture, bugs, and optimization opportunities:\r\n\r\n   $(cat /home/user/script.py)\r\n\r\n   Provide technical depth with actionable insights.\r\n   EOF\r\n   )\" 2>/dev/null\r\n   ```\r\n\r\n4. **Run on Login Node** (if compute node blocks outbound):\r\n   ```bash\r\n   # SSH to login node first, then run codex there (not in Slurm job)\r\n   ssh login.cluster.edu\r\n   codex exec --yolo -m gpt-5 --skip-git-repo-check \"analyze @file.py\" 2>/dev/null\r\n   ```\r\n\r\n5. **Use Apptainer/Singularity** (if cluster supports):\r\n   ```bash\r\n   # Build image with Codex installed, then run via Slurm\r\n   singularity exec codex.sif codex exec --yolo -m gpt-5 \"task\"\r\n   ```\r\n\r\n**Best Practice for HPC**:\r\n- **Always use `--yolo` flag on HPC clusters** - it's safe on login nodes where you already have limited permissions\r\n- Run analysis on login nodes, submit only heavy compute jobs to Slurm\r\n- Keep code files on shared filesystem readable from login nodes\r\n- Combine `--yolo` with `$(cat file.py)` for maximum compatibility",
    "Resume Behavior": "codex exec -c model_reasoning_effort=\"high\" resume --last\r\n```",
    "Prerequisites": "- Codex CLI installed and configured (`~/.codex/config.toml`)\r\n- Verify availability: `codex --version` on first use per session",
    "Common Workflows": "### Code Review Workflow\r\n1. Ask user: model + reasoning effort\r\n2. Run read-only analysis\r\n3. Present findings\r\n4. If changes needed: resume with workspace-write\r\n5. Validate changes\r\n6. Inform about resume capability\r\n\r\n### Refactoring Workflow\r\n1. Ask user: model + reasoning effort\r\n2. Analyze current code (read-only)\r\n3. Propose changes\r\n4. Get user approval\r\n5. Apply changes (workspace-write)\r\n6. Run validation/tests\r\n7. Report results\r\n\r\n### Security Audit Workflow\r\n1. Use high reasoning effort\r\n2. Run comprehensive analysis (read-only)\r\n3. Document findings\r\n4. Propose fixes\r\n5. Apply fixes if approved (workspace-write)\r\n6. Re-audit to verify\r\n7. Generate report",
    "CLI Reference": "### Core Flags\r\n\r\n| Flag | Values | When to Use |\r\n|------|--------|-------------|\r\n| `-m, --model` | `gpt-5`, `gpt-5-codex` | Override default model |\r\n| `-c, --config` | `key=value` | Runtime config override (repeatable) |\r\n| `-s, --sandbox` | `read-only`, `workspace-write`, `danger-full-access` | Set execution permissions |\r\n| `--yolo` | flag | **REQUIRED on HPC** - Bypasses all sandbox restrictions (alias for `--dangerously-bypass-approvals-and-sandbox`). **Cannot be used with --full-auto** |\r\n| `-C, --cd` | `path` | Change workspace directory |\r\n| `--skip-git-repo-check` | flag | Allow execution outside git repos |\r\n| `--full-auto` | flag | Non-interactive mode (workspace-write + approvals on failure). **Cannot be used with --yolo** |\r\n| `-p, --profile` | `string` | Load configuration profile from config.toml |\r\n| `--json` | flag | JSON event output (CI/CD pipelines) |\r\n| `-o, --output-last-message` | `path` | Write final message to file |\r\n| `-i, --image` | `path[,path...]` | Attach images (repeatable or comma-separated) |\r\n| `--oss` | flag | Use local open-source model (requires Ollama) |\r\n\r\n### Configuration Options\r\n\r\n**Model Reasoning Effort** (`-c model_reasoning_effort=\"<LEVEL>\"`):\r\n- `minimal`: Quick tasks, simple queries\r\n- `low`: Standard operations, routine refactoring\r\n- `medium`: Complex analysis, architectural decisions (default)\r\n- `high`: Critical code, security audits, complex algorithms\r\n\r\n**Model Verbosity** (`-c model_verbosity=\"<LEVEL>\"`):\r\n- `low`: Minimal output\r\n- `medium`: Balanced detail (default)\r\n- `high`: Verbose explanations\r\n\r\n**Approval Prompts** (`-c approvals=\"<WHEN>\"`):\r\n- `on-request`: Before any tool use\r\n- `on-failure`: Only on errors (default for `--full-auto`)\r\n- `untrusted`: Minimal prompts\r\n- `never`: No interruptions (use with caution)"
  },
  "content": "> **🔥 HPC QUICK TIP**: On HPC clusters (e.g., `/home/woody/`, `/home/hpc/`), **ALWAYS add `--yolo` flag** to avoid Landlock sandbox errors. Example: `codex exec --yolo -m gpt-5 ...`\r\n\r\n### Read-Only Analysis\r\n```bash\r\ncodex exec -m gpt-5 -c model_reasoning_effort=\"medium\" -s read-only \\\r\n  --skip-git-repo-check --full-auto \"review @file.py for security issues\" 2>/dev/null\r\n```\r\n\r\n### Stdin Input (bypasses sandbox file restrictions)\r\n```bash\r\ncat file.py | codex exec -m gpt-5 -c model_reasoning_effort=\"low\" \\\r\n  --skip-git-repo-check --full-auto - 2>/dev/null\r\n```\r\n**Note**: Stdin with `-` flag may not be supported in all Codex CLI versions.\r\n\r\n### HPC/Slurm Environment (YOLO Mode - Bypass Landlock)\r\nWhen running on HPC clusters with Landlock security restrictions, use the `--yolo` flag:\r\n\r\n```bash\r\ncodex exec --yolo -m gpt-5 -c model_reasoning_effort=\"high\" --skip-git-repo-check \\\r\n  \"Analyze this code: $(cat /path/to/file.py)\" 2>/dev/null\r\n```\r\n\r\n**Alternative: Manual Code Injection** (if --yolo is unavailable):\r\n```bash\r\n\r\n### Config File Location\r\n`~/.codex/config.toml`\r\n\r\n### Runtime Overrides\r\n```bash\r\ncodex exec -c model=\"gpt-5\" \"task\"\r\n\r\n\r\n**Automatic inheritance**:\r\n- Model selection\r\n- Reasoning effort\r\n- Sandbox mode\r\n- Configuration overrides\r\n\r\n**Resume syntax**:\r\n```bash\r\ncodex exec resume --last\r\n\r\ncodex exec resume --last \"continue with next steps\"\r\n\r\necho \"new instructions\" | codex exec resume --last 2>/dev/null\r\n\r\ncodex exec resume <SESSION_ID> \"follow-up task\"\r\n```\r\n\r\n**Flag injection** (between `exec` and `resume`):\r\n```bash\r\n\r\n### CI/CD Integration\r\n```bash\r\ncodex exec --json -o result.txt -m gpt-5 \\\r\n  -c model_reasoning_effort=\"medium\" \\\r\n  --skip-git-repo-check --full-auto \\\r\n  \"run security audit on changed files\" 2>/dev/null\r\n```\r\n\r\n### Batch Processing\r\n```bash\r\nfor file in *.py; do\r\n  cat \"$file\" | codex exec -m gpt-5 -c model_reasoning_effort=\"low\" \\\r\n    --skip-git-repo-check --full-auto \"lint and format\" - 2>/dev/null\r\ndone\r\n```\r\n\r\n### Multi-Step Workflows\r\n```bash\r\ncodex exec -m gpt-5 -c model_reasoning_effort=\"high\" -s read-only \\\r\n  --full-auto \"analyze @codebase for architectural issues\" 2>/dev/null",
  "id": "codex",
  "name": "codex",
  "description": "Executes OpenAI Codex CLI for code analysis, refactoring, and automated editing. Activates when users mention codex commands, code review requests, or automated code transformations requiring advanced reasoning models."
}

---
name: codex
description: Executes OpenAI Codex CLI for code analysis, refactoring, and automated editing. Activates when users mention codex commands, code review requests, or automated code transformations requiring advanced reasoning models.
---

# Codex Execution Skill

## Prerequisites
- Codex CLI installed and configured (`~/.codex/config.toml`)
- Verify availability: `codex --version` on first use per session

## Workflow Checklist

**For every Codex task, follow this sequence**:

1. ☐ **Detect HPC/Slurm environment**:
   - Check if running on HPC cluster (look for `/home/woody/`, `/home/hpc/`, Slurm env vars)
   - If HPC detected: **Always use `--yolo` flag to bypass Landlock sandbox restrictions**

2. ☐ **Ask user for execution parameters** via `AskUserQuestion` (single prompt):
   - Model: `gpt-5`, `gpt-5-codex`, or default
   - Reasoning effort: `minimal`, `low`, `medium`, `high`

3. ☐ **Determine sandbox mode** based on task:
   - `read-only`: Code review, analysis, documentation
   - `workspace-write`: Code modifications, file creation
   - `danger-full-access`: System operations, network access
   - **HPC override**: Always add `--yolo` flag (bypasses Landlock restrictions)

4. ☐ **Build command** with required flags:
   ```bash
   codex exec [OPTIONS] "PROMPT"
   ```
   Essential flags:
   - `-m <MODEL>` (if overriding default)
   - `-c model_reasoning_effort="<LEVEL>"`
   - `-s <SANDBOX_MODE>` (skip on HPC)
   - `--skip-git-repo-check` (if outside git repo)
   - `-C <DIRECTORY>` (if changing workspace)
   - `--full-auto` (for non-interactive execution, **cannot be used with --yolo**)

   **HPC command pattern** (with `--yolo` to bypass Landlock):
   ```bash
   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
     "Analyze this code: $(cat /path/to/file.py)" 2>/dev/null
   ```

   **Note**: `--yolo` is an alias for `--dangerously-bypass-approvals-and-sandbox` and is REQUIRED on HPC clusters to avoid Landlock sandbox errors. **Do not use --full-auto with --yolo as they are incompatible.**

5. ☐ **Execute with stderr suppression**:
   - Append `2>/dev/null` to hide thinking tokens
   - Remove only if user requests verbose output or debugging

6. ☐ **Validate execution**:
   - Check exit code (0 = success)
   - Summarize output for user
   - Report errors with actionable solutions
   - If Landlock/sandbox errors on HPC: verify `--yolo` flag was used, retry if missing

7. ☐ **Inform about resume capability**:
   - "Resume this session anytime: `codex resume`"

## Command Patterns

> **🔥 HPC QUICK TIP**: On HPC clusters (e.g., `/home/woody/`, `/home/hpc/`), **ALWAYS add `--yolo` flag** to avoid Landlock sandbox errors. Example: `codex exec --yolo -m gpt-5 ...`

### Read-Only Analysis
```bash
codex exec -m gpt-5 -c model_reasoning_effort="medium" -s read-only \
  --skip-git-repo-check --full-auto "review @file.py for security issues" 2>/dev/null
```

### Stdin Input (bypasses sandbox file restrictions)
```bash
cat file.py | codex exec -m gpt-5 -c model_reasoning_effort="low" \
  --skip-git-repo-check --full-auto - 2>/dev/null
```
**Note**: Stdin with `-` flag may not be supported in all Codex CLI versions.

### HPC/Slurm Environment (YOLO Mode - Bypass Landlock)
When running on HPC clusters with Landlock security restrictions, use the `--yolo` flag:

```bash
# Primary solution: --yolo flag bypasses Landlock sandbox
codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
  "Analyze this code: $(cat /path/to/file.py)" 2>/dev/null
```

**Alternative: Manual Code Injection** (if --yolo is unavailable):
```bash
# Capture code content and pass directly in prompt
codex exec -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check --full-auto \
  "Analyze this Python code: $(cat file.py)" 2>/dev/null
```
Or for large files, use heredoc:
```bash
codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check "$(cat <<'ENDCODE'
Analyze the following code comprehensively:

$(cat file.py)

Focus on: architecture, algorithms, multi-GPU optimization, potential bugs, code quality.
ENDCODE
)" 2>/dev/null
```

**Note**: `--yolo` is short for `--dangerously-bypass-approvals-and-sandbox` and is safe on HPC login nodes where you have limited permissions anyway. **Do not combine --yolo with --full-auto as they are incompatible.**

### Code Modification
```bash
codex exec -m gpt-5 -c model_reasoning_effort="high" -s workspace-write \
  --skip-git-repo-check --full-auto "refactor @module.py to async/await" 2>/dev/null
```

### Resume Session
```bash
echo "fix the remaining issues" | codex exec --skip-git-repo-check resume --last 2>/dev/null
```

### Cross-Directory Execution
```bash
codex exec -C /path/to/project -m gpt-5 -c model_reasoning_effort="medium" \
  -s read-only --skip-git-repo-check --full-auto "analyze architecture" 2>/dev/null
```

### Using Profiles
```bash
codex exec --profile production -c model_reasoning_effort="high" \
  --full-auto "optimize performance in @app.py" 2>/dev/null
```

## CLI Reference

### Core Flags

| Flag | Values | When to Use |
|------|--------|-------------|
| `-m, --model` | `gpt-5`, `gpt-5-codex` | Override default model |
| `-c, --config` | `key=value` | Runtime config override (repeatable) |
| `-s, --sandbox` | `read-only`, `workspace-write`, `danger-full-access` | Set execution permissions |
| `--yolo` | flag | **REQUIRED on HPC** - Bypasses all sandbox restrictions (alias for `--dangerously-bypass-approvals-and-sandbox`). **Cannot be used with --full-auto** |
| `-C, --cd` | `path` | Change workspace directory |
| `--skip-git-repo-check` | flag | Allow execution outside git repos |
| `--full-auto` | flag | Non-interactive mode (workspace-write + approvals on failure). **Cannot be used with --yolo** |
| `-p, --profile` | `string` | Load configuration profile from config.toml |
| `--json` | flag | JSON event output (CI/CD pipelines) |
| `-o, --output-last-message` | `path` | Write final message to file |
| `-i, --image` | `path[,path...]` | Attach images (repeatable or comma-separated) |
| `--oss` | flag | Use local open-source model (requires Ollama) |

### Configuration Options

**Model Reasoning Effort** (`-c model_reasoning_effort="<LEVEL>"`):
- `minimal`: Quick tasks, simple queries
- `low`: Standard operations, routine refactoring
- `medium`: Complex analysis, architectural decisions (default)
- `high`: Critical code, security audits, complex algorithms

**Model Verbosity** (`-c model_verbosity="<LEVEL>"`):
- `low`: Minimal output
- `medium`: Balanced detail (default)
- `high`: Verbose explanations

**Approval Prompts** (`-c approvals="<WHEN>"`):
- `on-request`: Before any tool use
- `on-failure`: Only on errors (default for `--full-auto`)
- `untrusted`: Minimal prompts
- `never`: No interruptions (use with caution)

## Configuration Management

### Config File Location
`~/.codex/config.toml`

### Runtime Overrides
```bash
# Override single setting
codex exec -c model="gpt-5" "task"

# Override multiple settings
codex exec -c model="gpt-5" -c model_reasoning_effort="high" "task"
```

### Using Profiles
Define in `config.toml`:
```toml
[profiles.research]
model = "gpt-5"
model_reasoning_effort = "high"
sandbox = "read-only"

[profiles.development]
model = "gpt-5-codex"
sandbox = "workspace-write"
```

Use with:
```bash
codex exec --profile research "analyze codebase"
```

## Resume Behavior

**Automatic inheritance**:
- Model selection
- Reasoning effort
- Sandbox mode
- Configuration overrides

**Resume syntax**:
```bash
# Resume last session
codex exec resume --last

# Resume with new prompt
codex exec resume --last "continue with next steps"

# Resume via stdin
echo "new instructions" | codex exec resume --last 2>/dev/null

# Resume specific session
codex exec resume <SESSION_ID> "follow-up task"
```

**Flag injection** (between `exec` and `resume`):
```bash
# Change reasoning effort for resumed session
codex exec -c model_reasoning_effort="high" resume --last
```

## Error Handling

### Validation Loop
1. Execute command
2. Check exit code (non-zero = failure)
3. Report error with context
4. Ask user for direction via `AskUserQuestion`
5. Retry with adjustments or escalate

### Permission Requests
Before using high-impact flags, request user approval via `AskUserQuestion`:
- `--full-auto`: Automated execution
- `-s danger-full-access`: System-wide access
- `--yolo` / `--dangerously-bypass-approvals-and-sandbox`:
  - **HPC clusters**: No approval needed (required for operation)
  - **Personal machines**: Request approval (full system access)

### Partial Success Handling
When output contains warnings:
1. Summarize successful operations
2. Detail failures with context
3. Use `AskUserQuestion` to determine next steps
4. Propose specific adjustments

## Troubleshooting

### File Access Blocked

**Symptom**: "shell is blocked by the sandbox" or permission errors

**Root cause**: Sandbox `read-only` mode restricts file system

**Solutions** (priority order):

1. **Stdin piping** (recommended):
   ```bash
   cat target.py | codex exec -m gpt-5 -c model_reasoning_effort="medium" \
     --skip-git-repo-check --full-auto - 2>/dev/null
   ```

2. **Explicit permissions**:
   ```bash
   codex exec -m gpt-5 -s read-only \
     -c 'sandbox_permissions=["disk-full-read-access"]' \
     --skip-git-repo-check --full-auto "@file.py" 2>/dev/null
   ```

3. **Upgrade sandbox**:
   ```bash
   codex exec -m gpt-5 -s workspace-write \
     --skip-git-repo-check --full-auto "review @file.py" 2>/dev/null
   ```

### Invalid Flag Errors

**Symptom**: "unexpected argument '--add-dir' found"

**Cause**: Flag does not exist in Codex CLI

**Solution**: Use `-C <DIR>` to change directory:
```bash
codex exec -C /target/dir -m gpt-5 --skip-git-repo-check \
  --full-auto "task" 2>/dev/null
```

### Exit Code Failures

**Symptom**: Non-zero exit without clear message

**Diagnostic steps**:
1. Remove `2>/dev/null` to see full stderr
2. Verify installation: `codex --version`
3. Check configuration: `cat ~/.codex/config.toml`
4. Test minimal command: `codex exec -m gpt-5 "hello world"`
5. Verify model access: `codex exec --model gpt-5 "test"`

### Model Unavailable

**Symptom**: "model not found" or authentication errors

**Solutions**:
1. Check configured model: `grep model ~/.codex/config.toml`
2. Verify API access: Ensure valid credentials
3. Try alternative model: `-m gpt-5-codex`
4. Use OSS fallback: `--oss` (requires Ollama)

### Session Resume Fails

**Symptom**: Cannot resume previous session

**Diagnostic steps**:
1. List recent sessions: `codex history`
2. Verify session ID format
3. Try `--last` flag instead of specific ID
4. Check if session expired or was cleaned up

### HPC/Slurm Sandbox Failures

**Symptom**: "Landlock sandbox error", "LandlockRestrict", or all file operations fail

**Root Cause**: HPC clusters use Landlock/seccomp kernel security modules that block Codex's default sandbox

**✅ SOLUTION: Use the `--yolo` flag** (priority order):

1. **YOLO Flag** (PRIMARY SOLUTION - WORKS ON HPC):
   ```bash
   # Bypasses Landlock restrictions completely
   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
     "Analyze this code: $(cat /full/path/to/file.py)" 2>/dev/null
   ```

   **Why this works**: `--yolo` (alias for `--dangerously-bypass-approvals-and-sandbox`) disables the Codex sandbox entirely, allowing direct file access on HPC systems. **Note: Do not use --full-auto with --yolo as they are incompatible.**

2. **Manual Code Injection** (fallback if --yolo unavailable):
   ```bash
   # Pass code directly in prompt via command substitution
   codex exec -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check --full-auto \
     "Analyze this code comprehensively: $(cat /full/path/to/file.py)" 2>/dev/null
   ```

3. **Heredoc for Long Code**:
   ```bash
   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check "$(cat <<'EOF'
   Analyze the following Python code for architecture, bugs, and optimization opportunities:

   $(cat /home/user/script.py)

   Provide technical depth with actionable insights.
   EOF
   )" 2>/dev/null
   ```

4. **Run on Login Node** (if compute node blocks outbound):
   ```bash
   # SSH to login node first, then run codex there (not in Slurm job)
   ssh login.cluster.edu
   codex exec --yolo -m gpt-5 --skip-git-repo-check "analyze @file.py" 2>/dev/null
   ```

5. **Use Apptainer/Singularity** (if cluster supports):
   ```bash
   # Build image with Codex installed, then run via Slurm
   singularity exec codex.sif codex exec --yolo -m gpt-5 "task"
   ```

**Best Practice for HPC**:
- **Always use `--yolo` flag on HPC clusters** - it's safe on login nodes where you already have limited permissions
- Run analysis on login nodes, submit only heavy compute jobs to Slurm
- Keep code files on shared filesystem readable from login nodes
- Combine `--yolo` with `$(cat file.py)` for maximum compatibility

## Best Practices

### Reasoning Effort Selection
- **minimal**: Syntax fixes, simple renaming
- **low**: Standard refactoring, basic analysis
- **medium**: Complex refactoring, architecture review
- **high**: Security audits, algorithm optimization, critical bugs

### Sandbox Mode Selection
- **read-only**: Default for any analysis or review
- **workspace-write**: File modifications only
- **danger-full-access**: Network operations, system commands (rare)

### Stderr Suppression
- **Always use `2>/dev/null`** unless:
  - User explicitly requests thinking tokens
  - Debugging failed commands
  - Troubleshooting configuration issues

### Profile Usage
Create profiles for common workflows:
- `review`: High reasoning, read-only
- `refactor`: Medium reasoning, workspace-write
- `quick`: Low reasoning, read-only
- `security`: High reasoning, workspace-write

### Stdin vs File Reference
- **Stdin**: Single file analysis, avoids permissions
- **File reference**: Multi-file context, codebase-wide changes

## Safety Guidelines

**HPC Clusters - `--yolo` is SAFE and REQUIRED**:
- HPC login nodes already have strict permissions (no root access, no network modification)
- `--yolo` bypasses Codex sandbox but you still operate within HPC user restrictions
- Always use `--yolo` on HPC to avoid Landlock errors

**General Use - Exercise Caution**:
- Don't use `--yolo` on unrestricted systems (your laptop, cloud VMs with full sudo)
- Prefer `--full-auto` + `-s workspace-write` for normal development

**Always verify before**:
- Using `danger-full-access` sandbox (outside HPC)
- Disabling approval prompts on production systems
- Running with `--yolo` on personal machines with sudo access

**Ask user approval for**:
- First-time `workspace-write` usage
- System-wide access requests
- Destructive operations (deletions, migrations)

## Advanced Usage

### CI/CD Integration
```bash
codex exec --json -o result.txt -m gpt-5 \
  -c model_reasoning_effort="medium" \
  --skip-git-repo-check --full-auto \
  "run security audit on changed files" 2>/dev/null
```

### Batch Processing
```bash
for file in *.py; do
  cat "$file" | codex exec -m gpt-5 -c model_reasoning_effort="low" \
    --skip-git-repo-check --full-auto "lint and format" - 2>/dev/null
done
```

### Multi-Step Workflows
```bash
# Step 1: Analysis
codex exec -m gpt-5 -c model_reasoning_effort="high" -s read-only \
  --full-auto "analyze @codebase for architectural issues" 2>/dev/null

# Step 2: Resume with changes
echo "implement suggested refactoring" | \
  codex exec -s workspace-write resume --last 2>/dev/null
```

## When to Escalate

If errors persist after troubleshooting:

1. **Check documentation**:
   ```bash
   WebFetch https://developers.openai.com/codex/cli/reference
   ```
   ```bash
   WebFetch https://developers.openai.com/codex/local-config#cli
   ```

2. **Report to user**:
   - Error message verbatim
   - Attempted solutions
   - Configuration details
   - Exit codes and stderr output

3. **Request guidance**:
   - Alternative approaches
   - Configuration adjustments
   - Manual intervention points

## Model Selection Guide

| Task Type | Recommended Model | Reasoning Effort |
|-----------|------------------|------------------|
| Quick syntax fixes | `gpt-5` | minimal |
| Code review | `gpt-5` | medium |
| Refactoring | `gpt-5-codex` | medium |
| Architecture analysis | `gpt-5` | high |
| Security audit | `gpt-5` | high |
| Algorithm optimization | `gpt-5-codex` | high |
| Documentation generation | `gpt-5` | low |

## Common Workflows

### Code Review Workflow
1. Ask user: model + reasoning effort
2. Run read-only analysis
3. Present findings
4. If changes needed: resume with workspace-write
5. Validate changes
6. Inform about resume capability

### Refactoring Workflow
1. Ask user: model + reasoning effort
2. Analyze current code (read-only)
3. Propose changes
4. Get user approval
5. Apply changes (workspace-write)
6. Run validation/tests
7. Report results

### Security Audit Workflow
1. Use high reasoning effort
2. Run comprehensive analysis (read-only)
3. Document findings
4. Propose fixes
5. Apply fixes if approved (workspace-write)
6. Re-audit to verify
7. Generate report