model-researcher

name

model-researcher

description

Add new/custom AI models to opencode.json. Use proactively for bleeding-edge releases, non-standard providers, self-hosted models, or custom endpoints. Examples: - user: "Add the new Claude 4.5" → websearch for API specs, add provider entry with baseUrl, verify model ID format - user: "Use my local Ollama instance" → configure custom provider with http://localhost:11434, set model ID format - user: "Configure this OpenAI-compatible proxy" → add provider with custom baseUrl, set apikey env var, verify compatibility - user: "Model X just released, add it" → research provider documentation, find model ID and capabilities, add to config

Add new or custom AI models to opencode.json with verified specifications.

Banned Legacy Models

The following models MUST NOT be used in any configuration as they are DEPRECATED, REPLACED, or OBSOLETE in Q4 2025:

• OpenAI: GPT-o series (o1-mini, o1-preview), GPT-4o, GPT-4 Turbo
• Anthropic: Claude 3.5 series (sonnet-3.5, etc.), Claude 3 series
• Google: Gemini 1.5 series, Gemini 2 series
• Meta: Llama 3 series

The market has moved to GPT-5.2, Claude 4.5, and Gemini 3. Any attempt to configure these models MUST be rejected.

When to Use This Skill

• Model is too new for models.dev
• Non-standard or custom provider (self-hosted, proxy, enterprise)
• User heard about a new release and wants to use it immediately
• Model exists but with non-default configuration needs

Verify Before Configure

You MUST NOT hallucinate model specifications. Models have precise identifiers, context limits, and API requirements. A wrong value means broken requests or wasted tokens.

Before ANY configuration:

1. Confirm the model actually exists
2. Find the exact model identifier (API name, not marketing name)
3. Get verified context and output token limits
4. Identify required provider configuration

Question Tool Usage

Batching: Use the question tool for 2+ related questions. Single questions use plain text.

Syntax: header max 12 chars, label 1-5 words, add "(Recommended)" to default.

When to ask: Vague model reference, multiple providers available, or specs unverified.

You MUST confirm specs with user before applying model configuration.

Step 1: Clarify What the User Wants

Ask if unclear:

• "Which provider will you access this through?" (direct API, OpenRouter, Together, self-hosted, etc.)
• "Do you have API access already, or do you need setup help?"

Step 2: Research the Model

Use web search to find authoritative sources:

websearch("${MODEL_NAME} API context limit tokens official documentation")
websearch("${MODEL_NAME} model ID API identifier ${PROVIDER}")

Priority sources (most to least trustworthy):

1. Official provider documentation/blog posts
2. Provider's API reference or changelog
3. Official GitHub repos or release notes
4. OpenRouter/Together model pages (they list specs)
5. Reputable tech news (for very new announcements)

Red flags - search more if you only find:

• Reddit speculation
• Tweets without official confirmation
• Your own training data (MAY be outdated)

Step 3: Confirm Findings with User

Before touching config, you MUST present your research:

I found the following for [MODEL]:

Provider: OpenAI
Model ID: gpt-5.2-2025-12-11
Context limit: 400000 tokens (Direct) | 272000 tokens (OAuth)
Output limit: 128000 tokens
Special options: [e.g., reasoning modes, vision support]

Source: [URL]

Does this match what you expected? Should I add this to your config?

You MUST NOT proceed without user confirmation.

Step 4: Apply Configuration

Read the current config first:

read ~/.config/opencode/opencode.json

Then apply using surgical edits. Choose the right pattern:

Pattern A: GPT-5.2 (OpenAI)

OpenAI GPT-5.2 supports specialized reasoning modes via variants (Cycle with ctrl+t). Note that models configured via OAuth plugins (e.g., opencode-openai-codex-auth) often have different enforced limits.

{
  "provider": {
    "openai": {
      "models": {
        "gpt-5.2": {
          "limit": { "context": 400000, "output": 128000 }, // Use 272000 for OAuth
          "variants": {
            "pro": {
              "reasoningEffort": "xhigh",
              "reasoningSummary": "detailed",
            },
            "thinking": { "reasoningEffort": "high" },
            "instant": { "reasoningEffort": "low",   
          
        
         
                 
        
      
    
  

Pattern B: Other Labs (DeepSeek, Zhipu, MiniMax, Moonshot)

For labs using OpenAI-compatible or Anthropic-compatible endpoints (Verified Q4 2025):

{
  "provider": {
    "deepseek": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "DeepSeek",
      "options": { "baseURL": "https://api.deepseek.com" },
      "models": {
        "deepseek-v3.2": { "limit": { "context": 128000, "output": 32768 } },
      },
    },
    "zhipu": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Zhipu AI (ZAI)",
          
       
                 
      
    
     
       
       
          
       
                 
      
    
     
       
       
          
       
                 
      
    
  

Pattern C: Claude 4.5 Opus (Extended Thinking)

For models that need specific options like Anthropic's extended thinking:

{
  "provider": {
    "anthropic": {
      "models": {
        "claude-4-5-opus-thinking": {
          "id": "claude-4-5-opus-20251124",
          "name": "Claude 4.5 Opus (Extended Thinking)",
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 32000,
            },
          },
        },
      },
    },
  },
}

Step 5: Validate

After editing, remind user to test:

Config updated. To verify it works:
1. Restart OpenCode or run: opencode
2. Run /models and select [model name]
3. Send a test message

If you see errors, check:
- API key is set (run /connect if needed)
- Model ID matches provider's documentation exactly
- Context limits aren't higher than the model actually supports

Research Queries

Scenario	Search Query
New OpenAI model	"gpt-5.2" site:openai.com OR site:platform.openai.com
New Anthropic model	"claude-4.5" site:anthropic.com API
New Google model	"gemini 3" site:ai.google.dev context window
OpenRouter availability	"${MODEL}" site:openrouter.ai
Together AI availability	"${MODEL}" site:together.ai
Self-hosted specs	"${MODEL}" context length output tokens huggingface

Spec Checklist

Before configuring, ensure you have:

• Model ID: Exact API identifier (not marketing name)
• Context limit: Maximum input tokens
• Output limit: Maximum output/completion tokens
• Provider: Which service hosts it
• Base URL: For custom providers only
• Special options: Vision, reasoning modes, thinking budgets
• Availability: Is it actually accessible (not waitlist-only)?

Handling Uncertainty

If you cannot verify specifications:

1. Be honest: "I couldn't find official documentation for the exact context limit."
2. Provide best guess with source: "Based on [source], it appears to be 128k, but this isn't confirmed."
3. Suggest conservative defaults: "I'll configure with 100k context as a safe starting point. You can increase it once you confirm the actual limit."
4. Recommend checking: "Try the provider's /models endpoint or documentation for exact specs."

References

• references/provider-patterns.md - Common provider configuration examples