ocx-cursor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hiddenest
+
+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,130 @@
+# OpenCodex Cursor Bridge
+
+[![npm version](https://img.shields.io/npm/v/ocx-cursor.svg)](https://www.npmjs.com/package/ocx-cursor)
+[![CI](https://github.com/hiddenest/opencodex-cursor-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/hiddenest/opencodex-cursor-bridge/actions/workflows/ci.yml)
+
+Use active [OpenCodex](https://github.com/lidge-jun/opencodex) models in Cursor through its custom OpenAI endpoint. The package runs a local gateway and keeps Cursor's custom model list in sync.
+
+## Requirements
+
+- macOS with Cursor installed at `/Applications/Cursor.app`
+- Node.js 22.5 or newer
+- OpenCodex installed, signed in, and running
+- An HTTPS hostname that forwards to `http://127.0.0.1:10101`
+
+Launch Cursor and sign in once before setup. Cursor creates the Safe Storage key that the installer uses to encrypt the gateway API key.
+
+## Set up an HTTPS endpoint
+
+Cursor's custom OpenAI endpoint must use HTTPS. Point a tunnel or reverse proxy at the local gateway on port `10101`.
+
+This Cloudflare Tunnel config maps `cursor-api.example.com` to the gateway:
+
+```yaml
+# ~/.cloudflared/config.yml
+tunnel: YOUR_TUNNEL_ID
+credentials-file: /Users/YOU/.cloudflared/YOUR_TUNNEL_ID.json
+
+ingress:
+  - hostname: cursor-api.example.com
+    service: http://127.0.0.1:10101
+  - service: http_status:404
+```
+
+Create the DNS route and run the tunnel:
+
+```bash
+cloudflared tunnel route dns YOUR_TUNNEL_NAME cursor-api.example.com
+cloudflared tunnel run YOUR_TUNNEL_NAME
+```
+
+The package does not install or manage the tunnel.
+
+## Install
+
+Quit Cursor, confirm that OpenCodex is running, then run:
+
+```bash
+npx ocx-cursor init \
+  --base-url https://cursor-api.example.com/v1
+```
+
+`init` performs these actions:
+
+1. Generates a gateway API key in `~/.opencodex/cursor-bridge/secret`.
+2. Stores the key in Cursor with macOS Safe Storage encryption.
+3. Registers the HTTPS URL as Cursor's OpenAI base URL.
+4. Installs the `com.opencodex.cursor-bridge` LaunchAgent.
+5. Adds active OpenCodex models to Cursor under `opencodex/*`.
+
+The installer links `ocx-cursor` into `~/.local/bin`. Add that directory to `PATH` if your shell does not include it:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+Open Cursor after `init` finishes. Models with known reasoning controls show an effort value in the picker. Use `Shift+Command+/` to cycle it.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `ocx-cursor init --base-url URL` | Configure Cursor, install the service, and sync models. Cursor must be closed. |
+| `ocx-cursor install` | Reinstall or restart the LaunchAgent without changing Cursor's API settings. |
+| `ocx-cursor sync` | Refresh the active model catalog. The service queues the update while Cursor runs. |
+| `ocx-cursor status` | Show service health, model count, and pending sync state. |
+| `ocx-cursor uninstall` | Remove the LaunchAgent, command link, and bridge home directory. |
+
+`uninstall` leaves Cursor's custom endpoint and model records in its state database.
+
+## Model mapping
+
+The bridge maps source model IDs to Cursor aliases:
+
+```text
+anthropic/claude-sonnet-5  -> opencodex/claude-sonnet-5
+gpt-5.6-sol                -> opencodex/gpt-5.6-sol
+```
+
+The catalog includes models returned by OpenCodex's active `/v1/models` endpoint. It excludes the OpenCodex `cursor/*` provider to avoid duplicating Cursor's own models.
+
+Cursor removes custom effort metadata from its database during startup. The LaunchAgent writes that metadata back after Cursor exits, once all Cursor Helper processes have stopped.
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `OCX_CURSOR_BASE_URL` | Stored Cursor URL | HTTPS endpoint used by `init` when `--base-url` is absent. |
+| `OCX_CURSOR_HOME` | `~/.opencodex/cursor-bridge` | Service state, API key, catalog, and logs. |
+| `OCX_CURSOR_HOST` | `127.0.0.1` | Local gateway bind address. |
+| `OCX_CURSOR_PORT` | `10101` | Local gateway port. |
+| `OCX_BIN` | `~/.local/bin/ocx` | OpenCodex CLI path. |
+
+The gateway accepts these routes:
+
+- `GET /v1/models`
+- `POST /v1/chat/completions`
+- `POST /v1/responses` and `/v1/responses/compact`
+- `POST /v1/messages`
+
+The gateway requires its generated bearer token on each `/v1/*` request. It binds to loopback unless you change `OCX_CURSOR_HOST`.
+
+## Development
+
+```bash
+npm test
+npm run check
+npm pack --dry-run
+```
+
+The code uses `node:sqlite`, so development requires Node.js 22.5 or newer.
+
+## Compatibility
+
+The package writes Cursor's local state database and uses Cursor's Safe Storage format. Cursor does not document either interface. A Cursor update can change them.
+
+The current release supports macOS. It does not configure Windows Credential Manager, Linux keyrings, or system services outside launchd.
+
+## License
+
+MIT

package/bin/ocx-cursor.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { configureCursorOpenAI, storedCursorOpenAIBaseUrl } from "../src/cursor-config.mjs";
+import { cursorIsRunning } from "../src/cursor-state.mjs";
+import { installService, prepareInstallSecret, serviceStatus, uninstallService } from "../src/install.mjs";
+import { cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
+import { runService } from "../src/service.mjs";
+import { loadCatalogSnapshot, syncNow } from "../src/sync.mjs";
+
+const usage = `OpenCodex Cursor Bridge
+
+Usage:
+  ocx-cursor init --base-url <https-url>
+                        Configure Cursor, install the service, and sync models
+  ocx-cursor install    Install and start the macOS companion service
+  ocx-cursor sync       Sync active OpenCodex models into Cursor
+  ocx-cursor status     Show service and model-sync status
+  ocx-cursor uninstall  Stop and remove the companion service
+  ocx-cursor service    Run the service in the foreground (internal)
+`;
+
+function argumentValue(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? "" : String(process.argv[index + 1] || "");
+}
+
+function normalizedBaseUrl(value) {
+  if (!value) {
+    throw new Error("Pass --base-url https://your-domain.example/v1 or set OCX_CURSOR_BASE_URL");
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Invalid Cursor OpenAI base URL: ${value}`);
+  }
+  if (url.protocol !== "https:") throw new Error("Cursor OpenAI base URL must use HTTPS");
+  url.pathname = url.pathname.replace(/\/$/, "");
+  if (!url.pathname.endsWith("/v1")) throw new Error("Cursor OpenAI base URL must end with /v1");
+  return url.toString().replace(/\/$/, "");
+}
+
+async function pendingCount() {
+  try {
+    const value = JSON.parse(await readFile(pendingFile, "utf8"));
+    return Array.isArray(value) ? value.length : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function printSync(result) {
+  const effort = `${result.effortCount} with effort selector`;
+  if (result.status === "queued") {
+    process.stdout.write(`Queued ${result.modelCount} active models (${effort}); they will be applied after Cursor quits.\n`);
+  } else {
+    process.stdout.write(`Synced ${result.modelCount} active models (${effort}).\nBackup: ${result.backupPath}\n`);
+  }
+}
+
+async function main() {
+  const command = process.argv[2] || "help";
+  if (["help", "--help", "-h"].includes(command)) {
+    process.stdout.write(usage);
+    return;
+  }
+  if (["--version", "-v"].includes(command)) {
+    const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    process.stdout.write(`${pkg.version}\n`);
+    return;
+  }
+
+  if (command === "install") {
+    const installed = await installService();
+    process.stdout.write(`Installed ${installed.launchAgentFile} (API key ${installed.secretStatus}).\nCLI: ${installed.cliLinkFile}\n`);
+    printSync(await syncNow());
+    process.stdout.write("Endpoint: http://127.0.0.1:10101/v1\n");
+    return;
+  }
+  if (command === "init") {
+    if (cursorIsRunning()) {
+      throw new Error("Quit Cursor before running ocx-cursor init so model variants and effort selectors can be applied");
+    }
+    const baseUrl = normalizedBaseUrl(
+      argumentValue("--base-url") || cursorOpenAIBaseUrl || storedCursorOpenAIBaseUrl(),
+    );
+    const prepared = await prepareInstallSecret();
+    const configured = await configureCursorOpenAI({
+      secret: prepared.secret,
+      baseUrl,
+    });
+    process.stdout.write(configured.changed
+      ? `Configured Cursor OpenAI endpoint: ${baseUrl}\nBackup: ${configured.backupPath}\n`
+      : `Cursor OpenAI endpoint is already configured: ${baseUrl}\n`);
+    const installed = await installService();
+    process.stdout.write(`Installed ${installed.launchAgentFile} (API key ${installed.secretStatus}).\nCLI: ${installed.cliLinkFile}\n`);
+    printSync(await syncNow());
+    return;
+  }
+  if (command === "sync") {
+    printSync(await syncNow());
+    return;
+  }
+  if (command === "status") {
+    const [status, catalog, pending] = await Promise.all([
+      serviceStatus(),
+      loadCatalogSnapshot(),
+      pendingCount(),
+    ]);
+    process.stdout.write([
+      `Installed: ${status.installed ? "yes" : "no"}`,
+      `Service: ${status.loaded ? "running" : "stopped"}`,
+      `Gateway: ${status.health?.status === "ok" ? `healthy (${status.health.models} models)` : "unavailable"}`,
+      `Catalog: ${catalog.length} active models`,
+      `Pending Cursor sync: ${pending ? `${pending} models` : "none"}`,
+      `Home: ${status.installRoot}`,
+    ].join("\n") + "\n");
+    return;
+  }
+  if (command === "uninstall") {
+    await uninstallService();
+    process.stdout.write("Uninstalled OpenCodex Cursor Bridge.\n");
+    return;
+  }
+  if (command === "service") {
+    await runService();
+    return;
+  }
+  throw new Error(`Unknown command: ${command}\n\n${usage}`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message || error}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "ocx-cursor",
+  "version": "0.1.0",
+  "description": "OpenCodex companion service for Cursor custom models",
+  "keywords": [
+    "opencodex",
+    "cursor",
+    "llm",
+    "proxy"
+  ],
+  "homepage": "https://github.com/hiddenest/opencodex-cursor-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/hiddenest/opencodex-cursor-bridge/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hiddenest/opencodex-cursor-bridge.git"
+  },
+  "author": "hiddenest",
+  "type": "module",
+  "bin": {
+    "ocx-cursor": "bin/ocx-cursor.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check bin/ocx-cursor.mjs && find src -maxdepth 1 -name '*.mjs' -print0 | xargs -0 -n1 node --check",
+    "prepublishOnly": "npm test && npm run check"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/catalog.mjs

@@ -0,0 +1,117 @@
+import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { managedPrefix, opencodexConfigFile, opencodexServiceTokenFile } from "./paths.mjs";
+
+export const allowedEfforts = ["low", "medium", "high", "xhigh", "max"];
+export const effortLabels = {
+  low: "Low",
+  medium: "Medium",
+  high: "High",
+  xhigh: "Extra High",
+  max: "Max",
+};
+
+export function opencodexEndpoint() {
+  let config = {};
+  try {
+    config = JSON.parse(execFileSync("/bin/cat", [opencodexConfigFile], { encoding: "utf8" }));
+  } catch {}
+  const port = Number(config.port || 10100);
+  const configuredHost = String(config.hostname || "127.0.0.1");
+  const host = configuredHost === "0.0.0.0" || configuredHost === "::" ? "127.0.0.1" : configuredHost;
+  return { host, port };
+}
+
+export function aliasFor(sourceId) {
+  return sourceId.startsWith("anthropic/claude-")
+    ? `${managedPrefix}${sourceId.slice("anthropic/".length)}`
+    : `${managedPrefix}${sourceId}`;
+}
+
+export function inferredEfforts(sourceId) {
+  const modelId = sourceId.split("/").at(-1);
+  if (/^claude-(?:fable-5|sonnet-5|opus-(?:5|4-[78]))$/.test(modelId)) return [...allowedEfforts];
+  if (/^claude-(?:opus-4-6|sonnet-4-6)$/.test(modelId)) return ["low", "medium", "high", "max"];
+  if (/^gpt-5\.6-(?:luna|sol|terra)$/.test(modelId)) return [...allowedEfforts];
+  if (/^gpt-5\.[45](?:$|-)/.test(modelId)) return ["low", "medium", "high", "xhigh"];
+  return [];
+}
+
+export function sanitizeEfforts(sourceId, configured) {
+  const values = Array.isArray(configured) ? configured : inferredEfforts(sourceId);
+  return allowedEfforts.filter((effort) => values.includes(effort));
+}
+
+export function normalizeActiveCatalog(configured, active) {
+  const configuredById = new Map(configured
+    .filter((model) => typeof model.provider === "string" && typeof model.model === "string")
+    .map((model) => [`${model.provider}/${model.model}`, model]));
+  const models = new Map();
+
+  for (const model of active) {
+    if (typeof model?.id !== "string" || model.owned_by === "opencodex" || model.id.startsWith("cursor/")) continue;
+    const configuredModel = configuredById.get(model.id);
+    const provider = model.id.includes("/") ? model.id.split("/", 1)[0] : String(model.owned_by || "openai").toLowerCase();
+    const inputModalities = Array.isArray(configuredModel?.inputModalities)
+      ? configuredModel.inputModalities
+      : Array.isArray(model.capabilities?.input_modalities)
+        ? model.capabilities.input_modalities
+        : ["text", "image"];
+    models.set(model.id, {
+      alias: aliasFor(model.id),
+      sourceId: model.id,
+      provider,
+      contextWindow: Number.isFinite(configuredModel?.contextWindow)
+        ? configuredModel.contextWindow
+        : model.capabilities?.context_length,
+      maxOutputTokens: model.capabilities?.max_output_tokens,
+      inputModalities,
+      reasoningEfforts: sanitizeEfforts(model.id, configuredModel?.reasoningEfforts ?? model.capabilities?.reasoning_effort),
+    });
+  }
+
+  return [...models.values()].sort((left, right) => left.alias.localeCompare(right.alias));
+}
+
+async function optionalServiceToken() {
+  try {
+    return (await readFile(opencodexServiceTokenFile, "utf8")).trim();
+  } catch {
+    return "";
+  }
+}
+
+export function configuredModels(ocxBin = process.env.OCX_BIN || join(homedir(), ".local", "bin", "ocx")) {
+  let executable = ocxBin;
+  try {
+    execFileSync(executable, ["--version"], { stdio: "ignore" });
+  } catch {
+    executable = "/opt/homebrew/bin/ocx";
+  }
+  const output = execFileSync(executable, ["models", "--json"], { encoding: "utf8" });
+  const payload = JSON.parse(output);
+  if (!Array.isArray(payload.models)) throw new Error("ocx models --json returned an invalid catalog");
+  return payload.models;
+}
+
+export async function activeModels(fetchImpl = fetch) {
+  const { host, port } = opencodexEndpoint();
+  const token = await optionalServiceToken();
+  const response = await fetchImpl(`http://${host}:${port}/v1/models`, {
+    headers: token ? { authorization: `Bearer ${token}` } : {},
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!response.ok) throw new Error(`OpenCodex /v1/models returned HTTP ${response.status}`);
+  const payload = await response.json();
+  if (!Array.isArray(payload.data)) throw new Error("OpenCodex /v1/models returned an invalid catalog");
+  return payload.data;
+}
+
+export async function buildActiveCatalog(options = {}) {
+  return normalizeActiveCatalog(
+    configuredModels(options.ocxBin),
+    await activeModels(options.fetchImpl),
+  );
+}

package/src/cursor-config.mjs

@@ -0,0 +1,96 @@
+import { execFileSync } from "node:child_process";
+import { createCipheriv, pbkdf2Sync } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { backup, DatabaseSync } from "node:sqlite";
+import { cursorIsRunning } from "./cursor-state.mjs";
+import { cursorDatabaseFile, installRoot } from "./paths.mjs";
+
+const applicationStorageKey = "src.vs.platform.reactivestorage.browser.reactiveStorageServiceImpl.persistentStorage.applicationUser";
+const openAISecretKey = "secret://cursorAuth/openAIKey";
+
+function cursorSafeStoragePassword() {
+  try {
+    return execFileSync("security", [
+      "find-generic-password",
+      "-w",
+      "-a", "Cursor Key",
+      "-s", "Cursor Safe Storage",
+    ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    throw new Error("Cursor Safe Storage key was not found. Launch and sign in to Cursor once, then rerun init.");
+  }
+}
+
+export function encryptedCursorSecret(secret, password) {
+  const key = pbkdf2Sync(password, "saltysalt", 1003, 16, "sha1");
+  const cipher = createCipheriv("aes-128-cbc", key, Buffer.alloc(16, 0x20));
+  const encrypted = Buffer.concat([Buffer.from("v10"), cipher.update(secret, "utf8"), cipher.final()]);
+  return JSON.stringify({ type: "Buffer", data: [...encrypted] });
+}
+
+export function applyOpenAISettings(state, baseUrl) {
+  state.useOpenAIKey = true;
+  state.openAIBaseUrl = baseUrl;
+  return state;
+}
+
+export function storedCursorOpenAIBaseUrl(databasePath = cursorDatabaseFile) {
+  try {
+    const database = new DatabaseSync(databasePath, { readOnly: true });
+    const row = database.prepare("SELECT value FROM ItemTable WHERE key = ?").get(applicationStorageKey);
+    database.close();
+    const value = JSON.parse(row?.value || "{}").openAIBaseUrl;
+    return typeof value === "string" ? value : "";
+  } catch {
+    return "";
+  }
+}
+
+export async function configureCursorOpenAI(options) {
+  const databasePath = options.databasePath || cursorDatabaseFile;
+  const backupDirectory = options.backupDirectory || installRoot;
+  const password = options.safeStoragePassword || cursorSafeStoragePassword();
+  const encryptedSecret = encryptedCursorSecret(options.secret, password);
+  const database = new DatabaseSync(databasePath);
+  const stateRow = database.prepare("SELECT value FROM ItemTable WHERE key = ?").get(applicationStorageKey);
+  const secretRow = database.prepare("SELECT value FROM ItemTable WHERE key = ?").get(openAISecretKey);
+  if (!stateRow?.value) {
+    database.close();
+    throw new Error("Cursor application user storage was not found");
+  }
+
+  const state = JSON.parse(stateRow.value);
+  const alreadyConfigured = state.useOpenAIKey === true
+    && state.openAIBaseUrl === options.baseUrl
+    && secretRow?.value === encryptedSecret;
+  if (alreadyConfigured) {
+    database.close();
+    return { changed: false, backupPath: null };
+  }
+  if (options.cursorRunning ?? cursorIsRunning()) {
+    database.close();
+    throw new Error("Quit Cursor before running ocx-cursor init so its API settings can be updated safely");
+  }
+
+  applyOpenAISettings(state, options.baseUrl);
+  await mkdir(backupDirectory, { recursive: true });
+  const timestamp = new Date().toISOString().replaceAll(":", "-");
+  const backupPath = `${backupDirectory}/cursor-state-before-api-init-${timestamp}.vscdb`;
+  await backup(database, backupPath);
+
+  database.exec("BEGIN IMMEDIATE");
+  try {
+    database.prepare("UPDATE ItemTable SET value = ? WHERE key = ?").run(JSON.stringify(state), applicationStorageKey);
+    database.prepare(`
+      INSERT INTO ItemTable (key, value) VALUES (?, ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `).run(openAISecretKey, encryptedSecret);
+    database.exec("COMMIT");
+  } catch (error) {
+    database.exec("ROLLBACK");
+    throw error;
+  } finally {
+    database.close();
+  }
+  return { changed: true, backupPath };
+}

package/src/cursor-state.mjs

@@ -0,0 +1,182 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { backup, DatabaseSync } from "node:sqlite";
+import { effortLabels } from "./catalog.mjs";
+import { cursorDatabaseFile, installRoot, managedPrefix, pendingFile } from "./paths.mjs";
+
+const storageKey = "src.vs.platform.reactivestorage.browser.reactiveStorageServiceImpl.persistentStorage.applicationUser";
+
+export function cursorIsRunning() {
+  try {
+    execFileSync("pgrep", ["-f", "/Applications/Cursor.app/Contents/"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function defaultEffort(model) {
+  const modelId = model.sourceId.split("/").at(-1);
+  if (/^(?:gpt|gemini)-/.test(modelId) && model.reasoningEfforts.includes("medium")) return "medium";
+  if (model.reasoningEfforts.includes("high")) return "high";
+  if (model.reasoningEfforts.includes("medium")) return "medium";
+  return model.reasoningEfforts[0];
+}
+
+function parameterIdFor(model) {
+  return model.provider === "anthropic" ? "effort" : "reasoning";
+}
+
+function effortDefinition(model) {
+  const parameterId = parameterIdFor(model);
+  return {
+    id: parameterId,
+    name: "Effort",
+    markdownTooltip: "Effort the model uses to generate its response.",
+    parameterType: {
+      enumParameter: {
+        values: model.reasoningEfforts.map((value) => ({ value, displayName: effortLabels[value], modelPickerBadges: [] })),
+      },
+    },
+    isCycleableByHotkey: true,
+  };
+}
+
+function effortVariants(model) {
+  const parameterId = parameterIdFor(model);
+  const selectedDefault = defaultEffort(model);
+  return model.reasoningEfforts.map((effort) => {
+    const displayName = `${model.alias} <span style="color: var(--cursor-text-tertiary);">${effortLabels[effort]}</span>`;
+    const isDefault = effort === selectedDefault;
+    return {
+      parameterValues: [{ id: parameterId, value: effort }],
+      displayName,
+      displayNameOutsidePicker: displayName,
+      isMaxMode: false,
+      ...(isDefault ? { isDefaultMaxConfig: true, isDefaultNonMaxConfig: true } : {}),
+      variantStringRepresentation: `${model.alias}[${parameterId}=${effort}]`,
+      legacySlug: `${model.alias}-${effort}`,
+    };
+  });
+}
+
+export function cursorModel(model) {
+  const hasEffort = model.reasoningEfforts.length > 0;
+  return {
+    name: model.alias,
+    defaultOn: false,
+    supportsAgent: true,
+    degradationStatus: 0,
+    supportsThinking: hasEffort,
+    supportsImages: model.inputModalities.includes("image"),
+    supportsMaxMode: true,
+    supportsNonMaxMode: true,
+    serverModelName: model.alias,
+    isRecommendedForBackgroundComposer: false,
+    supportsPlanMode: true,
+    supportsSandboxing: true,
+    isUserAdded: true,
+    inputboxShortModelName: model.alias,
+    idAliases: [],
+    namedModelSectionIndex: 1,
+    cloudAgentEffortModes: [],
+    parameterDefinitions: hasEffort ? [effortDefinition(model)] : [],
+    variants: hasEffort ? effortVariants(model) : [],
+    legacySlugs: model.reasoningEfforts.map((effort) => `${model.alias}-${effort}`),
+    modelPickerBadges: [],
+  };
+}
+
+function syncSelectedModel(state, catalog) {
+  const composer = state.aiSettings?.modelConfig?.composer;
+  if (!composer || !Array.isArray(composer.selectedModels)) return;
+  const byAlias = new Map(catalog.map((model) => [model.alias, model]));
+  for (const selected of composer.selectedModels) {
+    const model = byAlias.get(selected.modelId);
+    if (!model || model.reasoningEfforts.length === 0) continue;
+    const parameterId = parameterIdFor(model);
+    const current = Array.isArray(selected.parameters)
+      ? selected.parameters.find(({ id }) => id === parameterId)?.value
+      : undefined;
+    selected.parameters = [{
+      id: parameterId,
+      value: model.reasoningEfforts.includes(current) ? current : defaultEffort(model),
+    }];
+  }
+}
+
+export function applyCatalogToState(state, catalog) {
+  const aliases = catalog.map(({ alias }) => alias);
+  const keepUnmanaged = (value) => typeof value !== "string" || !value.startsWith(managedPrefix);
+  const existingModels = Array.isArray(state.availableDefaultModels2) ? state.availableDefaultModels2 : [];
+  state.availableDefaultModels2 = [
+    ...existingModels.filter((model) => !(model?.isUserAdded && typeof model.name === "string" && model.name.startsWith(managedPrefix))),
+    ...catalog.map(cursorModel),
+  ];
+  state.aiSettings ||= {};
+  state.aiSettings.userAddedModels = [
+    ...(Array.isArray(state.aiSettings.userAddedModels) ? state.aiSettings.userAddedModels.filter(keepUnmanaged) : []),
+    ...aliases,
+  ];
+  state.aiSettings.modelOverrideEnabled = [
+    ...(Array.isArray(state.aiSettings.modelOverrideEnabled) ? state.aiSettings.modelOverrideEnabled.filter(keepUnmanaged) : []),
+    ...aliases,
+  ];
+  syncSelectedModel(state, catalog);
+  return state;
+}
+
+export async function syncCursorDatabase(catalog, options = {}) {
+  if (cursorIsRunning()) throw new Error("Quit Cursor before syncing OpenCodex models");
+  const databasePath = options.databasePath || cursorDatabaseFile;
+  const backupDirectory = options.backupDirectory || installRoot;
+  await mkdir(backupDirectory, { recursive: true });
+
+  const database = new DatabaseSync(databasePath);
+  const row = database.prepare("SELECT value FROM ItemTable WHERE key = ?").get(storageKey);
+  if (!row?.value) {
+    database.close();
+    throw new Error("Cursor application user storage was not found");
+  }
+  const state = applyCatalogToState(JSON.parse(row.value), catalog);
+  let backupPath = null;
+  if (options.createBackup !== false) {
+    const timestamp = new Date().toISOString().replaceAll(":", "-");
+    backupPath = `${backupDirectory}/cursor-state-before-model-sync-${timestamp}.vscdb`;
+    await backup(database, backupPath);
+  }
+
+  database.exec("BEGIN IMMEDIATE");
+  try {
+    database.prepare("UPDATE ItemTable SET value = ? WHERE key = ?").run(JSON.stringify(state), storageKey);
+    database.exec("COMMIT");
+  } catch (error) {
+    database.exec("ROLLBACK");
+    throw error;
+  } finally {
+    database.close();
+  }
+  return {
+    modelCount: catalog.length,
+    effortCount: catalog.filter(({ reasoningEfforts }) => reasoningEfforts.length > 0).length,
+    backupPath,
+  };
+}
+
+export async function writePendingCatalog(catalog, file = pendingFile) {
+  await mkdir(installRoot, { recursive: true });
+  await writeFile(file, `${JSON.stringify(catalog, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function readPendingCatalog(file = pendingFile) {
+  try {
+    const catalog = JSON.parse(await readFile(file, "utf8"));
+    return Array.isArray(catalog) ? catalog : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function clearPendingCatalog(file = pendingFile) {
+  await rm(file, { force: true });
+}

package/src/gateway.mjs

@@ -0,0 +1,195 @@
+import http from "node:http";
+import { readFile } from "node:fs/promises";
+import { timingSafeEqual } from "node:crypto";
+import { activeModels, allowedEfforts, opencodexEndpoint } from "./catalog.mjs";
+import { gatewayHost, gatewayPort, managedPrefix, opencodexServiceTokenFile } from "./paths.mjs";
+
+const maxBodyBytes = 24 * 1024 * 1024;
+const allowedRoutes = new Set([
+  "GET /v1/models",
+  "POST /v1/responses",
+  "POST /v1/responses/compact",
+  "POST /v1/chat/completions",
+  "POST /v1/messages",
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function suppliedEffort(payload, variantText) {
+  const variantEffort = variantText
+    ?.split(",")
+    .map((value) => value.split("=", 2))
+    .find(([key]) => key === "effort" || key === "reasoning")?.[1];
+  return variantEffort
+    || payload.reasoning_effort
+    || payload.reasoning?.effort
+    || payload.output_config?.effort
+    || payload.reasoningEffort;
+}
+
+export function rewriteModelAliasBody(body, catalog) {
+  if (!body?.length) return body;
+  let payload;
+  try {
+    payload = JSON.parse(body.toString("utf8"));
+  } catch {
+    return body;
+  }
+  if (!isRecord(payload) || typeof payload.model !== "string" || !payload.model.startsWith(managedPrefix)) return body;
+
+  const variant = /^(opencodex\/.+?)\[([^\]]+)\]$/.exec(payload.model);
+  let alias = variant?.[1] || payload.model;
+  let effort = suppliedEffort(payload, variant?.[2]);
+  if (!allowedEfforts.includes(effort)) {
+    const legacy = catalog.find((model) => model.reasoningEfforts?.some((value) => payload.model === `${model.alias}-${value}`));
+    if (legacy) {
+      effort = legacy.reasoningEfforts.find((value) => payload.model === `${legacy.alias}-${value}`);
+      alias = legacy.alias;
+    }
+  }
+
+  const catalogModel = catalog.find((model) => model.alias === alias);
+  const fallbackSourceId = alias.slice(managedPrefix.length);
+  payload.model = catalogModel?.sourceId
+    || (fallbackSourceId.startsWith("claude-") ? `anthropic/${fallbackSourceId}` : fallbackSourceId);
+  if (allowedEfforts.includes(effort)) payload.reasoning_effort = effort;
+  delete payload.reasoningEffort;
+  return Buffer.from(JSON.stringify(payload));
+}
+
+export function enrichModelList(active, catalog) {
+  const existing = new Set(active.map((model) => model?.id));
+  const aliases = catalog
+    .filter(({ alias }) => !existing.has(alias))
+    .map((model) => ({
+      id: model.alias,
+      object: "model",
+      created: 0,
+      owned_by: "opencodex",
+      api_types: [model.provider === "anthropic" ? "anthropic_messages" : "chat_completions"],
+      capabilities: {
+        ...(model.contextWindow ? { context_length: model.contextWindow } : {}),
+        ...(model.maxOutputTokens ? { max_output_tokens: model.maxOutputTokens } : {}),
+        output_modalities: ["text"],
+        input_modalities: model.inputModalities,
+        supports_tool_use: true,
+        supports_streaming: true,
+        supports_reasoning: model.reasoningEfforts.length > 0,
+        supports_vision: model.inputModalities.includes("image"),
+        reasoning_effort: model.reasoningEfforts,
+      },
+    }));
+  return { object: "list", data: [...active, ...aliases] };
+}
+
+async function serviceToken() {
+  try {
+    return (await readFile(opencodexServiceTokenFile, "utf8")).trim();
+  } catch {
+    return "";
+  }
+}
+
+function authorized(req, expected) {
+  const supplied = String(req.headers.authorization || "").replace(/^Bearer\s+/i, "").trim();
+  const actual = Buffer.from(supplied);
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+
+function json(res, status, body) {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  res.end(JSON.stringify(body));
+}
+
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > maxBodyBytes) throw Object.assign(new Error("request too large"), { status: 413 });
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+function upstreamHeaders(req, body, token, upstream) {
+  const headers = { ...req.headers };
+  delete headers.authorization;
+  delete headers["x-api-key"];
+  delete headers["x-opencodex-api-key"];
+  delete headers.cookie;
+  delete headers.origin;
+  delete headers["cf-access-jwt-assertion"];
+  if (token) headers.authorization = `Bearer ${token}`;
+  headers.host = `${upstream.host}:${upstream.port}`;
+  if (body) headers["content-length"] = String(body.length);
+  else delete headers["content-length"];
+  headers["cache-control"] = "no-store";
+  return headers;
+}
+
+export function startGateway(options) {
+  const host = options.host || gatewayHost;
+  const port = options.port || gatewayPort;
+  const expected = Buffer.from(options.secret);
+  let activeRequests = 0;
+
+  const server = http.createServer(async (req, res) => {
+    const started = Date.now();
+    const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+    const route = `${req.method} ${url.pathname}`;
+    const catalog = options.getCatalog();
+
+    if (route === "GET /healthz") {
+      return json(res, 200, { service: "opencodex-cursor-bridge", status: "ok", models: catalog.length, pid: process.pid });
+    }
+    if (!authorized(req, expected)) return json(res, 401, { error: { message: "invalid bridge API key", type: "authentication_error" } });
+    if (!allowedRoutes.has(route)) return json(res, 404, { error: { message: "route not exposed", type: "not_found" } });
+    if (activeRequests >= 8) return json(res, 429, { error: { message: "bridge concurrency limit reached", type: "rate_limit_error" } });
+
+    activeRequests += 1;
+    res.once("close", () => { activeRequests = Math.max(0, activeRequests - 1); });
+    try {
+      if (route === "GET /v1/models") {
+        return json(res, 200, enrichModelList(await activeModels(), catalog));
+      }
+
+      const upstream = opencodexEndpoint();
+      const body = rewriteModelAliasBody(await readBody(req), catalog);
+      const token = await serviceToken();
+      const upstreamReq = http.request({
+        hostname: upstream.host,
+        port: upstream.port,
+        method: req.method,
+        path: `${url.pathname}${url.search}`,
+        headers: upstreamHeaders(req, body, token, upstream),
+      }, (upstreamRes) => {
+        const headers = { ...upstreamRes.headers, "cache-control": "no-store" };
+        delete headers["set-cookie"];
+        res.writeHead(upstreamRes.statusCode || 502, headers);
+        upstreamRes.pipe(res);
+        upstreamRes.on("end", () => {
+          process.stdout.write(`${route} ${upstreamRes.statusCode || 502} ${Date.now() - started}ms\n`);
+        });
+      });
+      upstreamReq.on("error", (error) => {
+        if (!res.headersSent) json(res, 502, { error: { message: "OpenCodex upstream unavailable", type: "upstream_error" } });
+        else res.destroy(error);
+      });
+      upstreamReq.end(body);
+    } catch (error) {
+      if (!res.headersSent) json(res, error.status || 500, { error: { message: error.message || "bridge error", type: "bridge_error" } });
+      else res.destroy(error);
+    }
+  });
+
+  server.listen(port, host, () => {
+    process.stdout.write(`OpenCodex Cursor Bridge listening on http://${host}:${port}\n`);
+  });
+  return server;
+}

package/src/install.mjs

@@ -0,0 +1,203 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { access, chmod, copyFile, cp, lstat, mkdir, readFile, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  cliLinkFile,
+  installRoot,
+  installedPackageRoot,
+  launchAgentFile,
+  legacyLaunchAgentFile,
+  legacyServiceLabel,
+  secretFile,
+  serviceLabel,
+  stderrFile,
+  stdoutFile,
+} from "./paths.mjs";
+
+const sourcePackageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const launchDomain = `gui/${process.getuid()}`;
+
+function xml(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function commandOutput(command, args) {
+  try {
+    return execFileSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function bootout(label) {
+  try {
+    execFileSync("launchctl", ["bootout", `${launchDomain}/${label}`], { stdio: "ignore" });
+  } catch {}
+}
+
+async function bootstrap(plist) {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      execFileSync("launchctl", ["bootstrap", launchDomain, plist], { stdio: "ignore" });
+      return;
+    } catch (error) {
+      if (attempt === 4) throw error;
+      await new Promise((resolveDelay) => setTimeout(resolveDelay, 200));
+    }
+  }
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runningLegacyPlist() {
+  if (await exists(legacyLaunchAgentFile)) return legacyLaunchAgentFile;
+  const output = commandOutput("launchctl", ["print", `${launchDomain}/${legacyServiceLabel}`]);
+  return output.match(/^\s*path = (.+)$/m)?.[1]?.trim() || legacyLaunchAgentFile;
+}
+
+async function migrateSecret(legacyPlist) {
+  if (await exists(secretFile)) return "preserved";
+  if (legacyPlist && await exists(legacyPlist)) {
+    const stdoutPath = commandOutput("plutil", ["-extract", "StandardOutPath", "raw", "-o", "-", legacyPlist]);
+    if (stdoutPath) {
+      const candidate = join(dirname(stdoutPath), "ocx-cursor-gateway.secret");
+      if (await exists(candidate)) {
+        await copyFile(candidate, secretFile);
+        await chmod(secretFile, 0o600);
+        return "migrated";
+      }
+    }
+  }
+  const secret = `ocx_cursor_${randomBytes(32).toString("hex")}`;
+  await writeFile(secretFile, `${secret}\n`, { mode: 0o600, flag: "wx" });
+  return "created";
+}
+
+export async function prepareInstallSecret() {
+  await mkdir(installRoot, { recursive: true });
+  const legacyPlist = await runningLegacyPlist();
+  const secretStatus = await migrateSecret(legacyPlist);
+  return {
+    legacyPlist,
+    secretStatus,
+    secret: (await readFile(secretFile, "utf8")).trim(),
+  };
+}
+
+async function copyPackage() {
+  if (resolve(sourcePackageRoot) === resolve(installedPackageRoot)) return;
+  const temporary = `${installedPackageRoot}.tmp-${process.pid}`;
+  await rm(temporary, { recursive: true, force: true });
+  await cp(sourcePackageRoot, temporary, {
+    recursive: true,
+    filter: (source) => !source.includes("/node_modules/") && !source.includes("/.git/"),
+  });
+  await rm(installedPackageRoot, { recursive: true, force: true });
+  await rename(temporary, installedPackageRoot);
+}
+
+async function installCliLink() {
+  const target = join(installedPackageRoot, "bin", "ocx-cursor.mjs");
+  await mkdir(dirname(cliLinkFile), { recursive: true });
+  try {
+    const stat = await lstat(cliLinkFile);
+    if (!stat.isSymbolicLink() || resolve(dirname(cliLinkFile), await readlink(cliLinkFile)) !== resolve(target)) {
+      throw new Error(`${cliLinkFile} already exists and is not managed by this package`);
+    }
+    await rm(cliLinkFile);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  await symlink(target, cliLinkFile);
+}
+
+function launchAgent(nodePath) {
+  const program = join(installedPackageRoot, "bin", "ocx-cursor.mjs");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xml(serviceLabel)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(nodePath)}</string>
+    <string>${xml(program)}</string>
+    <string>service</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xml(stdoutFile)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(stderrFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+export async function installService() {
+  await mkdir(dirname(launchAgentFile), { recursive: true });
+  const { legacyPlist, secretStatus } = await prepareInstallSecret();
+  await copyPackage();
+  await installCliLink();
+
+  const nodePath = (await exists("/opt/homebrew/bin/node")) ? "/opt/homebrew/bin/node" : process.execPath;
+  await writeFile(launchAgentFile, launchAgent(nodePath), { mode: 0o644 });
+  bootout(serviceLabel);
+  bootout(legacyServiceLabel);
+  await bootstrap(launchAgentFile);
+
+  if (legacyPlist.startsWith(dirname(legacyLaunchAgentFile)) && await exists(legacyPlist)) {
+    const disabled = `${legacyPlist}.disabled-by-${serviceLabel}`;
+    await rm(disabled, { force: true });
+    await rename(legacyPlist, disabled);
+  }
+  return { installRoot, launchAgentFile, cliLinkFile, secretStatus };
+}
+
+export async function uninstallService() {
+  bootout(serviceLabel);
+  await rm(launchAgentFile, { force: true });
+  try {
+    if (resolve(dirname(cliLinkFile), await readlink(cliLinkFile)).startsWith(resolve(installRoot))) {
+      await rm(cliLinkFile, { force: true });
+    }
+  } catch {}
+  await rm(installRoot, { recursive: true, force: true });
+}
+
+export async function serviceStatus(fetchImpl = fetch) {
+  const launchctl = commandOutput("launchctl", ["print", `${launchDomain}/${serviceLabel}`]);
+  let health = null;
+  try {
+    const response = await fetchImpl("http://127.0.0.1:10101/healthz", { signal: AbortSignal.timeout(1000) });
+    if (response.ok) health = await response.json();
+  } catch {}
+  return {
+    installed: await exists(launchAgentFile),
+    loaded: launchctl.includes("state = running") || launchctl.includes("state = active"),
+    health,
+    installRoot,
+  };
+}

package/src/paths.mjs

@@ -0,0 +1,22 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const serviceLabel = "com.opencodex.cursor-bridge";
+export const legacyServiceLabel = "com.local.opencodex.cursor-gateway";
+export const installRoot = process.env.OCX_CURSOR_HOME || join(homedir(), ".opencodex", "cursor-bridge");
+export const installedPackageRoot = join(installRoot, "package");
+export const cliLinkFile = join(homedir(), ".local", "bin", "ocx-cursor");
+export const secretFile = join(installRoot, "secret");
+export const catalogFile = join(installRoot, "catalog.json");
+export const pendingFile = join(installRoot, "pending-sync.json");
+export const stdoutFile = join(installRoot, "service.log");
+export const stderrFile = join(installRoot, "service.error.log");
+export const launchAgentFile = join(homedir(), "Library", "LaunchAgents", `${serviceLabel}.plist`);
+export const legacyLaunchAgentFile = join(homedir(), "Library", "LaunchAgents", `${legacyServiceLabel}.plist`);
+export const cursorDatabaseFile = join(homedir(), "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
+export const opencodexConfigFile = join(homedir(), ".opencodex", "config.json");
+export const opencodexServiceTokenFile = join(homedir(), ".opencodex", "service-api-token");
+export const gatewayPort = Number(process.env.OCX_CURSOR_PORT || "10101");
+export const gatewayHost = process.env.OCX_CURSOR_HOST || "127.0.0.1";
+export const cursorOpenAIBaseUrl = process.env.OCX_CURSOR_BASE_URL || "";
+export const managedPrefix = "opencodex/";

package/src/service.mjs

@@ -0,0 +1,93 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { buildActiveCatalog } from "./catalog.mjs";
+import {
+  cursorIsRunning,
+  readPendingCatalog,
+} from "./cursor-state.mjs";
+import { startGateway } from "./gateway.mjs";
+import { installRoot, secretFile } from "./paths.mjs";
+import { applyOrQueueCatalog, loadCatalogSnapshot, saveCatalogSnapshot } from "./sync.mjs";
+
+export async function loadOrCreateSecret() {
+  await mkdir(installRoot, { recursive: true });
+  try {
+    return (await readFile(secretFile, "utf8")).trim();
+  } catch {
+    const secret = `ocx_cursor_${randomBytes(32).toString("hex")}`;
+    await writeFile(secretFile, `${secret}\n`, { mode: 0o600, flag: "wx" });
+    await chmod(secretFile, 0o600);
+    return secret;
+  }
+}
+
+export async function runService(options = {}) {
+  let catalog = await loadCatalogSnapshot();
+  let refreshPromise = null;
+  let cursorSyncPromise = null;
+  let wasCursorRunning = cursorIsRunning();
+  let stopped = false;
+
+  const refresh = async () => {
+    if (refreshPromise) return refreshPromise;
+    refreshPromise = (async () => {
+      try {
+        const next = await buildActiveCatalog(options);
+        if (JSON.stringify(next) === JSON.stringify(catalog)) return;
+        catalog = next;
+        await saveCatalogSnapshot(catalog);
+        const result = await applyOrQueueCatalog(catalog, { createBackup: false });
+        process.stdout.write(`${result.status === "queued" ? "Queued" : "Synced"} ${result.modelCount} Cursor models\n`);
+      } catch (error) {
+        process.stderr.write(`Catalog refresh failed: ${error.message}\n`);
+      } finally {
+        refreshPromise = null;
+      }
+    })();
+    return refreshPromise;
+  };
+
+  const secret = await loadOrCreateSecret();
+  if (catalog.length === 0) {
+    try {
+      catalog = await buildActiveCatalog(options);
+      await saveCatalogSnapshot(catalog);
+    } catch (error) {
+      process.stderr.write(`Initial catalog load failed: ${error.message}\n`);
+    }
+  }
+
+  const server = startGateway({ secret, getCatalog: () => catalog, host: options.host, port: options.port });
+  const refreshTimer = setInterval(refresh, options.refreshIntervalMs || 15_000);
+  const pendingTimer = setInterval(() => {
+    if (cursorSyncPromise) return;
+    if (cursorIsRunning()) {
+      wasCursorRunning = true;
+      return;
+    }
+    cursorSyncPromise = (async () => {
+      const pending = await readPendingCatalog();
+      const next = pending || (wasCursorRunning ? catalog : null);
+      if (!next) return;
+      const result = await applyOrQueueCatalog(next, { createBackup: false });
+      wasCursorRunning = false;
+      process.stdout.write(`Synced ${result.modelCount} Cursor models after shutdown\n`);
+    })().catch((error) => {
+      process.stderr.write(`Cursor shutdown sync failed: ${error.message}\n`);
+    }).finally(() => {
+      cursorSyncPromise = null;
+    });
+  }, options.cursorPollIntervalMs || 2_000);
+
+  await refresh();
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(refreshTimer);
+    clearInterval(pendingTimer);
+    server.close(() => process.exit(0));
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+  return { server, stop, getCatalog: () => catalog, refresh };
+}

package/src/sync.mjs

@@ -0,0 +1,45 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { buildActiveCatalog } from "./catalog.mjs";
+import {
+  clearPendingCatalog,
+  cursorIsRunning,
+  syncCursorDatabase,
+  writePendingCatalog,
+} from "./cursor-state.mjs";
+import { catalogFile, installRoot } from "./paths.mjs";
+
+export async function loadCatalogSnapshot() {
+  try {
+    const value = JSON.parse(await readFile(catalogFile, "utf8"));
+    return Array.isArray(value) ? value : [];
+  } catch {
+    return [];
+  }
+}
+
+export async function saveCatalogSnapshot(catalog) {
+  await mkdir(installRoot, { recursive: true });
+  const temporary = `${catalogFile}.tmp-${process.pid}`;
+  await writeFile(temporary, `${JSON.stringify(catalog, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, catalogFile);
+}
+
+export async function applyOrQueueCatalog(catalog, options = {}) {
+  if (cursorIsRunning()) {
+    await writePendingCatalog(catalog);
+    return {
+      status: "queued",
+      modelCount: catalog.length,
+      effortCount: catalog.filter(({ reasoningEfforts }) => reasoningEfforts.length > 0).length,
+    };
+  }
+  const result = await syncCursorDatabase(catalog, options);
+  await clearPendingCatalog();
+  return { status: "synced", ...result };
+}
+
+export async function syncNow(options = {}) {
+  const catalog = await buildActiveCatalog(options);
+  await saveCatalogSnapshot(catalog);
+  return { catalog, ...(await applyOrQueueCatalog(catalog)) };
+}