feat: Add Codex CLI provider with OAuth authentication (#1273)
Co-authored-by: Ralph Khreish <35776126+Crunchyman-ralph@users.noreply.github.com>
This commit is contained in:
Ben Vargas
463
docs/examples/codex-cli-usage.md
Normal file
463
docs/examples/codex-cli-usage.md
Normal file
@@ -0,0 +1,463 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user