claude-task-master/docs/examples/codex-cli-usage.md

# Codex CLI Provider Usage Examples

This guide provides practical examples of using Task Master with the Codex CLI provider.

## Prerequisites

Before using these examples, ensure you have:

```bash
# 1. Codex CLI installed
npm install -g @openai/codex

# 2. Authenticated with ChatGPT
codex login

# 3. Codex CLI configured as your provider
task-master models --set-main gpt-5-codex --codex-cli
```

## Example 1: Basic Task Creation

Use Codex CLI to create tasks from a simple description:

```bash
# Add a task with AI-powered enhancement
task-master add-task --prompt="Implement user authentication with JWT" --research
```

**What happens**:
1. Task Master sends your prompt to GPT-5-Codex via the CLI
2. The AI analyzes your request and generates a detailed task
3. The task is added to your `.taskmaster/tasks/tasks.json`
4. OAuth credentials are automatically used (no API key needed)

## Example 2: Parsing a Product Requirements Document

Create a comprehensive task list from a PRD:

```bash
# Create your PRD
cat > my-feature.txt <<EOF
# User Profile Feature

## Requirements
1. Users can view their profile
2. Users can edit their information
3. Profile pictures can be uploaded
4. Email verification required

## Technical Constraints
- Use React for frontend
- Node.js/Express backend
- PostgreSQL database
EOF

# Parse with Codex CLI
task-master parse-prd my-feature.txt --num-tasks 12
```

**What happens**:
1. GPT-5-Codex reads and analyzes your PRD
2. Generates structured tasks with dependencies
3. Creates subtasks for complex items
4. Saves everything to `.taskmaster/tasks/`

## Example 3: Expanding Tasks with Research

Break down a complex task into detailed subtasks:

```bash
# First, show your current tasks
task-master list

# Expand a specific task (e.g., task 1.2)
task-master expand --id=1.2 --research --force
```

**What happens**:
1. Codex CLI uses GPT-5 for research-level analysis
2. Breaks down the task into logical subtasks
3. Adds implementation details and test strategies
4. Updates the task with dependency information

## Example 4: Analyzing Project Complexity

Get AI-powered insights into your project's task complexity:

```bash
# Analyze all tasks
task-master analyze-complexity --research

# View the complexity report
task-master complexity-report
```

**What happens**:
1. GPT-5 analyzes each task's scope and requirements
2. Assigns complexity scores and estimates subtask counts
3. Generates a detailed report
4. Saves to `.taskmaster/reports/task-complexity-report.json`

## Example 5: Using Custom Codex CLI Settings

Configure Codex CLI behavior for different commands:

```json
// In .taskmaster/config.json
{
  "models": {
    "main": {
      "provider": "codex-cli",
      "modelId": "gpt-5-codex",
      "maxTokens": 128000,
      "temperature": 0.2
    }
  },
  "codexCli": {
    "allowNpx": true,
    "approvalMode": "on-failure",
    "sandboxMode": "workspace-write",
    "commandSpecific": {
      "parse-prd": {
        "verbose": true,
        "approvalMode": "never"
      },
      "expand": {
        "sandboxMode": "read-only",
        "verbose": true
      }
    }
  }
}
```

```bash
# Now parse-prd runs with verbose output and no approvals
task-master parse-prd requirements.txt

# Expand runs with read-only mode
task-master expand --id=2.1
```

## Example 6: Workflow - Building a Feature End-to-End

Complete workflow from PRD to implementation tracking:

```bash
# Step 1: Initialize project
task-master init

# Step 2: Set up Codex CLI
task-master models --set-main gpt-5-codex --codex-cli
task-master models --set-fallback gpt-5 --codex-cli

# Step 3: Create PRD
cat > feature-prd.txt <<EOF
# Authentication System

Implement a complete authentication system with:
- User registration
- Email verification
- Password reset
- Two-factor authentication
- Session management
EOF

# Step 4: Parse PRD into tasks
task-master parse-prd feature-prd.txt --num-tasks 8

# Step 5: Analyze complexity
task-master analyze-complexity --research

# Step 6: Expand complex tasks
task-master expand --all --research

# Step 7: Start working
task-master next
# Shows: Task 1.1: User registration database schema

# Step 8: Mark completed as you work
task-master set-status --id=1.1 --status=done

# Step 9: Continue to next task
task-master next
```

## Example 7: Multi-Role Configuration

Use Codex CLI for main tasks, Perplexity for research:

```json
// In .taskmaster/config.json
{
  "models": {
    "main": {
      "provider": "codex-cli",
      "modelId": "gpt-5-codex",
      "maxTokens": 128000,
      "temperature": 0.2
    },
    "research": {
      "provider": "perplexity",
      "modelId": "sonar-pro",
      "maxTokens": 8700,
      "temperature": 0.1
    },
    "fallback": {
      "provider": "codex-cli",
      "modelId": "gpt-5",
      "maxTokens": 128000,
      "temperature": 0.2
    }
  }
}
```

```bash
# Main task operations use GPT-5-Codex
task-master add-task --prompt="Build REST API endpoint"

# Research operations use Perplexity
task-master analyze-complexity --research

# Fallback to GPT-5 if needed
task-master expand --id=3.2 --force
```

## Example 8: Troubleshooting Common Issues

### Issue: Codex CLI not found

```bash
# Check if Codex is installed
codex --version

# If not found, install globally
npm install -g @openai/codex

# Or enable npx fallback in config
cat >> .taskmaster/config.json <<EOF
{
  "codexCli": {
    "allowNpx": true
  }
}
EOF
```

### Issue: Not authenticated

```bash
# Check auth status
codex
# Use /about command to see auth info

# Re-authenticate if needed
codex login
```

### Issue: Want more verbose output

```bash
# Enable verbose mode in config
cat >> .taskmaster/config.json <<EOF
{
  "codexCli": {
    "verbose": true
  }
}
EOF

# Or for specific commands
task-master parse-prd my-prd.txt
# (verbose output shows detailed Codex CLI interactions)
```

## Example 9: CI/CD Integration

Use Codex CLI in automated workflows:

```yaml
# .github/workflows/task-analysis.yml
name: Analyze Task Complexity

on:
  push:
    paths:
      - '.taskmaster/**'

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Task Master
        run: npm install -g task-master-ai

      - name: Configure Codex CLI
        run: |
          npm install -g @openai/codex
          echo "${{ secrets.OPENAI_CODEX_API_KEY }}" > ~/.codex-auth
        env:
          OPENAI_CODEX_API_KEY: ${{ secrets.OPENAI_CODEX_API_KEY }}

      - name: Configure Task Master
        run: |
          cat > .taskmaster/config.json <<EOF
          {
            "models": {
              "main": {
                "provider": "codex-cli",
                "modelId": "gpt-5"
              }
            },
            "codexCli": {
              "allowNpx": true,
              "skipGitRepoCheck": true,
              "approvalMode": "never",
              "fullAuto": true
            }
          }
          EOF

      - name: Analyze Complexity
        run: task-master analyze-complexity --research

      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: complexity-report
          path: .taskmaster/reports/task-complexity-report.json
```

## Best Practices

### 1. Use OAuth for Development

```bash
# For local development, use OAuth (no API key needed)
codex login
task-master models --set-main gpt-5-codex --codex-cli
```

### 2. Configure Approval Modes Appropriately

```json
{
  "codexCli": {
    "approvalMode": "on-failure",  // Safe default
    "sandboxMode": "workspace-write"  // Restricts to project directory
  }
}
```

### 3. Use Command-Specific Settings

```json
{
  "codexCli": {
    "commandSpecific": {
      "parse-prd": {
        "approvalMode": "never",  // PRD parsing is safe
        "verbose": true
      },
      "expand": {
        "approvalMode": "on-request",  // More cautious for task expansion
        "verbose": false
      }
    }
  }
}
```

### 4. Leverage Codebase Analysis

```json
{
  "global": {
    "enableCodebaseAnalysis": true  // Let Codex analyze your code
  }
}
```

### 5. Handle Errors Gracefully

```bash
# Always configure a fallback model
task-master models --set-fallback gpt-5 --codex-cli

# Or use a different provider as fallback
task-master models --set-fallback claude-3-5-sonnet
```

## Next Steps

- Read the [Codex CLI Provider Documentation](../providers/codex-cli.md)
- Explore [Configuration Options](../configuration.md#codex-cli-provider)
- Check out [Command Reference](../command-reference.md)
- Learn about [Task Structure](../task-structure.md)

## Common Patterns

### Pattern: Daily Development Workflow

```bash
# Morning: Review tasks
task-master list

# Get next task
task-master next

# Work on task...

# Update task with notes
task-master update-subtask --id=2.3 --prompt="Implemented authentication middleware"

# Mark complete
task-master set-status --id=2.3 --status=done

# Repeat
```

### Pattern: Feature Planning

```bash
# Write feature spec
vim new-feature.txt

# Generate tasks
task-master parse-prd new-feature.txt --num-tasks 10

# Analyze and expand
task-master analyze-complexity --research
task-master expand --all --research --force

# Review and adjust
task-master list
```

### Pattern: Sprint Planning

```bash
# Parse sprint requirements
task-master parse-prd sprint-requirements.txt

# Analyze complexity
task-master analyze-complexity --research

# View report
task-master complexity-report

# Adjust task estimates based on complexity scores
```

---

For more examples and advanced usage, see the [full documentation](https://docs.task-master.dev).