opencode-models-discovery-wz

A universal OpenCode plugin for dynamic model discovery across any OpenAI-compatible provider.

Originally inspired by opencode-lmstudio, this project has been fully refactored into a general-purpose model discovery plugin with richer configuration controls for providers, models, naming, caching, and discovery behavior.

Features

• Universal Provider Support: Works with any OpenAI-compatible provider (LM Studio, Ollama, LocalAI, gateways, and more)
• Dynamic Model Discovery: Queries each provider's /v1/models endpoint to discover available models
• LiteLLM Auto-Enhancement: Automatically queries LiteLLM's /v1/model/info endpoint to enrich discovered models with context limits, pricing, and capability flags
• Auto-Injection: Automatically adds unconfigured models into OpenCode provider config
• Provider Filtering: Include or exclude specific providers from discovery
• Model Filtering: Use regex rules to precisely control which discovered models are injected
• Configurable Discovery: Control discovery behavior with enable/disable switches and TTL-based caching
• Smart Model Formatting: Optional human-friendly display names for discovered models
• Organization Owner Extraction: Extracts and sets organizationOwner from model IDs when available
• Health Check Monitoring: Verifies providers are accessible before attempting discovery
• Model Merging: Intelligently merges discovered models with existing configuration
• Error Handling: Smart error categorization with actionable suggestions

Installation

npm install opencode-models-discovery-wz
# or
bun add opencode-models-discovery-wz

Usage

Add the plugin to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-models-discovery-wz@latest"
  ],
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1"
      }
    },
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      }
    }
  }
}

Configuration

The plugin configuration is placed in the plugin array using tuple format ["plugin-name", { config }]:

{
  "plugin": [
    ["opencode-models-discovery-wz", {
      "providers": {
        "include": [],
        "exclude": []
      },
      "models": {
        "includeRegex": [],
        "excludeRegex": []
      },
      "discovery": {
        "enabled": true
      },
      "smartModelName": false
    }]
  ]
}

Set smartModelName to true if you want discovered models to use human-friendly display names instead of the raw model_id. (e.g., "Qwen3 30B A3B" instead of "qwen/qwen3-30b-a3b")

Provider-Level Discovery Overrides

Each provider can override discovery behavior through provider.<name>.options.modelsDiscovery:

| Option | Type | Description | |--------|------|-------------| | provider.<name>.options.modelsDiscovery.enabled | boolean | Override global discovery and provider filters for a single provider | | provider.<name>.options.modelsDiscovery.models.includeRegex | string[] | Provider-specific model include filter | | provider.<name>.options.modelsDiscovery.models.excludeRegex | string[] | Provider-specific model exclude filter | | provider.<name>.options.modelsDiscovery.smartModelName | boolean | Override global smartModelName for a single provider |

Priority rules:

1. provider.<name>.options.modelsDiscovery.enabled overrides global discovery.enabled and providers.include/exclude
2. If a provider defines its own modelsDiscovery.models filters, those filters replace global models.includeRegex/excludeRegex for that provider
3. If a provider does not define its own model filters, global models.includeRegex/excludeRegex are used
4. provider.<name>.options.modelsDiscovery.smartModelName overrides global smartModelName

{
  "plugin": [
    ["opencode-models-discovery-wz", {
      "providers": {
        "include": ["ollama"]
      },
      "models": {
        "includeRegex": ["^qwen/"]
      },
      "discovery": {
        "enabled": false
      },
      "smartModelName": false
    }]
  ],
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1",
        "modelsDiscovery": {
          "enabled": true,
          "models": {
            "includeRegex": ["^gpt-"]
          },
          "smartModelName": true
        }
      },
      "models": {}
    }
  }
}

In this example:

1. Global discovery is disabled
2. lmstudio is still discovered because modelsDiscovery.enabled is true
3. lmstudio uses ^gpt- instead of the global ^qwen/ filter
4. lmstudio uses smart model names even though the global setting is false

Provider Filtering

Control which providers are discovered:

| Option | Type | Description | |--------|------|-------------| | providers.include | string[] | If non-empty, only these providers will be discovered | | providers.exclude | string[] | These providers will be skipped (only used when include is empty) |

{
  "plugin": [
    ["opencode-models-discovery-wz", {
      "providers": {
        "include": ["ollama"],
        "exclude": ["lmstudio"]
      }
    }]
  ]
}

Model Filtering

Control which discovered models are auto-injected with regular expressions:

| Option | Type | Description | |--------|------|-------------| | models.includeRegex | string[] | If non-empty, only discovered model IDs matching at least one regex will be added | | models.excludeRegex | string[] | Discovered model IDs matching any regex will be skipped (only used when includeRegex is empty) |

Regex filtering only applies to auto-discovered models. Models already explicitly configured by the user are preserved.

{
  "plugin": [
    ["opencode-models-discovery-wz", {
      "models": {
        "includeRegex": ["^qwen/", "gpt-4"],
        "excludeRegex": ["embedding", "test"]
      }
    }]
  ]
}

How It Works

1. On OpenCode startup, the plugin's config hook is called
2. The plugin iterates through all configured providers
3. For each provider, it checks if the baseURL contains /v1/ (supports any npm package)
4. For each accessible provider, it queries the /v1/models endpoint
5. Discovered models are automatically merged into the provider's configuration
6. The enhanced configuration is used for the current session

Supported Providers

The plugin supports any OpenAI-compatible provider. Here are the most common ones:

| Provider | Default Port | Use Case | npm Package | |----------|-------------|----------|-------------| | Ollama | 11434 | Local model inference engine | @ai-sdk/openai-compatible | | LM Studio | 1234 | Local LLM with UI | @ai-sdk/openai-compatible | | LocalAI | 8080 | Self-hosted AI inference | @ai-sdk/openai-compatible | | llama.cpp Server | 8080 | Standalone llama.cpp server | @ai-sdk/openai-compatible | | Text Generation WebUI | 5000 | OpenAI-compatible extension | @ai-sdk/openai-compatible | | FastChat (Vicuna) | 8001 | Multi-model serving | @ai-sdk/openai-compatible | | vLLM | 8000 | High-performance inference | @ai-sdk/openai-compatible | | CLIProxyAPI | 8317 | A LLM proxy server | @ai-sdk/anthropic (with /v1 backend) & @ai-sdk/openai-compatible |

Anthropic API with Custom Backend

Providers using @ai-sdk/anthropic but backed by OpenAI-compatible servers (like Ollama's Anthropic compatibility mode) are also supported:

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/anthropic",
      "name": "Ollama (Anthropic Mode)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" }
    }
  }
}

Cloud OpenAI-Compatible Services

Cloud services with OpenAI-compatible APIs are also supported:

• Cloudflare Workers AI
• Azure OpenAI Service (with appropriate endpoint configuration)
• Groq (ultra-fast inference)
• Together AI
• Perplexity AI
• Any custom OpenAI-compatible API

Provider Detection

The plugin identifies OpenAI-compatible providers using two detection methods:

1. Strict Detection: npm === "@ai-sdk/openai-compatible"
2. URL-based Detection: baseURL contains /v1/ pattern

A provider is considered discoverable if either condition matches.

Examples of Supported Configurations

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" }
    }
  }
}

{
  "provider": {
    "ollama-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "Ollama (Anthropic Mode)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" }
    }
  }
}

{
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio",
      "options": { "baseURL": "http://127.0.0.1:1234/v1" }
    }
  }
}

This means providers using @ai-sdk/anthropic with OpenAI-compatible backends (like Ollama's Anthropic compatibility mode) are also supported, as long as the baseURL contains /v1/.

How It Works

1. On OpenCode startup, the plugin's config hook is called
2. The plugin iterates through all configured providers
3. For each provider, it checks if the baseURL contains /v1/ (supports any npm package)
4. For each accessible provider, it queries both the /v1/models endpoint and the LiteLLM /v1/model/info endpoint in parallel
5. If /v1/model/info returns rich metadata, the plugin merges it into discovered models (context limits, pricing, capabilities)
6. If /v1/model/info is unavailable (404), the plugin falls back to cache-based metadata or basic discovery without metadata
7. Discovered models are automatically merged into the provider's configuration
8. The enhanced configuration is used for the current session

LiteLLM Metadata Enhancement

When a provider is backed by a LiteLLM proxy server, the plugin automatically enriches discovered models with the following fields:

| LiteLLM Field | OpenCode Model Config | |---------------|----------------------| | max_input_tokens | limit.context | | max_output_tokens | limit.output | | input_cost_per_token | cost.input (converted to per-million) | | output_cost_per_token | cost.output (converted to per-million) | | supports_function_calling | tool_call | | supports_reasoning | reasoning | | supports_response_schema | structured_output | | mode + supports_vision | modalities |

This is zero-config — the plugin automatically detects LiteLLM endpoints and falls back gracefully for non-LiteLLM providers.

Requirements

• OpenCode with plugin support
• At least one OpenAI-compatible provider running locally or remotely
• Provider server API accessible (e.g., http://127.0.0.1:11434/v1)

Logging

When available, the plugin writes logs through OpenCode's structured server log API via client.app.log(...) using the service name opencode-models-discovery-wz.

If structured logging is unavailable in the runtime, the plugin falls back to prefixed console.* output. Key log categories are emitted through metadata such as plugin, config, discovery, event, and filtering to make local debugging easier with opencode --print-logs.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This project is not built by the OpenCode team and is not affiliated with OpenCode in any way.