Skip to content

README.md

Latest commit

 

History

History
182 lines (142 loc) · 5.31 KB

README.md

File metadata and controls

182 lines (142 loc) · 5.31 KB

opencode-lmstudio-sync

opencode-lmstudio-sync is an OpenCode plugin that discovers the models exposed by a local LM Studio server and merges them into the OpenCode runtime configuration at startup.

It keeps user-authored model entries intact, fills in missing metadata when available, and avoids writing back to the user's config file by default.

Features

  • Discovers authoritative model IDs from LM Studio GET /v1/models
  • Optionally enriches model names and context limits from GET /api/v1/models
  • Creates or completes the lmstudio provider at runtime when needed
  • Preserves user-defined model names and context limits by default
  • Supports optional prune and refresh flags for plugin-generated entries
  • Uses short in-memory caching to avoid repeated network calls
  • Works on Windows, macOS, and Linux

Platform Support

The plugin logic is cross-platform.

  • Windows: supported. The probe order checks 127.0.0.1:15432 and localhost:15432 first, which matches common LM Studio setups on Windows.
  • macOS: supported. If OpenCode loads the plugin from a protected folder such as Documents, the app may need explicit file access in macOS privacy settings.
  • Linux: supported. If OpenCode is installed through Flatpak or Snap, filesystem sandboxing may require additional access to the plugin directory.

Installation

Option 1: Install through OpenCode as an npm plugin

Use this after publishing the package to npm.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-lmstudio-sync@latest"]
}

Optional explicit LM Studio base URL:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-lmstudio-sync@latest"],
  "provider": {
    "lmstudio": {
      "options": {
        "baseURL": "http://127.0.0.1:15432/v1"
      }
    }
  }
}

Full explicit provider:

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

Option 2: Run it from a local checkout

  1. Clone the repository.
  2. Install dependencies.
  3. Build the project.
  4. Add a small local loader file in your OpenCode plugin directory.

Build commands:

npm install
npm run build

Local loader example:

CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
OPENCODE_DIR="$CONFIG_HOME/opencode"
PLUGIN_DIR="/absolute/path/to/opencode-lmstudio-sync"

mkdir -p "$OPENCODE_DIR/plugins"

cat > "$OPENCODE_DIR/plugins/opencode-lmstudio-sync.js" <<EOF2
export { LMStudioPlugin } from "$PLUGIN_DIR/dist/index.js";
EOF2

If your OpenCode installation uses a different config root, place the loader file inside that installation's plugin directory instead.

Base URL Resolution

The plugin resolves the LM Studio base URL in this order:

  1. provider.lmstudio.options.baseURL
  2. LM_STUDIO_BASE_URL
  3. Probing these bases in order:
    • http://127.0.0.1:15432
    • http://localhost:15432
    • http://127.0.0.1:1234
    • http://localhost:1234
    • http://127.0.0.1:8080
    • http://localhost:8080
    • http://127.0.0.1:11434
    • http://localhost:11434

Accepted values are normalized to <base>/v1.

Environment Variables

  • LM_STUDIO_BASE_URL: use an explicit LM Studio server URL
  • LM_STUDIO_API_TOKEN: optional bearer token for /api/v1/models
  • LMSTUDIO_PRUNE_MISSING=1: remove plugin-generated models that are no longer returned by /v1/models
  • LMSTUDIO_REFRESH_EXISTING=1: refresh metadata for existing plugin-generated entries

Behavior Notes

  • GET /v1/models is the source of truth for which models appear in OpenCode.
  • GET /api/v1/models is optional enrichment only.
  • User-defined name values are preserved.
  • User-defined limit.context values are preserved unless refresh is explicitly enabled for plugin-generated entries.
  • The plugin tracks generated models in memory instead of adding custom marker fields to the config.
  • The plugin mutates the runtime config object and does not write to the user's config file.

Example Runtime Merge

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-lmstudio-sync@latest"],
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:15432/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b",
          "organizationOwner": "google",
          "limit": {
            "context": 8192
          }
        }
      }
    }
  }
}

Development

npm install
npm run build
npm run typecheck
npm test

Troubleshooting

  • LM Studio is not detected: make sure the local server is running and exposing the OpenAI-compatible API.
  • Models do not appear: verify that GET /v1/models returns the expected IDs.
  • Metadata is missing: the plugin still works without /api/v1/models, but display names and context limits may be less detailed.
  • macOS cannot load the plugin from Documents: give OpenCode access to that folder or move the project to a less restricted path.
  • Linux sandboxed app cannot read the plugin directory: grant filesystem access or move the project to a path visible to the app.

License

MIT