@hellogravel/opencode-lms

An LM Studio provider plugin for OpenCode.

What it does

• Discovers the chat models your LM Studio server is hosting and exposes them in OpenCode. Embedding models are filtered out by default (OpenCode has no slot that consumes them); list one in provider.lmstudio.models to opt it back in.
• Loads an unloaded LLM on first reference; load progress is logged to the OpenCode server log. Loads at a capped context window (contextLength, default 32k — agent sessions open well past 8k) to keep VRAM in check, and tags the model with an idle ttl (default 1h) so it auto-evicts when unused. A resident instance loaded with a smaller window than the policy is evicted and reloaded at it; concurrent sessions referencing the same cold model share a single load.
• Self-heals when LM Studio starts after OpenCode: discovery is retried on demand (throttled to 30s) from the first request that needs it, so auto-load and model listing recover without an OpenCode restart.
• Forwards an Authorization: Bearer … header to LM Studio when apiKey is set.
• Demotes reasoning_effort: "max" to "xhigh" before requests leave OpenCode, since LM Studio rejects max.
• Sets each model's OpenCode capability flags from what LM Studio reports — reasoning, attachment (vision models), temperature, family, etc. — and marks reasoning-capable models with interleaved: { field: "reasoning_content" } so OpenCode renders the streaming reasoning trace live in the TUI. Tool calling is always advertised as available (LM Studio's trained_for_tool_use flag is unreliable as a gate, so it's used only for a discovery-log diagnostic, not to disable tools).
• Suppresses OpenCode's auto-generated reasoning-effort picker (low/medium/high) for models that only support binary on/off reasoning, since every choice would route to "on" inside LM Studio anyway. Graduated reasoning models keep the picker.

Compatibility

Requires OpenCode ≥ 1.16.2 (validated on 1.17.15). The @opencode-ai/plugin dependency pin governs the plugin API types only, not the OpenCode runtime version you run against.

Set up

Add the plugin and provider to ~/.config/opencode/opencode.jsonc:

{
  "provider": {
    "lmstudio": {
      "name": "LM Studio",
      "options": {
        "baseURL": "http://127.0.0.1:1234",
        "apiKey": "sk-lm-..."
      }
    }
  },
  "model": "lmstudio/google/gemma-4-26b-a4b",
  "plugin": ["@hellogravel/opencode-lms"]
}

Start LM Studio's server (lms server start) and restart OpenCode.

• This plugin extends OpenCode's built-in lmstudio provider in place — it supplies the live model list via OpenCode's provider.models hook. Do not add lmstudio to disabled_providers, or the plugin's models get disabled too.
• apiKey is only needed when LM Studio has API token auth enabled.
• baseURL should not include a /v1 suffix — the plugin appends it.

Upgrading from a pre-0.2 build? The provider id changed from lms to lmstudio. Rename the provider.lms config key to provider.lmstudio, update any "model": "lms/…" reference to "lmstudio/…", and drop the old "disabled_providers": ["lmstudio"] line.

Options

Under provider.lmstudio.options:

| Option | Type | Default | Description | |---|---|---|---| | baseURL | string | "http://127.0.0.1:1234" | LM Studio server URL | | apiKey | string | — | Bearer token sent in the Authorization header | | autoDetect | boolean | true | When baseURL is not set, probe localhost ports 1234, 8080, 11434 | | disableAutoLoad | boolean | false | Skip the auto-load step on first model reference | | autoDownload | boolean | false | Download a missing model on first reference (off by default — a typo could trigger a multi-GB download) | | loadTimeout | number | 600000 | Load/unload timeout in ms | | downloadTimeout | number | 1800000 | Download timeout in ms | | timeout | number | 600000 | Overall chat-completion request timeout in ms | | chunkTimeout | number | 120000 | Inter-chunk (time-to-next-token) timeout in ms — raise for SWA models (see note) | | contextLength | number | 32768 | Global cap on the context window a model is loaded with (the VRAM knob). A model whose max is below this loads at its max; adjust per-model with models[<id>].contextLength. A resident instance with a smaller window is unloaded and reloaded at this value on first use, and the advertised limit.context follows it, so OpenCode budgets against the real window | | ttl | number | 3600 | Idle seconds before a loaded model auto-evicts (frees VRAM), sent on each chat completion. The countdown resets on every request, so active models stay resident. 0 = resident (never auto-evict). Reach is limited by LM Studio's API — see the TTL note below |

TTL vs auto-load (LM Studio ≤0.4.19): LM Studio applies a request's ttl only when that request JIT-loads the model; it ignores ttl on already-loaded instances, and the REST load endpoint rejects a ttl key outright (HTTP 400). Since this plugin auto-loads cold models via REST (to apply contextLength), plugin-loaded models evict on LM Studio's server-default idle TTL, not options.ttl. The configured ttl fully applies only when disableAutoLoad is set (JIT loads — which also bypass the context cap). Verified live on 0.4.19.

SWA models (e.g. Gemma) and chunkTimeout: llama.cpp can't reuse the prompt cache for sliding-window-attention models, so every turn reprocesses the entire prompt from scratch. No streamed chunks are emitted during that prompt-processing phase, so a large prompt can exceed chunkTimeout before the first token — the request aborts and retries, reprocessing from 0% again, looping indefinitely. If you see prompt processing restart from 0% repeatedly, raise chunkTimeout (e.g. to match timeout) and/or shrink the prompt by disabling unused tools/MCP servers.

Model overrides

Override per-model metadata under provider.lmstudio.models[<id>]:

"models": {
  "google/gemma-4-e4b": {
    "name": "Gemma 4 E4B",
    "reasoning": true,
    "contextLength": 32768,
    "limit": { "context": 131072, "output": 131072 }
  }
}

| Field | Type | Description | |---|---|---| | id | string | LM Studio model identifier (e.g. google/gemma-4-e4b) | | name | string | Display name | | reasoning | boolean | Mark the model as reasoning-capable | | tool_call | boolean | Mark the model as supporting tool calls | | modalities | object | e.g. { input: ["text","image"], output: ["text"] } | | limit | object | { context: <ctx>, output: <out> } — UI metadata, not the load-time window | | contextLength | number | Load-time context window for this model (the VRAM knob); overrides the global contextLength, still clamped to the model's max |

Overrides merge on top of discovered models.

Development

git clone https://github.com/hellogravel/opencode-lms
cd opencode-lms
npm install
npm run build       # Compile TypeScript → dist/
npm run typecheck
npm run test:run

For a containerized OpenCode runtime with this plugin loaded, see docker/.

docker/smoke.sh boots that harness (latest OpenCode, plugin baked in) and asserts GET /config/providers returns 200 and lists lmstudio — the loader-level regression check the unit suite can't cover. Run it before a release and after any OpenCode version bump.

test-live.mjs exercises the plugin against a live LM Studio server:

npm run build
LMS_BASE_URL=http://192.168.1.10:1234 \
LMS_API_KEY=sk-lm-... \
  node test-live.mjs

License

MIT