docs: auto-update documentation based on changes in next branch

This PR was automatically generated to update documentation based on recent changes.

  Original commit: feat: Add Codex CLI provider with OAuth authentication (#1273)\n\nCo-authored-by: Ralph Khreish <35776126+Crunchyman-ralph@users.noreply.github.com>\n\n

  Co-authored-by: Claude <claude-assistant@anthropic.com>

apps/docs/best-practices/configuration-advanced.mdx

@@ -75,6 +75,7 @@ Taskmaster uses two primary methods for configuration:
   - `AZURE_OPENAI_API_KEY`: Your Azure OpenAI API key (also requires `AZURE_OPENAI_ENDPOINT`).
   - `OPENROUTER_API_KEY`: Your OpenRouter API key.
   - `XAI_API_KEY`: Your X-AI API key.
+  - `OPENAI_CODEX_API_KEY`: Your OpenAI API key for Codex CLI (optional - OAuth preferred).
 - **Optional Endpoint Overrides:**
   - **Per-role `baseURL` in `.taskmasterconfig`:** You can add a `baseURL` property to any model role (`main`, `research`, `fallback`) to override the default API endpoint for that provider. If omitted, the provider's standard endpoint is used.
   - **Environment Variable Overrides (`<PROVIDER>_BASE_URL`):** For greater flexibility, especially with third-party services, you can set an environment variable like `OPENAI_BASE_URL` or `MISTRAL_BASE_URL`. This will override any `baseURL` set in the configuration file for that provider. This is the recommended way to connect to OpenAI-compatible APIs.
@@ -317,3 +318,88 @@ 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 Configuration
+
+The Codex CLI provider integrates with OpenAI's ChatGPT subscription through the Codex CLI tool, providing access to advanced models like GPT-5 and GPT-5-Codex.
+
+1. **Prerequisites**:
+   - Node.js >= 18.0.0
+   - Codex CLI >= 0.42.0 (>= 0.44.0 recommended)
+   - Active ChatGPT subscription (Plus, Pro, Business, Edu, or Enterprise)
+
+2. **Installation**:
+   ```bash
+   # Install Codex CLI globally
+   npm install -g @openai/codex
+   
+   # Authenticate with your ChatGPT account
+   codex login
+   ```
+
+3. **Configuration Options**:
+
+   **Basic Configuration**
+   ```json
+   // In .taskmaster/config.json
+   {
+     "models": {
+       "main": {
+         "provider": "codex-cli",
+         "modelId": "gpt-5-codex",
+         "maxTokens": 128000,
+         "temperature": 0.2
+       }
+     }
+   }
+   ```
+
+   **Advanced Configuration with Codex CLI Settings**
+   ```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,
+       "commandSpecific": {
+         "parse-prd": {
+           "approvalMode": "never",
+           "verbose": true
+         },
+         "expand": {
+           "sandboxMode": "read-only"
+         }
+       }
+     }
+   }
+   ```
+
+4. **Authentication**:
+   - **Primary Method**: OAuth authentication via `codex login` (recommended)
+   - **Optional**: Set `OPENAI_CODEX_API_KEY` environment variable as fallback
+   - Note: API key doesn't provide access to subscription-only models like GPT-5-Codex
+
+5. **Available Settings**:
+   - **`allowNpx`** (boolean): Allow fallback to `npx @openai/codex` if CLI not found
+   - **`skipGitRepoCheck`** (boolean): Skip git repository safety check
+   - **`approvalMode`** (string): Control command approval (`"untrusted"`, `"on-failure"`, `"on-request"`, `"never"`)
+   - **`sandboxMode`** (string): Control filesystem access (`"read-only"`, `"workspace-write"`, `"danger-full-access"`)
+   - **`codexPath`** (string): Custom path to Codex CLI executable
+   - **`cwd`** (string): Working directory for execution
+   - **`verbose`** (boolean): Enable verbose logging
+   - **`commandSpecific`** (object): Override settings for specific commands
+
+6. **Security Notes**:
+   - Default settings prioritize safety with approval and sandbox modes
+   - Use `fullAuto: true` or `dangerouslyBypassApprovalsAndSandbox: true` with extreme caution
+   - Codebase analysis is automatically enabled for this provider

apps/docs/docs.json

@@ -52,6 +52,18 @@
 							"capabilities/cli-root-commands",
 							"capabilities/task-structure"
 						]
+					},
+					{
+						"group": "AI Providers",
+						"pages": [
+							"providers/codex-cli"
+						]
+					},
+					{
+						"group": "Usage Examples",
+						"pages": [
+							"examples/codex-cli-usage"
+						]
 					}
 				]
 			}

apps/docs/examples/codex-cli-usage.mdx

@@ -0,0 +1,466 @@
+---
+title: Codex CLI Provider Usage Examples
+sidebarTitle: "Codex CLI Usage"
+---
+
+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
+```
+
+## 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
+```
+
+## Next Steps
+
+- Read the [Codex CLI Provider Documentation](../providers/codex-cli)
+- Explore [Configuration Options](../best-practices/configuration-advanced)
+- Check out [API Keys Setup](../getting-started/api-keys)
+- Learn about [Task Structure](../capabilities/task-structure)
+
+---
+
+For more examples and advanced usage, see the [full documentation](https://docs.task-master.dev).

apps/docs/getting-started/api-keys.mdx

@@ -112,6 +112,19 @@ AWS_ACCESS_KEY_ID="your-aws-access-key"
 AWS_SECRET_ACCESS_KEY="your-aws-secret-key"
 ```
 
+### OPENAI_CODEX_API_KEY
+- **Provider**: Codex CLI
+- **Required**: ❌ **No** (uses OAuth authentication)
+- **Purpose**: Optional API key for Codex CLI provider
+- **Authentication**: OAuth via `codex login` is preferred, API key is optional fallback
+- **Models**: GPT-5, GPT-5-Codex (subscription required)
+- **Get Key**: [OpenAI Platform](https://platform.openai.com/api-keys)
+
+```bash
+# Optional - OAuth authentication is preferred
+OPENAI_CODEX_API_KEY="sk-your-openai-api-key-here"
+```
+
 ### CLAUDE_CODE_API_KEY
 - **Provider**: Claude Code CLI
 - **Required**: ❌ **No** (uses OAuth tokens)

apps/docs/providers/codex-cli.mdx

@@ -0,0 +1,408 @@
+---
+title: Codex CLI Provider
+sidebarTitle: "Codex CLI"
+---
+
+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"`
+
+#### Advanced Settings
+
+- **`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"`
+
+- **`verbose`** (boolean, optional)
+  - Enable verbose provider logging
+  - Helpful for debugging issues
+  - Example: `"verbose": true`
+
+- **`fullAuto`** (boolean, optional)
+  - Fully automatic mode (equivalent to `--full-auto` flag)
+  - Bypasses most approvals for fully automated workflows
+  - Example: `"fullAuto": 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
+   ```
+
+### "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"`
+
+## 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](../best-practices/configuration-advanced) - Complete Codex CLI configuration reference
+- [API Keys](../getting-started/api-keys) - Setting up OPENAI_CODEX_API_KEY
+- [Codex CLI Usage Examples](../examples/codex-cli-usage) - Practical usage examples
+- [ai-sdk-provider-codex-cli](https://github.com/ben-vargas/ai-sdk-provider-codex-cli) - Source code for the provider package