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:

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

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

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

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

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

// 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
      }
    }
  }
}

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

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

// 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
    }
  }
}

# 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

# 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

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

# Re-authenticate if needed
codex login

Issue: Want more verbose output

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

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

# 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

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

3. Use Command-Specific Settings

{
  "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

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

5. Handle Errors Gracefully

# 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
• Explore Configuration Options
• Check out Command Reference
• Learn about Task Structure

Common Patterns

Pattern: Daily Development Workflow

# 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

# 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

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