Providers Guide

This guide covers the AI agent providers supported by prompts-gpt, how to install them, configure provider-specific options, and understand their differences.

Supported Providers

Installing Provider CLIs

Codex (OpenAI)

npm install -g @openai/codex
codex --version

Claude Code (Anthropic)

npm install -g @anthropic-ai/claude-code
claude --version

Cursor

Cursor CLI is bundled with the Cursor IDE. Ensure the cursor command is available in your PATH.

cursor --version

GitHub Copilot

gh extension install github/gh-copilot
gh copilot --version

Detecting Providers

prompts-gpt providers

Output:

Provider    Status     Version     Path
──────────  ─────────  ──────────  ────────────────────
codex       available  1.0.12      /usr/local/bin/codex
claude      available  1.0.30      /usr/local/bin/claude
cursor      available  0.46.0      /usr/bin/cursor
copilot     missing    —           —

Programmatic detection:

import { detectProviders } from "prompts-gpt";

const providers = await detectProviders();
providers.forEach(p => {
  console.log(`${p.provider}: ${p.available ? p.version : "not found"}`);
});

Provider-Specific Options

Codex

prompts-gpt run task.md --provider codex --sandbox full-auto --model gpt-5.4

Claude

prompts-gpt run task.md --provider claude --permission-mode bypassPermissions

Cursor

prompts-gpt run task.md --provider cursor --model claude-4-sonnet-thinking

Copilot

prompts-gpt run task.md --provider copilot

Provider Selection Logic

Manual Selection

prompts-gpt run task.md --provider codex

Auto-Detection ("router" mode)

When defaultAgent is set to "router" in config:

1. Check providerOrder in .prompts-gpt/config.json
2. For each provider in order, check availability
3. Use the first available provider

{
  "defaultAgent": "router",
  "providerOrder": ["codex", "claude", "cursor"]
}

Config-Based Selection

Set a default provider in .prompts-gpt/config.json:

{
  "defaultAgent": "codex"
}

Model Configuration

Per-Provider Defaults

{
  "modelOverrides": {
    "codex": "gpt-5.5",
    "claude": "claude-sonnet-4-20250514",
    "cursor": "auto"
  }
}

Command-Line Override

prompts-gpt run task.md --provider codex --model gpt-5.4

Listing Available Models

prompts-gpt models --provider codex
prompts-gpt models --provider claude

Custom Models

prompts-gpt models --add my-custom-model --provider codex
prompts-gpt models --remove my-custom-model --provider codex

Provider Comparison

Troubleshooting

Provider not detected

# Check if binary is in PATH
which codex
which claude

# Run diagnostics
prompts-gpt doctor

Provider version too old

npm update -g @openai/codex
npm update -g @anthropic-ai/claude-code

Permission errors

Ensure the provider CLI has appropriate permissions:

# Codex: use appropriate sandbox level
prompts-gpt run task.md --provider codex --sandbox workspace-write

# Claude: use appropriate permission mode
prompts-gpt run task.md --provider claude --permission-mode acceptEdits

See Also

• Providers CLI
• Models CLI
• Configuration Reference