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
@@ -383,6 +383,12 @@ task-master models --set-main=my-local-llama --ollama
|
||||
# Set a custom OpenRouter model for the research role
|
||||
task-master models --set-research=google/gemini-pro --openrouter
|
||||
|
||||
# Set Codex CLI model for the main role (uses ChatGPT subscription via OAuth)
|
||||
task-master models --set-main=gpt-5-codex --codex-cli
|
||||
|
||||
# Set Codex CLI model for the fallback role
|
||||
task-master models --set-fallback=gpt-5 --codex-cli
|
||||
|
||||
# Run interactive setup to configure models, including custom ones
|
||||
task-master models --setup
|
||||
```
|
||||
|
||||
@@ -429,3 +429,153 @@ Azure OpenAI provides enterprise-grade OpenAI models through Microsoft's Azure c
|
||||
- Verify the deployment name matches your configuration exactly (case-sensitive)
|
||||
- Ensure the model deployment is in a "Succeeded" state in Azure OpenAI Studio
|
||||
- Ensure youre not getting rate limited by `maxTokens` maintain appropriate Tokens per Minute Rate Limit (TPM) in your deployment.
|
||||
|
||||
### Codex CLI Provider
|
||||
|
||||
The Codex CLI provider integrates Task Master with OpenAI's Codex CLI, allowing you to use ChatGPT subscription models via OAuth authentication.
|
||||
|
||||
1. **Prerequisites**:
|
||||
- Node.js >= 18
|
||||
- Codex CLI >= 0.42.0 (>= 0.44.0 recommended)
|
||||
- ChatGPT subscription: Plus, Pro, Business, Edu, or Enterprise (for OAuth access to GPT-5 models)
|
||||
|
||||
2. **Installation**:
|
||||
```bash
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
3. **Authentication** (OAuth - Primary Method):
|
||||
```bash
|
||||
codex login
|
||||
```
|
||||
This will open a browser window for OAuth authentication with your ChatGPT account. Once authenticated, Task Master will automatically use these credentials.
|
||||
|
||||
4. **Optional API Key Method**:
|
||||
While OAuth is the primary and recommended authentication method, you can optionally set an OpenAI API key:
|
||||
```bash
|
||||
# In .env file
|
||||
OPENAI_API_KEY=sk-your-openai-api-key-here
|
||||
```
|
||||
**Note**: The API key will only be injected if explicitly provided. OAuth is always preferred.
|
||||
|
||||
5. **Configuration**:
|
||||
```json
|
||||
// In .taskmaster/config.json
|
||||
{
|
||||
"models": {
|
||||
"main": {
|
||||
"provider": "codex-cli",
|
||||
"modelId": "gpt-5-codex",
|
||||
"maxTokens": 128000,
|
||||
"temperature": 0.2
|
||||
},
|
||||
"fallback": {
|
||||
"provider": "codex-cli",
|
||||
"modelId": "gpt-5",
|
||||
"maxTokens": 128000,
|
||||
"temperature": 0.2
|
||||
}
|
||||
},
|
||||
"codexCli": {
|
||||
"allowNpx": true,
|
||||
"skipGitRepoCheck": true,
|
||||
"approvalMode": "on-failure",
|
||||
"sandboxMode": "workspace-write"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
6. **Available Models**:
|
||||
- `gpt-5` - Latest GPT-5 model (272K max input, 128K max output)
|
||||
- `gpt-5-codex` - GPT-5 optimized for agentic software engineering (272K max input, 128K max output)
|
||||
|
||||
7. **Codex CLI Settings (`codexCli` section)**:
|
||||
|
||||
The `codexCli` section in your configuration file supports the following options:
|
||||
|
||||
- **`allowNpx`** (boolean, default: `false`): Allow fallback to `npx @openai/codex` if CLI not found on PATH
|
||||
- **`skipGitRepoCheck`** (boolean, default: `false`): Skip git repository safety check (recommended for CI/non-repo usage)
|
||||
- **`approvalMode`** (string): Control command execution approval
|
||||
- `"untrusted"`: Require approval for all commands
|
||||
- `"on-failure"`: Only require approval after a command fails (default)
|
||||
- `"on-request"`: Approve only when explicitly requested
|
||||
- `"never"`: Never require approval (not recommended)
|
||||
- **`sandboxMode`** (string): Control filesystem access
|
||||
- `"read-only"`: Read-only access
|
||||
- `"workspace-write"`: Allow writes to workspace (default)
|
||||
- `"danger-full-access"`: Full filesystem access (use with caution)
|
||||
- **`codexPath`** (string, optional): Custom path to codex CLI executable
|
||||
- **`cwd`** (string, optional): Working directory for Codex CLI execution
|
||||
- **`fullAuto`** (boolean, optional): Fully automatic mode (equivalent to `--full-auto` flag)
|
||||
- **`dangerouslyBypassApprovalsAndSandbox`** (boolean, optional): Bypass all safety checks (dangerous!)
|
||||
- **`color`** (string, optional): Color handling - `"always"`, `"never"`, or `"auto"`
|
||||
- **`outputLastMessageFile`** (string, optional): Write last agent message to specified file
|
||||
- **`verbose`** (boolean, optional): Enable verbose logging
|
||||
- **`env`** (object, optional): Additional environment variables for Codex CLI
|
||||
|
||||
8. **Command-Specific Settings** (optional):
|
||||
You can override settings for specific Task Master commands:
|
||||
```json
|
||||
{
|
||||
"codexCli": {
|
||||
"allowNpx": true,
|
||||
"approvalMode": "on-failure",
|
||||
"commandSpecific": {
|
||||
"parse-prd": {
|
||||
"approvalMode": "never",
|
||||
"verbose": true
|
||||
},
|
||||
"expand": {
|
||||
"sandboxMode": "read-only"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
9. **Codebase Features**:
|
||||
The Codex CLI provider is codebase-capable, meaning it can analyze and interact with your project files. Codebase analysis features are automatically enabled when using `codex-cli` as your provider and `enableCodebaseAnalysis` is set to `true` in your global configuration (default).
|
||||
|
||||
10. **Setup Commands**:
|
||||
```bash
|
||||
# Set Codex CLI for main role
|
||||
task-master models --set-main gpt-5-codex --codex-cli
|
||||
|
||||
# Set Codex CLI for fallback role
|
||||
task-master models --set-fallback gpt-5 --codex-cli
|
||||
|
||||
# Verify configuration
|
||||
task-master models
|
||||
```
|
||||
|
||||
11. **Troubleshooting**:
|
||||
|
||||
**"codex: command not found" error:**
|
||||
- Install Codex CLI globally: `npm install -g @openai/codex`
|
||||
- Verify installation: `codex --version`
|
||||
- Alternatively, enable `allowNpx: true` in your codexCli configuration
|
||||
|
||||
**"Not logged in" errors:**
|
||||
- Run `codex login` to authenticate with your ChatGPT account
|
||||
- Verify authentication status: `codex` (opens interactive CLI)
|
||||
|
||||
**"Old version" warnings:**
|
||||
- Check version: `codex --version`
|
||||
- Upgrade: `npm install -g @openai/codex@latest`
|
||||
- Minimum version: 0.42.0, recommended: >= 0.44.0
|
||||
|
||||
**"Model not available" errors:**
|
||||
- Only `gpt-5` and `gpt-5-codex` are available via OAuth subscription
|
||||
- Verify your ChatGPT subscription is active
|
||||
- For other OpenAI models, use the standard `openai` provider with an API key
|
||||
|
||||
**API key not being used:**
|
||||
- API key is only injected when explicitly provided
|
||||
- OAuth authentication is always preferred
|
||||
- If you want to use an API key, ensure `OPENAI_API_KEY` is set in your `.env` file
|
||||
|
||||
12. **Important Notes**:
|
||||
- OAuth subscription required for model access (no API key needed for basic operation)
|
||||
- Limited to OAuth-available models only (`gpt-5` and `gpt-5-codex`)
|
||||
- Pricing information is not available for OAuth models (shows as "Unknown" in cost calculations)
|
||||
- See [Codex CLI Provider Documentation](./providers/codex-cli.md) for more details
|
||||
|
||||
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).
|
||||
510
docs/providers/codex-cli.md
Normal file
510
docs/providers/codex-cli.md
Normal file
@@ -0,0 +1,510 @@
|
||||
# Codex CLI Provider
|
||||
|
||||
The `codex-cli` provider integrates Task Master with OpenAI's Codex CLI via the community AI SDK provider [`ai-sdk-provider-codex-cli`](https://github.com/ben-vargas/ai-sdk-provider-codex-cli). It uses your ChatGPT subscription (OAuth) via `codex login`, with optional `OPENAI_CODEX_API_KEY` support.
|
||||
|
||||
## Why Use Codex CLI?
|
||||
|
||||
The primary benefits of using the `codex-cli` provider include:
|
||||
|
||||
- **Use Latest OpenAI Models**: Access to cutting-edge models like GPT-5 and GPT-5-Codex via ChatGPT subscription
|
||||
- **OAuth Authentication**: No API key management needed - authenticate once with `codex login`
|
||||
- **Built-in Tool Execution**: Native support for command execution, file changes, MCP tools, and web search
|
||||
- **Native JSON Schema Support**: Structured output generation without post-processing
|
||||
- **Approval/Sandbox Modes**: Fine-grained control over command execution and filesystem access for safety
|
||||
|
||||
## Quickstart
|
||||
|
||||
Get up and running with Codex CLI in 3 steps:
|
||||
|
||||
```bash
|
||||
# 1. Install Codex CLI globally
|
||||
npm install -g @openai/codex
|
||||
|
||||
# 2. Authenticate with your ChatGPT account
|
||||
codex login
|
||||
|
||||
# 3. Configure Task Master to use Codex CLI
|
||||
task-master models --set-main gpt-5-codex --codex-cli
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Node.js**: >= 18.0.0
|
||||
- **Codex CLI**: >= 0.42.0 (>= 0.44.0 recommended)
|
||||
- **ChatGPT Subscription**: Required for OAuth access (Plus, Pro, Business, Edu, or Enterprise)
|
||||
- **Task Master**: >= 0.27.3 (version with Codex CLI support)
|
||||
|
||||
### Checking Your Versions
|
||||
|
||||
```bash
|
||||
# Check Node.js version
|
||||
node --version
|
||||
|
||||
# Check Codex CLI version
|
||||
codex --version
|
||||
|
||||
# Check Task Master version
|
||||
task-master --version
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### Install Codex CLI
|
||||
|
||||
```bash
|
||||
# Install globally via npm
|
||||
npm install -g @openai/codex
|
||||
|
||||
# Verify installation
|
||||
codex --version
|
||||
```
|
||||
|
||||
Expected output: `v0.44.0` or higher
|
||||
|
||||
### Install Task Master (if not already installed)
|
||||
|
||||
```bash
|
||||
# Install globally
|
||||
npm install -g task-master-ai
|
||||
|
||||
# Or install in your project
|
||||
npm install --save-dev task-master-ai
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
### OAuth Authentication (Primary Method - Recommended)
|
||||
|
||||
The Codex CLI provider is designed to use OAuth authentication with your ChatGPT subscription:
|
||||
|
||||
```bash
|
||||
# Launch Codex CLI and authenticate
|
||||
codex login
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Open a browser window for OAuth authentication
|
||||
2. Prompt you to log in with your ChatGPT account
|
||||
3. Store authentication credentials locally
|
||||
4. Allow Task Master to automatically use these credentials
|
||||
|
||||
To verify your authentication:
|
||||
```bash
|
||||
# Open interactive Codex CLI
|
||||
codex
|
||||
|
||||
# Use /about command to see auth status
|
||||
/about
|
||||
```
|
||||
|
||||
### Optional: API Key Method
|
||||
|
||||
While OAuth is the primary and recommended method, you can optionally use an OpenAI API key:
|
||||
|
||||
```bash
|
||||
# In your .env file
|
||||
OPENAI_CODEX_API_KEY=sk-your-openai-api-key-here
|
||||
```
|
||||
|
||||
**Important Notes**:
|
||||
- The API key will **only** be injected when explicitly provided
|
||||
- OAuth authentication is always preferred when available
|
||||
- Using an API key doesn't provide access to subscription-only models like GPT-5-Codex
|
||||
- For full OpenAI API access with non-subscription models, consider using the standard `openai` provider instead
|
||||
- `OPENAI_CODEX_API_KEY` is specific to the codex-cli provider to avoid conflicts with the `openai` provider's `OPENAI_API_KEY`
|
||||
|
||||
## Available Models
|
||||
|
||||
The Codex CLI provider supports only models available through ChatGPT subscription:
|
||||
|
||||
| Model ID | Description | Max Input Tokens | Max Output Tokens |
|
||||
|----------|-------------|------------------|-------------------|
|
||||
| `gpt-5` | Latest GPT-5 model | 272K | 128K |
|
||||
| `gpt-5-codex` | GPT-5 optimized for agentic software engineering | 272K | 128K |
|
||||
|
||||
**Note**: These models are only available via OAuth subscription through Codex CLI (ChatGPT Plus, Pro, Business, Edu, or Enterprise plans). For other OpenAI models, use the standard `openai` provider with an API key.
|
||||
|
||||
**Research Capabilities**: Both GPT-5 models support web search tools, making them suitable for the `research` role in addition to `main` and `fallback` roles.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
Add Codex CLI to your `.taskmaster/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"main": {
|
||||
"provider": "codex-cli",
|
||||
"modelId": "gpt-5-codex",
|
||||
"maxTokens": 128000,
|
||||
"temperature": 0.2
|
||||
},
|
||||
"fallback": {
|
||||
"provider": "codex-cli",
|
||||
"modelId": "gpt-5",
|
||||
"maxTokens": 128000,
|
||||
"temperature": 0.2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Configuration with Codex CLI Settings
|
||||
|
||||
The `codexCli` section allows you to customize Codex CLI behavior:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"main": {
|
||||
"provider": "codex-cli",
|
||||
"modelId": "gpt-5-codex",
|
||||
"maxTokens": 128000,
|
||||
"temperature": 0.2
|
||||
}
|
||||
},
|
||||
"codexCli": {
|
||||
"allowNpx": true,
|
||||
"skipGitRepoCheck": true,
|
||||
"approvalMode": "on-failure",
|
||||
"sandboxMode": "workspace-write",
|
||||
"verbose": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Codex CLI Settings Reference
|
||||
|
||||
#### Core Settings
|
||||
|
||||
- **`allowNpx`** (boolean, default: `false`)
|
||||
- Allow fallback to `npx @openai/codex` if the CLI is not found on PATH
|
||||
- Useful for CI environments or systems without global npm installations
|
||||
- Example: `"allowNpx": true`
|
||||
|
||||
- **`skipGitRepoCheck`** (boolean, default: `false`)
|
||||
- Skip git repository safety check before execution
|
||||
- Recommended for CI environments or non-repository usage
|
||||
- Example: `"skipGitRepoCheck": true`
|
||||
|
||||
#### Execution Control
|
||||
|
||||
- **`approvalMode`** (string)
|
||||
- Controls when to require user approval for command execution
|
||||
- Options:
|
||||
- `"untrusted"`: Require approval for all commands
|
||||
- `"on-failure"`: Only require approval after a command fails (default)
|
||||
- `"on-request"`: Approve only when explicitly requested
|
||||
- `"never"`: Never require approval (use with caution)
|
||||
- Example: `"approvalMode": "on-failure"`
|
||||
|
||||
- **`sandboxMode`** (string)
|
||||
- Controls filesystem access permissions
|
||||
- Options:
|
||||
- `"read-only"`: Read-only access to filesystem
|
||||
- `"workspace-write"`: Allow writes to workspace directory (default)
|
||||
- `"danger-full-access"`: Full filesystem access (use with extreme caution)
|
||||
- Example: `"sandboxMode": "workspace-write"`
|
||||
|
||||
#### Path and Environment
|
||||
|
||||
- **`codexPath`** (string, optional)
|
||||
- Custom path to Codex CLI executable
|
||||
- Useful when Codex is installed in a non-standard location
|
||||
- Example: `"codexPath": "/usr/local/bin/codex"`
|
||||
|
||||
- **`cwd`** (string, optional)
|
||||
- Working directory for Codex CLI execution
|
||||
- Defaults to current working directory
|
||||
- Example: `"cwd": "/path/to/project"`
|
||||
|
||||
- **`env`** (object, optional)
|
||||
- Additional environment variables for Codex CLI
|
||||
- Example: `"env": { "DEBUG": "true" }`
|
||||
|
||||
#### Advanced Settings
|
||||
|
||||
- **`fullAuto`** (boolean, optional)
|
||||
- Fully automatic mode (equivalent to `--full-auto` flag)
|
||||
- Bypasses most approvals for fully automated workflows
|
||||
- Example: `"fullAuto": true`
|
||||
|
||||
- **`dangerouslyBypassApprovalsAndSandbox`** (boolean, optional)
|
||||
- Bypass all safety checks including approvals and sandbox
|
||||
- **WARNING**: Use with extreme caution - can execute arbitrary code
|
||||
- Example: `"dangerouslyBypassApprovalsAndSandbox": false`
|
||||
|
||||
- **`color`** (string, optional)
|
||||
- Force color handling in Codex CLI output
|
||||
- Options: `"always"`, `"never"`, `"auto"`
|
||||
- Example: `"color": "auto"`
|
||||
|
||||
- **`outputLastMessageFile`** (string, optional)
|
||||
- Write last agent message to specified file
|
||||
- Useful for debugging or logging
|
||||
- Example: `"outputLastMessageFile": "./last-message.txt"`
|
||||
|
||||
- **`verbose`** (boolean, optional)
|
||||
- Enable verbose provider logging
|
||||
- Helpful for debugging issues
|
||||
- Example: `"verbose": true`
|
||||
|
||||
### Command-Specific Settings
|
||||
|
||||
Override settings for specific Task Master commands:
|
||||
|
||||
```json
|
||||
{
|
||||
"codexCli": {
|
||||
"allowNpx": true,
|
||||
"approvalMode": "on-failure",
|
||||
"commandSpecific": {
|
||||
"parse-prd": {
|
||||
"approvalMode": "never",
|
||||
"verbose": true
|
||||
},
|
||||
"expand": {
|
||||
"sandboxMode": "read-only"
|
||||
},
|
||||
"add-task": {
|
||||
"approvalMode": "untrusted"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Setting Codex CLI Models
|
||||
|
||||
```bash
|
||||
# Set Codex CLI for main role
|
||||
task-master models --set-main gpt-5-codex --codex-cli
|
||||
|
||||
# Set Codex CLI for fallback role
|
||||
task-master models --set-fallback gpt-5 --codex-cli
|
||||
|
||||
# Set Codex CLI for research role
|
||||
task-master models --set-research gpt-5 --codex-cli
|
||||
|
||||
# Verify configuration
|
||||
task-master models
|
||||
```
|
||||
|
||||
### Using Codex CLI with Task Master Commands
|
||||
|
||||
Once configured, use Task Master commands as normal:
|
||||
|
||||
```bash
|
||||
# Parse a PRD with Codex CLI
|
||||
task-master parse-prd my-requirements.txt
|
||||
|
||||
# Analyze project complexity
|
||||
task-master analyze-complexity --research
|
||||
|
||||
# Expand a task into subtasks
|
||||
task-master expand --id=1.2
|
||||
|
||||
# Add a new task with AI assistance
|
||||
task-master add-task --prompt="Implement user authentication" --research
|
||||
```
|
||||
|
||||
The provider will automatically use your OAuth credentials when Codex CLI is configured.
|
||||
|
||||
## Codebase Features
|
||||
|
||||
The Codex CLI provider is **codebase-capable**, meaning it can analyze and interact with your project files. This enables advanced features like:
|
||||
|
||||
- **Code Analysis**: Understanding your project structure and dependencies
|
||||
- **Intelligent Suggestions**: Context-aware task recommendations
|
||||
- **File Operations**: Reading and analyzing project files for better task generation
|
||||
- **Pattern Recognition**: Identifying common patterns and best practices in your codebase
|
||||
|
||||
### Enabling Codebase Analysis
|
||||
|
||||
Codebase analysis is automatically enabled when:
|
||||
1. Your provider is set to `codex-cli`
|
||||
2. `enableCodebaseAnalysis` is `true` in your global configuration (default)
|
||||
|
||||
To verify or configure:
|
||||
|
||||
```json
|
||||
{
|
||||
"global": {
|
||||
"enableCodebaseAnalysis": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "codex: command not found" Error
|
||||
|
||||
**Symptoms**: Task Master reports that the Codex CLI is not found.
|
||||
|
||||
**Solutions**:
|
||||
1. **Install Codex CLI globally**:
|
||||
```bash
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
2. **Verify installation**:
|
||||
```bash
|
||||
codex --version
|
||||
```
|
||||
|
||||
3. **Alternative: Enable npx fallback**:
|
||||
```json
|
||||
{
|
||||
"codexCli": {
|
||||
"allowNpx": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### "Not logged in" Errors
|
||||
|
||||
**Symptoms**: Authentication errors when trying to use Codex CLI.
|
||||
|
||||
**Solutions**:
|
||||
1. **Authenticate with OAuth**:
|
||||
```bash
|
||||
codex login
|
||||
```
|
||||
|
||||
2. **Verify authentication status**:
|
||||
```bash
|
||||
codex
|
||||
# Then use /about command
|
||||
```
|
||||
|
||||
3. **Re-authenticate if needed**:
|
||||
```bash
|
||||
# Logout first
|
||||
codex
|
||||
# Use /auth command to change auth method
|
||||
|
||||
# Then login again
|
||||
codex login
|
||||
```
|
||||
|
||||
### "Old version" Warnings
|
||||
|
||||
**Symptoms**: Warnings about Codex CLI version being outdated.
|
||||
|
||||
**Solutions**:
|
||||
1. **Check current version**:
|
||||
```bash
|
||||
codex --version
|
||||
```
|
||||
|
||||
2. **Upgrade to latest version**:
|
||||
```bash
|
||||
npm install -g @openai/codex@latest
|
||||
```
|
||||
|
||||
3. **Verify upgrade**:
|
||||
```bash
|
||||
codex --version
|
||||
```
|
||||
Should show >= 0.44.0
|
||||
|
||||
### "Model not available" Errors
|
||||
|
||||
**Symptoms**: Error indicating the requested model is not available.
|
||||
|
||||
**Causes and Solutions**:
|
||||
|
||||
1. **Using unsupported model**:
|
||||
- Only `gpt-5` and `gpt-5-codex` are available via Codex CLI
|
||||
- For other OpenAI models, use the standard `openai` provider
|
||||
|
||||
2. **Subscription not active**:
|
||||
- Verify your ChatGPT subscription is active
|
||||
- Check subscription status at <https://platform.openai.com>
|
||||
|
||||
3. **Wrong provider selected**:
|
||||
- Verify you're using `--codex-cli` flag when setting models
|
||||
- Check `.taskmaster/config.json` shows `"provider": "codex-cli"`
|
||||
|
||||
### API Key Not Being Used
|
||||
|
||||
**Symptoms**: You've set `OPENAI_CODEX_API_KEY` but it's not being used.
|
||||
|
||||
**Expected Behavior**:
|
||||
- OAuth authentication is always preferred
|
||||
- API key is only injected when explicitly provided
|
||||
- API key doesn't grant access to subscription-only models
|
||||
|
||||
**Solutions**:
|
||||
1. **Verify OAuth is working**:
|
||||
```bash
|
||||
codex
|
||||
# Check /about for auth status
|
||||
```
|
||||
|
||||
2. **If you want to force API key usage**:
|
||||
- This is not recommended with Codex CLI
|
||||
- Consider using the standard `openai` provider instead
|
||||
|
||||
3. **Verify .env file is being loaded**:
|
||||
```bash
|
||||
# Check if .env exists in project root
|
||||
ls -la .env
|
||||
|
||||
# Verify OPENAI_CODEX_API_KEY is set
|
||||
grep OPENAI_CODEX_API_KEY .env
|
||||
```
|
||||
|
||||
### Approval/Sandbox Issues
|
||||
|
||||
**Symptoms**: Commands are blocked or filesystem access is denied.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Adjust approval mode**:
|
||||
```json
|
||||
{
|
||||
"codexCli": {
|
||||
"approvalMode": "on-request"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Adjust sandbox mode**:
|
||||
```json
|
||||
{
|
||||
"codexCli": {
|
||||
"sandboxMode": "workspace-write"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **For fully automated workflows** (use cautiously):
|
||||
```json
|
||||
{
|
||||
"codexCli": {
|
||||
"fullAuto": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **OAuth subscription required**: No API key needed for basic operation, but requires active ChatGPT subscription
|
||||
- **Limited model selection**: Only `gpt-5` and `gpt-5-codex` available via OAuth
|
||||
- **Pricing information**: Not available for OAuth models (shows as "Unknown" in cost calculations)
|
||||
- **No automatic dependency**: The `@openai/codex` package is not added to Task Master's dependencies - install it globally or enable `allowNpx`
|
||||
- **Codebase analysis**: Automatically enabled when using `codex-cli` provider
|
||||
- **Safety first**: Default settings prioritize safety with `approvalMode: "on-failure"` and `sandboxMode: "workspace-write"`
|
||||
|
||||
## See Also
|
||||
|
||||
- [Configuration Guide](../configuration.md#codex-cli-provider) - Complete Codex CLI configuration reference
|
||||
- [Command Reference](../command-reference.md) - Using `--codex-cli` flag with commands
|
||||
- [Gemini CLI Provider](./gemini-cli.md) - Similar CLI-based provider for Google Gemini
|
||||
- [Claude Code Integration](../claude-code-integration.md) - Another CLI-based provider
|
||||
- [ai-sdk-provider-codex-cli](https://github.com/ben-vargas/ai-sdk-provider-codex-cli) - Source code for the provider package
|
||||
Reference in New Issue
Block a user