using-codex

What this skill does

# Using Codex for Testing & Automation

**Always use `gpt-5-codex` with different reasoning efforts.** Never use o3 or 4o.

**⚠️ IMPORTANT: Git Repository Requirement**
- Codex requires a Git repository by default to prevent destructive changes
- **If NOT in a git repo**: Add `--skip-git-repo-check` to every command
- **If IN a git repo**: Git check passes automatically

```bash
# In git repo - works fine
codex exec --model gpt-5-codex "task"

# NOT in git repo - need flag
codex exec --model gpt-5-codex --skip-git-repo-check "task"
```

## Official Documentation

- **Main Repo**: https://github.com/openai/codex
- **Non-interactive Mode**: https://github.com/openai/codex/blob/main/docs/exec.md
- **Config Guide**: https://github.com/openai/codex/blob/main/docs/config.md
- **Sandbox & Approvals**: https://github.com/openai/codex/blob/main/docs/sandbox.md

## Core Patterns

**Note**: All examples assume you're in a git repo. If not, add `--skip-git-repo-check` to every command.

### 1. Basic Execution (Read-Only)

```bash
# In git repo
codex exec --model gpt-5-codex "analyze test failures"

# Not in git repo
codex exec --model gpt-5-codex --skip-git-repo-check "analyze test failures"
```

### 2. With File Edits (Workspace-Write)

```bash
# In git repo
codex exec --model gpt-5-codex --full-auto "fix failing tests"

# Not in git repo
codex exec --model gpt-5-codex --skip-git-repo-check --full-auto "fix failing tests"
```

### 3. With Web Search (Critical for Up-to-Date Info)

```bash
# In git repo
codex exec \
  --model gpt-5-codex \
  --config tools.web_search=true \
  "research best practices for async Rust and apply to this codebase"

# Not in git repo
codex exec \
  --model gpt-5-codex \
  --skip-git-repo-check \
  --config tools.web_search=true \
  "research best practices for async Rust and apply to this codebase"
```

### 4. Streaming Output (JSON Lines)

```bash
# Stream events as they happen
codex exec --model gpt-5-codex --json "run all tests" > output.jsonl

# Watch in real-time
codex exec --model gpt-5-codex --json "analyze errors" | jq -r '.type'
```

Event types you'll see:
- `thread.started` - session begins (contains `thread_id`)
- `turn.started` - agent starts processing
- `item.completed` - reasoning, commands, file changes
- `turn.completed` - includes token usage

### 5. Multi-Turn Conversations (Save Conversation ID)

```bash
# First turn - save JSON output
codex exec --model gpt-5-codex --json "run tests" 2>&1 > output.jsonl

# Extract thread_id
cat output.jsonl | jq -r 'select(.type=="thread.started") | .thread_id' > thread_id.txt

# Resume with the same conversation (note: --model not needed for resume)
THREAD_ID=$(cat thread_id.txt)
echo "fix those failures" | codex exec resume $THREAD_ID
echo "verify all tests pass now" | codex exec resume $THREAD_ID

# Or just resume last session (no thread_id needed)
echo "now check code coverage" | codex exec resume --last
```

## Reasoning Effort Configuration

**Always use `gpt-5-codex`** - adjust reasoning effort based on task complexity:

### Quick Tasks (Low Reasoning)

```bash
codex exec \
  --model gpt-5-codex \
  --config model_reasoning_effort=low \
  "run pytest and report failures"
```

### Standard Tasks (Medium Reasoning - Default)

```bash
codex exec \
  --model gpt-5-codex \
  --config model_reasoning_effort=medium \
  "analyze test failures and suggest fixes"
```

### Complex Tasks (High Reasoning)

```bash
codex exec \
  --model gpt-5-codex \
  --config model_reasoning_effort=high \
  "debug race condition in concurrent tests"
```

### Deep Analysis (Detailed Reasoning Summary)

```bash
codex exec \
  --model gpt-5-codex \
  --config model_reasoning_effort=high \
  --config model_reasoning_summary=detailed \
  "analyze architecture for security vulnerabilities"
```

## Sandbox Modes

### read-only (Default - Safest)

```bash
codex exec --model gpt-5-codex "analyze code coverage"
```

### workspace-write (Allow File Edits)

```bash
codex exec --model gpt-5-codex --full-auto "fix type errors"
# Or explicitly:
codex exec --model gpt-5-codex --sandbox workspace-write "fix errors"
```

### danger-full-access (Full Disk + Network)

```bash
codex exec \
  --model gpt-5-codex \
  --sandbox danger-full-access \
  "run integration tests against staging"
```

## Command-Line Configuration (Flexible)

**Use `--config key=value` for maximum flexibility.** Don't use profiles.

### Multiple Configs in One Command

```bash
codex exec \
  --model gpt-5-codex \
  --config model_reasoning_effort=high \
  --config model_reasoning_summary=detailed \
  --config tools.web_search=true \
  --config approval_policy=never \
  --config hide_agent_reasoning=true \
  "research and implement caching strategy"
```

### Common Config Combinations

```bash
# CI/CD: fast, no prompts, hide reasoning
codex exec \
  --model gpt-5-codex \
  --config model_reasoning_effort=low \
  --config approval_policy=never \
  --config hide_agent_reasoning=true \
  "run test suite"

# Deep analysis: high reasoning, web search, detailed summary
codex exec \
  --model gpt-5-codex \
  --config model_reasoning_effort=high \
  --config model_reasoning_summary=detailed \
  --config tools.web_search=true \
  "analyze security of authentication flow"

# File editing: workspace-write, medium reasoning
codex exec \
  --model gpt-5-codex \
  --full-auto \
  --config model_reasoning_effort=medium \
  "refactor database module for better testability"
```

## Structured Output (JSON Schema)

Get structured data back:

```bash
# Define schema
cat > schema.json << 'EOF'
{
  "type": "object",
  "properties": {
    "test_failures": {
      "type": "array",
      "items": {"type": "string"}
    },
    "coverage_percent": {"type": "number"},
    "needs_attention": {
      "type": "array",
      "items": {"type": "string"}
    }
  },
  "required": ["test_failures", "coverage_percent"],
  "additionalProperties": false
}
EOF

# Get structured output
codex exec \
  --model gpt-5-codex \
  --output-schema schema.json \
  "analyze test suite" -o results.json

# Parse results
cat results.json | jq '.test_failures'
```

## Web Search (Important!)

**Enable web search for up-to-date information:**

```bash
# Research latest best practices
codex exec \
  --model gpt-5-codex \
  --config tools.web_search=true \
  --config model_reasoning_effort=medium \
  "research 2025 best practices for React testing and apply here"

# Find current library versions
codex exec \
  --model gpt-5-codex \
  --config tools.web_search=true \
  "check if we're using latest stable versions of dependencies"

# Debug with latest docs
codex exec \
  --model gpt-5-codex \
  --full-auto \
  --config tools.web_search=true \
  --config model_reasoning_effort=high \
  "research this error message and fix it"
```

## Streaming + Multi-Turn Pattern

**Powerful pattern for complex workflows:**

```bash
#!/bin/bash
# Complex multi-turn workflow with streaming

# Turn 1: Initial analysis
echo "=== Turn 1: Analyzing Tests ==="
codex exec \
  --model gpt-5-codex \
  --json \
  --config model_reasoning_effort=medium \
  "run all tests and analyze failures" 2>&1 > turn1.jsonl

# Extract thread_id
THREAD_ID=$(cat turn1.jsonl | jq -r 'select(.type=="thread.started") | .thread_id')
echo "Thread ID: $THREAD_ID"

# Turn 2: Fix failures
echo -e "\n=== Turn 2: Fixing Failures ==="
echo "fix all test failures" | codex exec \
  --json \
  --full-auto \
  --config model_reasoning_effort=high \
  resume $THREAD_ID 2>&1 > turn2.jsonl

# Turn 3: Verify fixes
echo -e "\n=== Turn 3: Verifying Fixes ==="
echo "run tests again and confirm all pass" | codex exec \
  --json \
  resume $THREAD_ID 2>&1 > turn3.jsonl

# Extract final result
echo -e "\n=== Final Result ==="
cat turn3.jsonl | jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text' | tail -1
```

## Practical Examples

### Example 1: CI/CD Test Runner

```bash
# Fast, no prompts, structured output
codex exec \
  --model gpt-