Skip to content

An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.

9.5 KB
Raw Blame

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

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.