codex

What this skill does

# 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 esc