Personal fork of yuhp/opencode-models-discovery.
Discover models from OpenAI-compatible providers and add them to OpenCode automatically.
This plugin queries a provider's model endpoint, applies optional filters, and injects the discovered models into OpenCode. It supports OpenCode v2 as the primary integration and keeps a separate OpenCode v1 adapter for legacy configurations.
- Dynamic model discovery from
/v1/modelsor a configured endpoint - Provider-level enablement, endpoint overrides, timeouts, and model filters
- Optional human-friendly model names
- Optional metadata enrichment for limits, reasoning, tools, attachments, structured output, and modalities
- OpenCode v2
/connectcredentials, host-managed storage, refresh commands, and model console - OpenCode v1 XDG caching, helper commands, and compatibility with Mimocode
- Works with any provider that returns an OpenAI-compatible model-list response
OpenCode v2 uses plugins and providers. Discovery settings belong under providers.<id>.settings.modelsDiscovery and require enabled: true for that provider.
The plugin requests /v1/models by default. For a provider that exposes /models, set "endpoint": "/models". The endpoint is resolved from the provider URL's origin.
You can omit apiKey and manage credentials with OpenCode's native /connect command. Resolved credentials are used in memory and are not written to configuration, caches, or logs.
For the complete V2 configuration reference, see Configuration Guide.
/models-discovery-refreshrefreshes discovered models./models-discovery-consolebrowses providers, models, metadata, and caches.models_discovery_refreshandmodels_discovery_statusare available as agent tools.- Pass
rawCache: truetomodels_discovery_statusto inspect cached raw models and enrichment results.
V2 caching is disabled by default and uses OpenCode's host-provided storage when enabled. After rebuilding a local plugin, restart the background service with opencode service restart.
For OpenCode v1 (1.18.29+), use plugin, provider, and options:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@ybbapp/opencode-models-discovery@2.2.0"],
"provider": {
"lmstudio": {
"npm": "@ai-sdk/openai-compatible",
"name": "LM Studio",
"options": {
"baseURL": "http://127.0.0.1:1234/v1",
"modelsDiscovery": {
"enabled": true,
"smartModelName": true
}
}
}
}
}V1 discovery is configured per provider at provider.<id>.options.modelsDiscovery. V1 remains supported for compatibility, security fixes, and severe regressions; new discovery, TUI, RPC, cache, and override features target V2 first.
For V1 migration, helper commands, disk caching, filters, and legacy configuration details, see:
Enrichment is opt-in. Without modelInfoFormat, the plugin does not contact external metadata sources and leaves unknown fields unset.
Supported formats include:
aiproxy, bifrost, litellm, lmstudio, llama-swap, models.dev, ollama, omniroute, openrouter, and vllm.
Example using models.dev:
{
"modelsDiscovery": {
"enabled": true,
"modelInfoFormat": "models.dev"
}
}models.dev uses https://models.dev/models.json by default and supports a custom modelInfoEndpoint. It also reads reasoning effort tiers from models.dev's v2 catalog (https://models.dev/api.json) when the default endpoint is used. Provider-specific formats read metadata from the provider's own response or endpoint. See Model Metadata Enrichment for format-specific paths and behavior.
All options are provider-scoped. The exact configuration path depends on the host:
| Host | Configuration path |
|---|---|
| OpenCode v2 | providers.<id>.settings.modelsDiscovery |
| OpenCode v1 | provider.<id>.options.modelsDiscovery |
Frequently used options:
| Option | Description |
|---|---|
enabled |
Enable or disable discovery for one provider |
endpoint |
Model-list endpoint; defaults to /v1/models |
timeoutMs |
Per-request timeout; V2 defaults to 5000 ms and V1 to 3000 ms |
models.includeBy / excludeBy |
Filter raw top-level provider fields with equals or match |
smartModelName |
Use provider-supplied human-friendly names when available |
modelInfoFormat |
Enable provider-specific metadata enrichment |
cache.enabled |
Enable provider model caching; disabled by default |
persistModels.enabled |
V2: write successful model definitions to JSONC so they remain available during host reload; disabled by default |
To enable model persistence on OpenCode v2, add this under providers.<id>.settings.modelsDiscovery in the configuration file to update:
"persistModels": {
"enabled": true,
"path": "/absolute/path/to/opencode.jsonc"
}path is optional: the plugin uses OPENCODE_CONFIG, otherwise OPENCODE_CONFIG_DIR/opencode.jsonc or the standard XDG OpenCode config directory. Use an explicit path if your file is named opencode.json or providers are configured in a project file. The target must already contain this provider with persistence enabled. Relative paths such as ./opencode.jsonc resolve from the plugin location. Paths beginning with ~/, such as ~/.config/opencode/opencode.jsonc, expand to the current user's home directory; this also applies to environment path fallbacks.
Only successful discovery updates generated entries; failed/invalid responses leave the file untouched. Existing manual models and user-edited generated models are preserved. JSONC comments are retained, writes are atomic and serialized, and unchanged inventories do not touch the file. The plugin stores ownership hashes in persistModels.managedModels; leave that metadata to the plugin. Persisted definitions include the upstream model ID, name, limits, tools, input/output modalities, and reasoning support; provider secrets and per-variant request settings are not copied. If you change provider accounts or endpoints, review/remove generated definitions belonging to the previous provider identity before reuse. An interrupted writer may leave a .models-discovery.lock beside the file; remove it only after confirming no writer is running.
See the full configuration reference for defaults, filter semantics, cache behavior, model assembly, and V1/V2 differences.
Known issue: 2.1.3 still reproduced ModelUnavailableError in a real session during a plugin-loading window after the checks below. These checks cover refreshes of initialized plugin instances, not readiness during plugin initialization or reload. See the investigation and regression plan. The PR branch adds opt-in persistModels synchronization, which passes the isolated reload/inference reproduction by giving the host model definitions in its own config. The original restored-session path remains unverified; persistence must first be enabled and complete one successful discovery.
On OpenCode v2, discovery refresh keeps the current model inventory available until the new inventory is ready. If a provider request fails, the plugin retains that provider's last known inventory. These protections predate this fork's 2.1.3 release: failure retention was added in 4fcb883 on October 13, 2026, and deferred catalog reload in 7fbc9af on October 18, 2026; both are included in upstream v2.0.0.
Local verification of @ybbapp/opencode-models-discovery@2.1.3 on November 17, 2026 used Herdr Core terminals against the running OpenCode service:
| Scenario | Concurrent terminals | Forced refreshes |
|---|---|---|
| Three different project directories | 3 | 15 |
| The same project directory | 3 | 15 |
Each terminal also ran two concurrent model-directory readers. Across 246 reads, the catalog remained at 249 models, and sub2api/deepseek-v4-1-flash-261017 remained available. All 30 forced refreshes succeeded. This test did not reproduce a temporary missing model; it did not exercise inference requests during refresh, configuration reloads, service restarts, or provider failures, and does not establish that every historical ModelUnavailableError is fixed.
The public package is @ybbapp/opencode-models-discovery. Version 2.2.0 uses the npm dist-tag latest. Use @ybbapp/opencode-models-discovery@2.2.0 to pin that release, or @ybbapp/opencode-models-discovery@latest to follow the stable dist-tag. npm dist-tags are separate from Git tags; this local publication did not create a Git tag.
- Configuration Guide
- Provider Compatibility
- Connect and Auth
- Migrate V1 to V2
- Persisted Model Discovery Cache
- Upgrade Guide
- Community configuration examples
- OpenCode with plugin support
- At least one local or remote OpenAI-compatible provider
- A provider model-list endpoint returning an OpenAI-compatible response
For local plugin development, run npm run compile and reference the generated directory with file:///absolute/path/to/opencode-models-discovery/dist. OpenCode v2 expects a directory rather than a direct JavaScript entry file.
Contributions are welcome. Please feel free to submit a pull request. Community provider examples should be added under docs/config_example/ on the community/config-examples branch.
MIT
This project is not built by the OpenCode team and is not affiliated with OpenCode. It is also not affiliated with, endorsed by, or sponsored by models.dev. The optional models.dev metadata source is used only when explicitly configured.
{ "$schema": "https://opencode.ai/config.json", "plugins": [ "@ybbapp/opencode-models-discovery@2.2.0" ], "providers": { "gateway": { "name": "My Gateway", "package": "@opencode/ai/providers/openai-compatible", "settings": { "baseURL": "https://gateway.example.com/v1", "apiKey": "{env:GATEWAY_API_KEY}", "modelsDiscovery": { "enabled": true, "smartModelName": true, "models": { "includeBy": [{ "field": "id", "match": "^(gpt|gemini)" }] } } } } } }