mirror of
https://github.com/eyaltoledano/claude-task-master.git
synced 2025-11-09 14:27:21 +00:00
464 lines
9.5 KiB
Markdown
464 lines
9.5 KiB
Markdown
# 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).
|