### Fresh Install Test Setup

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Performs a fresh installation test by clearing the cache, setting up a minimal opencode configuration, and testing the default model.

```bash
# 1. Clear cache
(cd ~ && rm -rf .cache/opencode/node_modules/opencode-openai-codex-auth)

# 2. Use minimal config
cat > ~/.config/opencode/opencode.jsonc <<'EOF'
{
  "plugin": ["opencode-openai-codex-auth"],
  "model": "openai/gpt-5-codex"
}
EOF

# 3. Test default model
DEBUG_CODEX_PLUGIN=1 opencode run "write hello world to test.txt"

```

--------------------------------

### Full Configuration Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

Provides a comprehensive configuration example including schema, plugin, model, and detailed provider options for multiple models.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-openai-codex-auth"],
  "model": "openai/gpt-5-codex-medium",
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "reasoningSummary": "auto",
        "textVerbosity": "medium",
        "include": ["reasoning.encrypted_content"]
      },
      "models": {
        "gpt-5-codex-low": {
          "name": "GPT 5 Codex Low (OAuth)",
          "options": {
            "reasoningEffort": "low"
          }
        },
        "gpt-5-codex-high": {
          "name": "GPT 5 Codex High (OAuth)",
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "detailed"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Global Configuration Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Example of a global configuration file, typically located at ~/.config/opencode/opencode.jsonc. This sets default provider options.

```json
{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "store": false
      }
    }
  }
}
```

--------------------------------

### Project-Specific Configuration Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Example of a project-specific configuration file, typically located at my-project/.opencode.json. This overrides global settings for that project.

```json
{
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "high",
        "store": false
      }
    }
  }
}
```

--------------------------------

### TUI Persistence Test Setup

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Tests the persistence of the selected model in the TUI by starting opencode, running a command, exiting, and then restarting to check the auto-selected model.

```bash
# 1. Start opencode
opencode --model=openai/gpt-5-codex-high

# 2. Run a command
> write test

# 3. Exit (ctrl+c)

# 4. Restart
opencode

# 5. Check which model is selected
> /model

```

--------------------------------

### Quick Reference Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

This is a full configuration example showing global and model-specific settings for the OpenAI Codex Auth Plugin.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "reasoningSummary": "auto",
        "textVerbosity": "medium",
        "include": ["reasoning.encrypted_content"],
        "store": false
      },
      "models": {
        "gpt-5.1-codex-low": {
          "name": "GPT 5.1 Codex Low (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "low",
            "reasoningSummary": "auto",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        }
      }
    }
  }
}
```

--------------------------------

### Current OpenCode Config Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

This example shows a typical configuration for a model variant, demonstrating the interplay between config key, ID, and name fields.

```json
{
  "gpt-5-codex-low": {
    "id": "gpt-5-codex",
    "name": "GPT 5 Codex Low (OAuth)",
    "options": { "reasoningEffort": "low" }
  }
}
```

--------------------------------

### OpenCode Authentication Steps

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/index.md

After installation, add the plugin configuration to your OpenCode settings and then run OpenCode to authenticate via the command line.

```bash
# 1. Add plugin to ~/.config/opencode/opencode.jsonc (or .json)
# 2. Run OpenCode
opencode

# 3. Authenticate
opencode auth login
```

--------------------------------

### Install OpenCode OpenAI Codex Auth

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/README.md

Install the latest version of the package using npx.

```bash
npx -y opencode-openai-codex-auth@latest
```

--------------------------------

### Run with Legacy Config (Medium Variant)

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/README.md

Example of running a task with the legacy configuration, specifying the 'openai/gpt-5.2-medium' model.

```bash
opencode run "task" --model=openai/gpt-5.2-medium
```

--------------------------------

### Run with Legacy Config (High Variant)

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/README.md

Example of running a task with the legacy configuration, specifying the 'openai/gpt-5.2-high' model.

```bash
opencode run "task" --model=openai/gpt-5.2-high
```

--------------------------------

### Install Legacy OpenCode

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/README.md

Install the legacy version of the package for older OpenCode versions (v1.0.209 and below).

```bash
npx -y opencode-openai-codex-auth@latest --legacy
```

--------------------------------

### Syntax Check with jq

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

Example command to check the JSON syntax of a configuration file using the 'jq' utility.

```bash
jq . < config.json
```

--------------------------------

### Start Interactive OpenCode Session

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/getting-started.md

Start an interactive session with OpenCode. This will allow you to select from various GPT 5.x model variants.

```bash
# Or start interactive session
opencode
```

--------------------------------

### Run a Quick Test Command

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/getting-started.md

Execute a quick test command using OpenCode to verify the setup. This command writes 'hello world' to a file using a specified GPT 5.x model.

```bash
# Quick test
opencode run "write hello world to test.txt" --model=openai/gpt-5.1-codex-medium
```

--------------------------------

### Custom Config Test Setup

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Sets up custom model configurations with different reasoning efforts and tests their application using opencode.

```bash
# Update config with custom models
cat > ~/.config/opencode/opencode.jsonc <<'EOF'
{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "models": {
        "gpt-5-codex-low": {
          "name": "GPT 5 Codex Low (OAuth)",
          "options": { "reasoningEffort": "low" }
        },
        "gpt-5-codex-high": {
          "name": "GPT 5 Codex High (OAuth)",
          "options": { "reasoningEffort": "high" }
        }
      }
    }
  }
}
EOF

# Test per-model options
DEBUG_CODEX_PLUGIN=1 opencode run "test low" --model=openai/gpt-5-codex-low
DEBUG_CODEX_PLUGIN=1 opencode run "test high" --model=openai/gpt-5-codex-high

```

--------------------------------

### Run with Modern Config (Medium Variant)

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/README.md

Example of running a task with the modern configuration, specifying the 'openai/gpt-5.2' model and the 'medium' reasoning variant.

```bash
opencode run "task" --model=openai/gpt-5.2 --variant=medium
```

--------------------------------

### Run with Modern Config (High Variant)

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/README.md

Example of running a task with the modern configuration, specifying the 'openai/gpt-5.2' model and the 'high' reasoning variant.

```bash
opencode run "task" --model=openai/gpt-5.2 --variant=high
```

--------------------------------

### Applying Global Options to All OpenAI Models

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

This example demonstrates how to set global options for the OpenAI provider, which will be applied to all models unless overridden by model-specific configurations.

```json
{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "textVerbosity": "medium",
        "include": ["reasoning.encrypted_content"]
      }
    }
  }
}
```

--------------------------------

### Build the Plugin Locally

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/getting-started.md

Build the plugin locally for development or testing. Navigate to the plugin's directory and run npm install and npm run build.

```bash
cd opencode-openai-codex-auth
npm install
npm run build
```

--------------------------------

### Check OpenCode Version

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/README.md

Command to check your installed OpenCode version.

```bash
opencode --version
```

--------------------------------

### Local Development Setup for Plugin

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/getting-started.md

Configure OpenCode to use a local development version of the plugin. Ensure the path points to the 'dist/' folder after building.

```json
{
  "plugin": ["file:///absolute/path/to/opencode-openai-codex-auth/dist"]
}
```

--------------------------------

### TUI Persistence Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

The selected provider ID and model ID (using the 'CONFIG KEY') are persisted in the TUI configuration file.

```text
~/.opencode/tui:
  provider_id = "openai"
  model_id = "gpt-5-codex-low" ← CONFIG KEY persisted
```

--------------------------------

### Install/Update OpenCode OpenAI Codex Auth Plugin

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/index.md

Run this command to install or update the plugin globally. For older OpenCode versions, use the --legacy flag.

```bash
npx -y opencode-openai-codex-auth@latest
```

```bash
npx -y opencode-openai-codex-auth@latest --legacy
```

--------------------------------

### Per-Model Override Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

Demonstrates how to override global options for specific models. 'gpt-5-codex-high' overrides 'reasoningEffort' and 'reasoningSummary', while 'gpt-5-nano' overrides both.

```json
{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "textVerbosity": "medium"
      },
      "models": {
        "gpt-5-codex-high": {
          "name": "GPT 5 Codex High (OAuth)",
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "detailed"
          }
        },
        "gpt-5-nano": {
          "name": "GPT 5 Nano (OAuth)",
          "options": {
            "reasoningEffort": "minimal",
            "textVerbosity": "low"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Full OpenCode Configuration for OpenAI Codex Auth

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/getting-started.md

This is the only officially supported setup for GPT 5.x models. It must be added to `~/.config/opencode/opencode.jsonc` or `.json`. It includes various GPT 5.1 Codex model configurations with different reasoning efforts and limits.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "reasoningSummary": "auto",
        "textVerbosity": "medium",
        "include": ["reasoning.encrypted_content"],
        "store": false
      },
      "models": {
        "gpt-5.1-codex-low": {
          "name": "GPT 5.1 Codex Low (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "low",
            "reasoningSummary": "auto",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-medium": {
          "name": "GPT 5.1 Codex Medium (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "medium",
            "reasoningSummary": "auto",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-high": {
          "name": "GPT 5.1 Codex High (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "detailed",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-max": {
          "name": "GPT 5.1 Codex Max (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "detailed",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-max-low": {
          "name": "GPT 5.1 Codex Max Low (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "low",
            "reasoningSummary": "detailed",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-max-medium": {
          "name": "GPT 5.1 Codex Max Medium (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "medium",
            "reasoningSummary": "detailed",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-max-high": {
          "name": "GPT 5.1 Codex Max High (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "detailed",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-max-xhigh": {
          "name": "GPT 5.1 Codex Max Extra High (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "xhigh",
            "reasoningSummary": "detailed",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-mini-medium": {
          "name": "GPT 5.1 Codex Mini Medium (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "medium",
            "reasoningSummary": "auto",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        },
        "gpt-5.1-codex-mini-high": {

```

--------------------------------

### Config Key Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

The 'config key' is the primary identifier used throughout OpenCode for model lookup and persistence. It is also what the plugin receives in `body.model`.

```json
"gpt-5-codex-low": { ... }
  └──────┬──────┘
    CONFIG KEY
```

--------------------------------

### Default OpenCode Models Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Configuration for using default OpenCode models without any custom settings. This setup relies on global options for all model requests.

```json
{
  "plugin": ["opencode-openai-codex-auth"]
}
```

--------------------------------

### Debug Output: Custom Model with Config

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Example of expected debug output when a custom model with specific configuration is used, verifying that per-model options are correctly identified and applied.

```text
[openai-codex-plugin] Debug logging ENABLED
[openai-codex-plugin] Model config lookup: "gpt-5-codex-low" → normalized to "gpt-5-codex" for API {
  hasModelSpecificConfig: true,
  resolvedConfig: {
    reasoningEffort: 'low',
    textVerbosity: 'medium',
    reasoningSummary: 'auto',
    include: ['reasoning.encrypted_content']
  }
}
[openai-codex-plugin] Filtering 0 message IDs from input: []
```

--------------------------------

### CLI Usage with Config Key

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Demonstrates how to use the configuration key to specify a model in the command-line interface.

```bash
# Use the config key in CLI
opencode run "task" --model=openai/my-custom-id
```

--------------------------------

### Start New Conversation

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/troubleshooting.md

To resolve "Context Window Exceeded" errors, you can start a new conversation by exiting and restarting OpenCode, which clears the conversation history.

```bash
# Exit and restart OpenCode (clears history)
```

--------------------------------

### Name Field Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

The 'name' field is used for UI display, providing a user-friendly and descriptive name for models in the model picker.

```json
"name": "GPT 5 Codex Low (OAuth)"
         └──────────┬──────────┘
              NAME FIELD
```

--------------------------------

### Cost vs. Quality Model Presets

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

This JSON illustrates setting up model presets that balance cost and quality, offering 'Economy Mode' for lower resource usage and 'Premium Mode' for higher quality output.

```json
{
  "models": {
    "economy": {
      "name": "Economy Mode",
      "options": {
        "reasoningEffort": "low",
        "textVerbosity": "low",
        "store": false
      }
    },
    "premium": {
      "name": "Premium Mode",
      "options": {
        "reasoningEffort": "high",
        "textVerbosity": "high",
        "store": false
      }
    }
  }
}
```

--------------------------------

### Testing Minimal Config with OPENCODE_CONFIG_CONTENT

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

Demonstrates how to test minimal configurations by providing the config content directly via the OPENCODE_CONFIG_CONTENT environment variable.

```bash
OPENCODE_CONFIG_CONTENT='{"codexMode": false}' opencode
```

--------------------------------

### Backwards Compatibility: New Plugin + New Config

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

Illustrates the ideal scenario with a new plugin and a new configuration format, ensuring per-model options work correctly and utilizing cleaner naming conventions.

```json
"gpt-5-codex-low": {
  "id": "gpt-5-codex",
  "name": "GPT 5 Codex Low (OAuth)",
  "options": { "reasoningEffort": "low" }
}
```

--------------------------------

### Test Per-Model Options with Logging

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Run OpenCode with different models and enable logging to observe the applied options. This helps in verifying that per-model configurations are correctly applied.

```bash
ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5-codex-low
ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5-codex-high
```

```bash
cat ~/.opencode/logs/codex-plugin/request-*-after-transform.json | jq '.reasoning.effort'
```

--------------------------------

### Run Tests in Watch Mode

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/test/README.md

Continuously run tests as file changes are detected. Useful for TDD or during active development to get immediate feedback.

```bash
npm run test:watch
```

--------------------------------

### Custom Configuration via Environment Variables

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

You can specify a custom configuration file path or provide configuration content directly using environment variables.

```bash
OPENCODE_CONFIG=/path/to/config.json opencode
```

```bash
OPENCODE_CONFIG_CONTENT='{"model":"openai/gpt-5"}' opencode
```

--------------------------------

### ID Field Example

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

The 'id' field serves as documentation and metadata, indicating the base model a variant uses and aiding in sorting. For OpenAI, this is not sent to the API.

```json
"id": "gpt-5-codex"
       └─────┬─────┘
         ID FIELD
```

--------------------------------

### Incompatible Request Body from OpenCode/AI SDK

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/ARCHITECTURE.md

This is an example of a multi-turn request body sent by the OpenCode/AI SDK, which includes constructs not directly supported by the Codex API.

```typescript
const body = {
  input: [
    { type: "message", role: "developer", content: [...] },
    { type: "message", role: "user", content: [...], id: "msg_abc" },
    { type: "item_reference", id: "rs_xyz" },  // ← AI SDK construct
    { type: "function_call", id: "fc_123" }
  ]
};
```

--------------------------------

### Copy Legacy Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/README.md

Use this command to copy the legacy configuration file if you have OpenCode v1.0.209 or older.

```bash
cp config/opencode-legacy.json ~/.config/opencode/opencode.jsonc
```

--------------------------------

### Inspect Actual API Requests with Logging

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/troubleshooting.md

Run OpenCode with request logging enabled and then inspect the 'after-transform' log file to verify the details sent to the API.

```bash
# Run command with logging
ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5-codex-low

# Check what was sent to API
cat ~/.opencode/logs/codex-plugin/request-*-after-transform.json | jq '{ "model": .body.model, "reasoning": .body.reasoning, "text": .body.text, "store": .body.store, "include": .body.include }'
```

--------------------------------

### Quick Switch Presets Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Define named variants for common tasks, each with specific 'reasoningEffort' and 'store' options. These presets offer quick-switch capabilities for different use cases.

```json
{
  "models": {
    "codex-quick": {
      "name": "⚡ Quick Code",
      "options": {
        "reasoningEffort": "low",
        "store": false
      }
    },
    "codex-balanced": {
      "name": "⚖️ Balanced Code",
      "options": {
        "reasoningEffort": "medium",
        "store": false
      }
    },
    "codex-quality": {
      "name": "🎯 Max Quality",
      "options": {
        "reasoningEffort": "high",
        "reasoningSummary": "detailed",
        "store": false
      }
    }
  }
}
```

--------------------------------

### Run a Command with Legacy Model Presets

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/README.md

Execute a command using legacy model presets. This is for OpenCode v1.0.209 and below.

```bash
opencode run "write hello world to test.txt" --model=openai/gpt-5.2-medium
```

--------------------------------

### Global and Per-Model Store Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

Demonstrates setting the 'store' option globally for all models and explicitly for a specific model. While per-model configuration is redundant if set globally, it can be used for clarity.

```json
{
  "provider": {
    "openai": {
      "options": {
        "store": false  // ← Global: applies to all models
      },
      "models": {
        "gpt-5-codex-low": {
          "options": {
            "store": false  // ← Per-model: redundant but explicit
          }
        }
      }
    }
  }
}
```

--------------------------------

### Invalid Config: Duplicate Keys

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

This example demonstrates a common error where duplicate config keys are used in a JavaScript object, which is not allowed and prevents multiple variants from being defined.

```json
{
  "gpt-5-codex": {
    "id": "gpt-5-codex",
    "name": "GPT 5 Codex Low (OAuth)",
    "options": { "reasoningEffort": "low" }
  },
  "gpt-5-codex": {  // ❌ DUPLICATE KEY ERROR!
    "id": "gpt-5-codex",
    "name": "GPT 5 Codex High (OAuth)",
    "options": { "reasoningEffort": "high" }
  }
}
```

--------------------------------

### Global Options for Consistent Behavior

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Apply consistent settings like reasoningEffort, textVerbosity, and store across all models by configuring the global 'options' block.

```json
{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "high",
        "textVerbosity": "high",
        "store": false
      }
    }
  }
}
```

--------------------------------

### CLI Model Selection

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

Users select a model via the command-line interface using a specific configuration key.

```bash
$ opencode run --model=openai/gpt-5-codex-low
```

--------------------------------

### Stateless Mode Context Maintenance in TypeScript

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/ARCHITECTURE.md

This TypeScript example shows how a request in stateless mode (`store:false`) includes the full message history for context. All previous user messages, tool calls, tool outputs, and assistant responses are sent with each new user turn. IDs are stripped, and `item_reference` is filtered out.

```typescript
// Turn 3 request contains ALL previous messages:
input: [
  { role: "developer", content: "..." },      // System prompts
  { role: "user", content: "write test.txt" },     // Turn 1 user
  { type: "function_call", name: "write", ... },   // Turn 1 tool call
  { type: "function_call_output", ... },           // Turn 1 tool result
  { role: "assistant", content: "Done!" },         // Turn 1 response
  { role: "user", content: "read it" },            // Turn 2 user
  { type: "function_call", name: "read", ... },    // Turn 2 tool call
  { type: "function_call_output", ... },           // Turn 2 tool result
  { role: "assistant", content: "Contents..." },   // Turn 2 response
  { role: "user", content: "what did you write?" } // Turn 3 user (current)
]
// All IDs stripped, item_reference filtered out
```

--------------------------------

### Good Practice: Per-Model Options for Variants

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

Shows the recommended approach for configuring model variants by setting global options and overriding only the differing parameters per model.

```json
{
  "options": {
    "include": ["reasoning.encrypted_content"]
  },
  "models": {
    "gpt-5-low": {
      "id": "gpt-5",
      "options": {
        "reasoningEffort": "low",
        "textVerbosity": "low"
      }
    },
    "gpt-5-high": {
      "id": "gpt-5",
      "options": {
        "reasoningEffort": "high",
        "textVerbosity": "high"
      }
    }
  }
}
```

--------------------------------

### Unsupported Minimal Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/getting-started.md

This is a minimal configuration that is NOT supported and should not be used with GPT 5 models. It lacks necessary metadata for OpenCode features and stable operation.

```json
// ❌ DO NOT USE THIS
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-openai-codex-auth"],
  "model": "openai/gpt-5-codex"
}
```

--------------------------------

### Global and Project Config Files

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

OpenCode loads configuration from global and project-specific files. The order indicates precedence, with later files overriding earlier ones.

```plaintext
~/.config/opencode/opencode.jsonc
~/.config/opencode/opencode.json
```

```plaintext
<project>/.opencode/opencode.jsonc
<project>/.opencode/opencode.json
<parent>/.opencode/opencode.jsonc
<parent>/.opencode/opencode.json
... (up to worktree root)
```

--------------------------------

### Run Default Model with Debug Logging

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Executes the 'test' command using the 'openai/gpt-5-codex' model with debug logging enabled. Verifies that the model uses global options when no custom configuration is present.

```bash
DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/gpt-5-codex
```

```text
[openai-codex-plugin] Debug logging ENABLED
[openai-codex-plugin] Model config lookup: "gpt-5-codex" → normalized to "gpt-5-codex" for API {
  hasModelSpecificConfig: false,
  resolvedConfig: {
    reasoningEffort: 'medium',
    textVerbosity: 'medium',
    reasoningSummary: 'auto',
    include: ['reasoning.encrypted_content']
  }
}
[openai-codex-plugin] Filtering 0 message IDs from input: []

```

--------------------------------

### Run All Tests

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/test/README.md

Execute all tests in the suite once. This is the primary command for verifying the current state of the codebase.

```bash
npm test
```

--------------------------------

### Enable Full Logging for OpenCode

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/troubleshooting.md

Enable both debug and request logging for OpenCode to see detailed configuration resolution and complete request/response logs.

```bash
# Both debug and request logging
DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test"
```

--------------------------------

### Test API Access with Logging

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/getting-started.md

Test API access by running a command with logging enabled. This helps verify that requests are being sent and received correctly by the plugin.

```bash
# Enable logging to verify requests
ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5-codex
```

--------------------------------

### Run Visual Test UI

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/test/README.md

Launch the visual test user interface. This can be helpful for debugging or understanding test execution flow.

```bash
npm run test:ui
```

--------------------------------

### Setting Global Default Options

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FLOW.md

Illustrates how to set common configuration options at the global level to be inherited by all models.

```json
{
  "options": {
    "reasoningEffort": "medium",
    "reasoningSummary": "auto",
    "textVerbosity": "medium",
    "include": ["reasoning.encrypted_content"]
  }
}
```

--------------------------------

### Set reasoningSummary to Detailed

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Configure the reasoningSummary to 'detailed' to receive more verbose summaries of the reasoning process.

```json
{
  "options": {
    "reasoningSummary": "detailed"
  }
}
```

--------------------------------

### Build and Test Commands for TypeScript Project

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/AGENTS.md

Standard npm scripts for building, type checking, testing, and coverage reporting. The build script includes a step to copy an HTML file required for the OAuth callback flow.

```bash
# Build (compiles TypeScript + copies HTML file)
npm run build

# Type checking only (no build)
npm run typecheck

# Run all tests
npm test

# Watch mode for TDD
npm run test:watch

# Interactive test UI
npm run test:ui

# Coverage report
npm run test:coverage
```

--------------------------------

### Repository Directory Structure

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/DOCUMENTATION.md

Overview of the file and directory layout for the project's documentation and configuration files.

```markdown
├── README.md                      # Main entry point (users)
├── CHANGELOG.md                   # Release history
├── AGENTS.md                      # AI agent guidance
├── docs/
│   ├── index.md                   # GitHub Pages home
│   ├── README.md                  # Documentation portal
│   ├── _config.yml                # GitHub Pages config
│   └── development/               # Developer documentation
│       ├── ARCHITECTURE.md        # Technical design
│       ├── CONFIG_FLOW.md         # Config system internals
│       ├── CONFIG_FIELDS.md       # Config field reference
│       └── TESTING.md             # Test procedures
├── config/
│   ├── README.md                  # Example configs guide
│   ├── opencode-legacy.json       # Legacy full config example (v1.0.209 and below)
│   ├── opencode-modern.json       # Variant config example (v1.0.210+)
│   └── minimal-opencode.json      # Minimal config example
└── tmp/release-notes/             # Detailed release artifacts
    ├── CHANGES.md                 # Detailed v2.1.2 changes
    ├── BUGS_FIXED.md              # Bug analysis
    ├── IMPLEMENTATION_SUMMARY.md  # Implementation details
    └── VERIFICATION.md            # Verification matrix
```

--------------------------------

### Backwards Compatibility: Old Plugin + Old Config

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

Demonstrates the behavior with an older plugin version and an older configuration format. Per-model options might be broken in this scenario due to existing bugs in the old plugin.

```json
"GPT 5 Codex Low (ChatGPT Subscription)": {
  "id": "gpt-5-codex",
  "options": { "reasoningEffort": "low" }
}
```

--------------------------------

### Copy Modern Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/README.md

Use this command to copy the modern configuration file if you have OpenCode v1.0.210 or newer.

```bash
cp config/opencode-modern.json ~/.config/opencode/opencode.jsonc
```

--------------------------------

### Test Case 3: Plugin Config Lookup

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

Illustrates how the plugin finds configuration options using the original config key, not the 'id' field.

```json
{
  "gpt-5-codex-low": {
    "id": "gpt-5-codex",
    "options": { "reasoningEffort": "low" }
  }
}
```

--------------------------------

### Correct model name format in CLI

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/troubleshooting.md

When specifying a model, always include the provider prefix (e.g., 'openai/').

```yaml
model: openai/gpt-5-codex-low
```

--------------------------------

### Verify model configuration key

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/troubleshooting.md

Ensure the model name used in the CLI command exactly matches the key in your configuration file.

```json
{
  "models": {
    "gpt-5-codex-low": { ... }  // ← This is the key
  }
}
```

--------------------------------

### Multiple Variants of the Same Model

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

Illustrates how to configure multiple variants of the same base model by using distinct config keys while maintaining a common 'id'. This allows for different settings and UI display names.

```json
{
  "gpt-5-codex-low": {
    "id": "gpt-5-codex",
    "name": "GPT 5 Codex Low (OAuth)"
  },
  "gpt-5-codex-high": {
    "id": "gpt-5-codex",
    "name": "GPT 5 Codex High (OAuth)"
  }
}
```

--------------------------------

### Backwards Compatibility Test: Minimal Config (No Custom Models)

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Verifies that the plugin functions correctly with a minimal configuration that specifies a default model but no custom model definitions.

```json
{
  "plugin": ["opencode-openai-codex-auth"],
  "model": "openai/gpt-5-codex"
}
```

--------------------------------

### Mixed Configuration (Default + Custom)

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Configuration that combines default model behavior with custom model presets. This allows for a mix of globally configured models and specifically defined ones.

```json
{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "models": {
        "gpt-5-codex-low": {
          "name": "GPT 5 Codex Low (OAuth)",
          "options": { "reasoningEffort": "low" }
        }
      }
    }
  }
}
```

--------------------------------

### Backwards Compatibility Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Configuration demonstrating backwards compatibility with older config styles, ensuring that legacy model definitions with 'id' keys are still processed correctly.

```json
{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium"
      },
      "models": {
        "GPT 5 Codex Low (ChatGPT Subscription)": {
          "id": "gpt-5-codex",
          "options": { "reasoningEffort": "low" }
        }
      }
    }
  }
}
```

--------------------------------

### Common Mistake: Using id as Config Key

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

Shows an incorrect configuration where the 'id' field is used as the config key, preventing multiple variants.

```json
{
  "gpt-5-codex": {  // ❌ Can't have multiple variants
    "id": "gpt-5-codex"
  }
}
```

--------------------------------

### Check OpenAI auth file

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/troubleshooting.md

Verify the existence and content of the OpenAI authentication file to ensure OAuth credentials are present.

```bash
cat ~/.opencode/auth/openai.json
```

--------------------------------

### Custom Config with Preset Names

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Configuration for custom model presets using the new style, allowing per-model options. Default models not explicitly defined will use global options.

```json
{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium"
      },
      "models": {
        "gpt-5-codex-low": {
          "name": "GPT 5 Codex Low (OAuth)",
          "options": { "reasoningEffort": "low" }
        },
        "gpt-5-codex-high": {
          "name": "GPT 5 Codex High (OAuth)",
          "options": { "reasoningEffort": "high" }
        }
      }
    }
  }
}
```

--------------------------------

### Update and restart plugin for multi-turn issues

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/troubleshooting.md

Update the plugin to the latest version and restart OpenCode to resolve 'Item not found' errors in multi-turn conversations.

```bash
# Update plugin
npx -y opencode-openai-codex-auth@latest

# Restart OpenCode
opencode
```

--------------------------------

### Validate OpenCode Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Run the opencode command without any arguments to check if your configuration file is valid. OpenCode will display errors if the configuration is malformed.

```bash
opencode
```

--------------------------------

### GPT 5.1 Low Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/getting-started.md

Configuration for the GPT 5.1 Low model, detailing its name, context/output limits, and reasoning options.

```json
{
          "name": "GPT 5.1 Low (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "reasoningEffort": "low",
            "reasoningSummary": "auto",
            "textVerbosity": "low",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        }
```

--------------------------------

### Per-Model Configuration Options

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/ARCHITECTURE.md

Details the benefits of using per-model configuration options in OpenCode, allowing for customized settings for different Codex variants like `gpt-5-codex` and `gpt-5-nano`.

```markdown
### Why Per-Model Config Options?

**Alternative**: Single global config

**Problem**:
- `gpt-5-codex` optimal settings differ from `gpt-5-nano`
- Users want quick switching between quality levels
- No way to save "presets"

**Solution**: Per-model options in config

**Benefits**:
- ✅ Save multiple configurations
- ✅ Quick switching (no CLI args)
- ✅ Descriptive names ("Fast", "Balanced", "Max Quality")
- ✅ Persistent across sessions
```

--------------------------------

### Per-Agent Model Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

Assign different models and prompts to specific agents, such as 'commit' and 'review', to tailor their behavior for distinct tasks.

```json
{
  "agent": {
    "commit": {
      "model": "openai/gpt-5.1-codex-low",
      "prompt": "Generate concise commit messages"
    },
    "review": {
      "model": "openai/gpt-5.1-codex-high",
      "prompt": "Thorough code review"
    }
  }
}
```

--------------------------------

### Configuring Multiple Variants with Different Settings

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

This configuration pattern uses unique config keys for each variant of the same base model, allowing for different options and settings to be applied per variant.

```json
{
  "gpt-5-codex-low": {
    "id": "gpt-5-codex",
    "options": { "reasoningEffort": "low" }
  },
  "gpt-5-codex-medium": {
    "id": "gpt-5-codex",
    "options": { "reasoningEffort": "medium" }
  },
  "gpt-5-codex-high": {
    "id": "gpt-5-codex",
    "options": { "reasoningEffort": "high" }
  }
}
```

--------------------------------

### Model Switching Test

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/TESTING.md

Demonstrates switching between different models ('gpt-5-codex-low' and 'gpt-5-codex-high') during a session to verify that per-model options are applied correctly.

```bash
DEBUG_CODEX_PLUGIN=1 opencode

```

```text
> /model openai/gpt-5-codex-low
> write hello to test.txt
> /model openai/gpt-5-codex-high
> write goodbye to test2.txt

```

--------------------------------

### Recommended Model Configuration Structure

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/development/CONFIG_FIELDS.md

This structure uses a clean config key ('gpt-5-codex-low') that matches Codex CLI presets and includes a friendly display name for the TUI. The 'id' field is omitted as it's redundant for the OpenAI provider.

```json
{
  "gpt-5-codex-low": {
    "name": "GPT 5 Codex Low (OAuth)",
    "options": { "reasoningEffort": "low" }
  }
}
```

--------------------------------

### Switch to a different model

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/troubleshooting.md

If a specific model is rate-limited, switch to an alternative model (e.g., 'openai/gpt-5') to continue operations.

```bash
# If codex is rate limited, try gpt-5
opencode run "task" --model=openai/gpt-5
```

--------------------------------

### Task-Based Model Presets Configuration

Source: https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/docs/configuration.md

This JSON demonstrates how to define task-based presets for different models, allowing users to quickly switch between configurations optimized for specific tasks like chat, code generation, or debugging.

```json
{
  "models": {
    "quick-chat": {
      "name": "Quick Chat",
      "options": {
        "reasoningEffort": "minimal",
        "textVerbosity": "low",
        "store": false
      }
    },
    "code-gen": {
      "name": "Code Generation",
      "options": {
        "reasoningEffort": "medium",
        "store": false
      }
    },
    "debug-help": {
      "name": "Debug Analysis",
      "options": {
        "reasoningEffort": "high",
        "reasoningSummary": "detailed",
        "store": false
      }
    }
  }
}
```