claude-task-master/docs/providers/codex-cli.md

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. 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:

# 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

# Check Node.js version
node --version

# Check Codex CLI version
codex --version

# Check Task Master version
task-master --version

Installation

Install Codex CLI

# 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)

# 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:

# 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:

# 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:

# 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:

{
  "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:

{
  "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:

{
  "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

# 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:

# 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:

{
  "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:

   npm install -g @openai/codex
   

2. Verify installation:

   codex --version
   

3. Alternative: Enable npx fallback:

   {
     "codexCli": {
       "allowNpx": true
     }
   }
   

"Not logged in" Errors

Symptoms: Authentication errors when trying to use Codex CLI.

Solutions:

1. Authenticate with OAuth:

   codex login
   

2. Verify authentication status:

   codex
   # Then use /about command
   

3. Re-authenticate if needed:

   # 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:

   codex --version
   

2. Upgrade to latest version:

   npm install -g @openai/codex@latest
   

3. Verify upgrade:

   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:

   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:

   # 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:

   {
     "codexCli": {
       "approvalMode": "on-request"
     }
   }
   

2. Adjust sandbox mode:

   {
     "codexCli": {
       "sandboxMode": "workspace-write"
     }
   }
   

3. For fully automated workflows (use cautiously):

   {
     "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 - Complete Codex CLI configuration reference
• Command Reference - Using --codex-cli flag with commands
• Gemini CLI Provider - Similar CLI-based provider for Google Gemini
• Claude Code Integration - Another CLI-based provider
• ai-sdk-provider-codex-cli - Source code for the provider package