opencode-cliproxyapi 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-25
+
+### Added
+
+- Dynamic model discovery from CLIProxyAPI's `/v1/models` endpoint.
+- OpenCode provider configuration for OpenAI-compatible chat completions.
+- Custom server URL and API key support through environment variables or
+  plugin options.
+- Automatic model names and capability hints in OpenCode's model picker.
+- Local plugin and npm package installation flows.
+
+[Unreleased]: https://github.com/yourcasualdev/opencode-cliproxyapi/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/yourcasualdev/opencode-cliproxyapi/releases/tag/v0.1.0
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 İbrahim BABAL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# OpenCode CLIProxyAPI
+
+[![CI](https://github.com/yourcasualdev/opencode-cliproxyapi/actions/workflows/ci.yml/badge.svg)](https://github.com/yourcasualdev/opencode-cliproxyapi/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/opencode-cliproxyapi)](https://www.npmjs.com/package/opencode-cliproxyapi)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Use every model exposed by [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)
+directly in [OpenCode](https://opencode.ai/).
+
+The plugin discovers CLIProxyAPI's live `/v1/models` catalog whenever OpenCode
+starts. Available models appear in the normal `/models` picker under
+**CLIProxyAPI**, with no hard-coded model list to maintain.
+
+## Quick start
+
+You need OpenCode, a running CLIProxyAPI server, and one of its API keys.
+
+### 1. Install
+
+```bash
+opencode plugin opencode-cliproxyapi --global
+```
+
+### 2. Set your connection
+
+macOS or Linux:
+
+```bash
+export CLIPROXY_BASE_URL="http://your-server:8317"
+export CLIPROXY_API_KEY="your-cli-proxy-api-key"
+```
+
+Windows PowerShell:
+
+```powershell
+$env:CLIPROXY_BASE_URL = "http://your-server:8317"
+$env:CLIPROXY_API_KEY = "your-cli-proxy-api-key"
+```
+
+The URL may include `/v1`, but it is not required. If the URL is omitted, the
+plugin uses `http://localhost:8317/v1`.
+
+These variables must be available to the process that starts OpenCode. Add them
+to your shell profile if you want them set in every new terminal.
+
+### 3. Verify
+
+```bash
+opencode models cliproxyapi
+```
+
+You should see models reported by your server:
+
+```text
+cliproxyapi/claude-sonnet-4-6
+cliproxyapi/gpt-5.6-terra
+cliproxyapi/gemini-3.1-pro-low
+```
+
+### 4. Select a model
+
+Start OpenCode and run `/models`:
+
+```bash
+opencode
+```
+
+Choose **CLIProxyAPI**, select a model, and use OpenCode normally. Restart
+OpenCode whenever the model catalog on CLIProxyAPI changes.
+
+> This release uses environment variables instead of OpenCode's `/connect`
+> screen. Model selection itself uses the standard `/models` experience.
+
+## Configuration
+
+The environment variables are the simplest and safest configuration:
+
+| Variable | Required | Default |
+| --- | --- | --- |
+| `CLIPROXY_API_KEY` | Yes, when the server requires authentication | None |
+| `CLIPROXY_BASE_URL` | No | `http://localhost:8317/v1` |
+
+Plugin options can be set in `opencode.json` when more control is needed:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "opencode-cliproxyapi",
+      {
+        "baseURL": "http://your-server:8317",
+        "providerName": "My CLIProxyAPI"
+      }
+    ]
+  ]
+}
+```
+
+Keep the API key in `CLIPROXY_API_KEY`; do not commit it to
+`opencode.json`.
+
+| Plugin option | Default | Purpose |
+| --- | --- | --- |
+| `baseURL` | `CLIPROXY_BASE_URL` or `http://localhost:8317/v1` | CLIProxyAPI URL |
+| `apiKey` | `CLIPROXY_API_KEY` | API key; prefer the environment variable |
+| `providerID` | `cliproxyapi` | ID used in `provider/model` names |
+| `providerName` | `CLIProxyAPI` | Name displayed in the model picker |
+| `protocol` | `chat` | `chat` uses `/chat/completions`; `responses` uses `/responses` |
+| `discoveryTimeoutMs` | `10000` | Startup model-discovery timeout |
+
+Existing `provider.cliproxyapi` settings are preserved, so individual models
+can be customized:
+
+```json
+{
+  "provider": {
+    "cliproxyapi": {
+      "models": {
+        "gpt-5.6-terra": {
+          "name": "Terra",
+          "limit": {
+            "context": 200000,
+            "output": 65536
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### `Missing API key`
+
+Set `CLIPROXY_API_KEY` in the same terminal that starts OpenCode:
+
+```bash
+export CLIPROXY_API_KEY="your-cli-proxy-api-key"
+```
+
+### No CLIProxyAPI models appear
+
+First check the API directly. If your base URL does not include `/v1`:
+
+```bash
+curl -H "Authorization: Bearer $CLIPROXY_API_KEY" \
+  "${CLIPROXY_BASE_URL%/}/v1/models"
+```
+
+If it already ends in `/v1`:
+
+```bash
+curl -H "Authorization: Bearer $CLIPROXY_API_KEY" \
+  "${CLIPROXY_BASE_URL%/}/models"
+```
+
+Then restart OpenCode and run:
+
+```bash
+opencode models cliproxyapi
+```
+
+### It works in one terminal but not another
+
+The second terminal or desktop launcher may not have the environment
+variables. Start OpenCode from the terminal where they are set, or configure
+the launcher to provide them.
+
+## Development
+
+```bash
+git clone https://github.com/yourcasualdev/opencode-cliproxyapi.git
+cd opencode-cliproxyapi
+bun install
+bun run check
+```
+
+The repository's `opencode.json` loads the local build for integration testing:
+
+```bash
+bun run build
+export CLIPROXY_BASE_URL="http://your-server:8317"
+export CLIPROXY_API_KEY="your-cli-proxy-api-key"
+opencode models cliproxyapi
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and
+[SECURITY.md](SECURITY.md) for private vulnerability reporting.
+
+## License
+
+[MIT](LICENSE)

package/dist/catalog.d.ts

@@ -0,0 +1,13 @@
+export type CatalogModel = {
+    id: string;
+    ownedBy?: string;
+};
+export declare function normalizeBaseURL(value: string): string;
+export declare function parseCatalog(input: unknown): CatalogModel[];
+export declare function discoverModels(input: {
+    baseURL: string;
+    apiKey?: string;
+    timeoutMs: number;
+    fetcher?: typeof fetch;
+}): Promise<CatalogModel[]>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAMD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,UAK7C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,EAAE,CAuB3D;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CACvB,2BAcA"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const CLIProxyAPIPlugin: Plugin;
+declare const _default: {
+    id: string;
+    server: Plugin;
+};
+export default _default;
+export { discoverModels, normalizeBaseURL, parseCatalog } from "./catalog.js";
+export type { CatalogModel } from "./catalog.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,MAAM,EAA+B,MAAM,qBAAqB,CAAA;AAoBtF,eAAO,MAAM,iBAAiB,EAAE,MAmD/B,CAAA;;;;;AAED,wBAGwB;AACxB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC7E,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,176 @@
+// @bun
+// src/catalog.ts
+function normalizeBaseURL(value) {
+  const url = new URL(value);
+  const pathname = url.pathname.replace(/\/+$/, "");
+  url.pathname = pathname.endsWith("/v1") ? pathname : `${pathname}/v1`;
+  return url.toString().replace(/\/$/, "");
+}
+function parseCatalog(input) {
+  if (!isRecord(input))
+    throw new Error("CLIProxyAPI returned a non-object model catalog");
+  const response = input;
+  if (!Array.isArray(response.data))
+    throw new Error("CLIProxyAPI model catalog is missing the data array");
+  const models = response.data.map((item) => {
+    if (!isRecord(item) || typeof item.id !== "string" || item.id.trim() === "")
+      return;
+    return {
+      id: item.id,
+      ...typeof item.owned_by === "string" ? { ownedBy: item.owned_by } : {}
+    };
+  }).filter((item) => item !== undefined);
+  if (models.length === 0)
+    throw new Error("CLIProxyAPI returned no usable models");
+  const unique = new Map;
+  for (const model of models) {
+    if (!unique.has(model.id))
+      unique.set(model.id, model);
+  }
+  return [...unique.values()];
+}
+async function discoverModels(input) {
+  const response = await (input.fetcher ?? fetch)(`${input.baseURL}/models`, {
+    headers: input.apiKey ? { Authorization: `Bearer ${input.apiKey}` } : undefined,
+    signal: AbortSignal.timeout(input.timeoutMs)
+  });
+  if (!response.ok) {
+    const detail = (await response.text()).trim().slice(0, 300);
+    throw new Error(`CLIProxyAPI model discovery failed with HTTP ${response.status}${detail ? `: ${detail}` : ""}`);
+  }
+  return parseCatalog(await response.json());
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/index.ts
+var DEFAULT_BASE_URL = "http://localhost:8317/v1";
+var DEFAULT_PROVIDER_ID = "cliproxyapi";
+var DEFAULT_PROVIDER_NAME = "CLIProxyAPI";
+var DEFAULT_DISCOVERY_TIMEOUT_MS = 1e4;
+var CLIProxyAPIPlugin = async ({ client }, rawOptions) => {
+  const options = readOptions(rawOptions);
+  return {
+    config: async (config) => {
+      const providerID = options.providerID ?? DEFAULT_PROVIDER_ID;
+      const existing = config.provider?.[providerID];
+      const baseURL = normalizeBaseURL(options.baseURL ?? process.env.CLIPROXY_BASE_URL ?? stringOption(existing?.options?.baseURL) ?? DEFAULT_BASE_URL);
+      const apiKey = options.apiKey ?? process.env.CLIPROXY_API_KEY ?? stringOption(existing?.options?.apiKey);
+      try {
+        const catalog = await discoverModels({
+          baseURL,
+          apiKey,
+          timeoutMs: options.discoveryTimeoutMs ?? DEFAULT_DISCOVERY_TIMEOUT_MS
+        });
+        addProvider(config, {
+          providerID,
+          providerName: options.providerName ?? DEFAULT_PROVIDER_NAME,
+          baseURL,
+          apiKey,
+          protocol: options.protocol ?? "chat",
+          catalog
+        });
+        await client.app.log({
+          body: {
+            service: "opencode-cliproxyapi",
+            level: "info",
+            message: `Discovered ${catalog.length} CLIProxyAPI models from ${baseURL}`
+          }
+        });
+      } catch (error) {
+        await client.app.log({
+          body: {
+            service: "opencode-cliproxyapi",
+            level: "error",
+            message: error instanceof Error ? error.message : String(error)
+          }
+        });
+        throw error;
+      }
+    }
+  };
+};
+var src_default = {
+  id: "opencode-cliproxyapi",
+  server: CLIProxyAPIPlugin
+};
+function addProvider(config, input) {
+  const existing = config.provider?.[input.providerID];
+  const discovered = Object.fromEntries(input.catalog.map((model) => [
+    model.id,
+    {
+      name: displayName(model.id),
+      tool_call: !isImageModel(model.id),
+      reasoning: isReasoningModel(model.id),
+      attachment: supportsAttachments(model.id),
+      ...isImageModel(model.id) ? {
+        modalities: {
+          input: ["text", "image"],
+          output: ["image"]
+        }
+      } : {}
+    }
+  ]));
+  config.provider = {
+    ...config.provider,
+    [input.providerID]: {
+      ...existing,
+      name: existing?.name ?? input.providerName,
+      npm: existing?.npm ?? (input.protocol === "responses" ? "@ai-sdk/openai" : "@ai-sdk/openai-compatible"),
+      env: [...new Set([...existing?.env ?? [], "CLIPROXY_API_KEY"])],
+      options: {
+        ...existing?.options,
+        baseURL: input.baseURL,
+        ...input.apiKey ? { apiKey: input.apiKey } : {}
+      },
+      models: {
+        ...discovered,
+        ...existing?.models
+      }
+    }
+  };
+}
+function readOptions(input) {
+  if (!input)
+    return {};
+  return {
+    baseURL: stringOption(input.baseURL),
+    apiKey: stringOption(input.apiKey),
+    providerID: stringOption(input.providerID),
+    providerName: stringOption(input.providerName),
+    protocol: input.protocol === "responses" ? "responses" : input.protocol === "chat" ? "chat" : undefined,
+    discoveryTimeoutMs: typeof input.discoveryTimeoutMs === "number" && input.discoveryTimeoutMs > 0 ? input.discoveryTimeoutMs : undefined
+  };
+}
+function stringOption(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function displayName(modelID) {
+  return modelID.split("-").map((part) => {
+    const lower = part.toLowerCase();
+    if (lower === "gpt")
+      return "GPT";
+    if (lower === "oss")
+      return "OSS";
+    if (lower === "codex")
+      return "Codex";
+    return part.charAt(0).toUpperCase() + part.slice(1);
+  }).join(" ");
+}
+function isImageModel(modelID) {
+  return /(?:^|-)image(?:-|$)/i.test(modelID);
+}
+function isReasoningModel(modelID) {
+  return /thinking|reasoning|codex|gpt-(?:5|oss)/i.test(modelID);
+}
+function supportsAttachments(modelID) {
+  return /^(?:claude|gemini|gpt)/i.test(modelID);
+}
+export {
+  parseCatalog,
+  normalizeBaseURL,
+  discoverModels,
+  src_default as default,
+  CLIProxyAPIPlugin
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "opencode-cliproxyapi",
+  "version": "0.1.0",
+  "description": "Discover and use every model exposed by CLIProxyAPI in OpenCode.",
+  "type": "module",
+  "license": "MIT",
+  "author": "İbrahim BABAL",
+  "homepage": "https://github.com/yourcasualdev/opencode-cliproxyapi#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourcasualdev/opencode-cliproxyapi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourcasualdev/opencode-cliproxyapi/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --format esm --external @opencode-ai/plugin && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test ./src",
+    "check": "bun run typecheck && bun run test && bun run build",
+    "prepublishOnly": "bun run check"
+  },
+  "keywords": [
+    "opencode",
+    "cliproxyapi",
+    "llm",
+    "plugin"
+  ],
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.18.5",
+    "@types/bun": "^1.3.5",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}