codex-copilot-dx 0.4.5 → 0.4.7

package/README.md

@@ -1,6 +1,6 @@
 # codex-copilot-dx
 
-Use [Codex Desktop](https://openai.com/codex) **and** [Claude Code](https://claude.com/claude-code) with your **GitHub Copilot** subscription.
+Use [Codex Desktop](https://openai.com/codex), [Claude Code](https://claude.com/claude-code), and optionally Claude Desktop with your **GitHub Copilot** subscription.
 
 ## How it works
 
@@ -8,6 +8,7 @@ A single in-process adapter (port `2026`) exposes both APIs over your Copilot su
 
 - **Codex** -> OpenAI Responses API (`/v1/responses`, `/v1/responses/compact`); Responses-only models and compaction proxy directly, chat models convert to Chat Completions.
 - **Claude Code** -> Anthropic Messages API (`/v1/messages`, `/v1/messages/count_tokens`), translated to/from Chat Completions.
+- **Claude Desktop** -> optional Anthropic gateway profile using the same local Messages API plus local model discovery for the configured gateway key.
 
 Supports both HTTP SSE streaming and non-streaming.
 
@@ -15,7 +16,7 @@ Supports both HTTP SSE streaming and non-streaming.
 
 - GitHub Copilot subscription (Individual, Business, or Enterprise)
 - Node.js 18+
-- [Codex Desktop](https://openai.com/codex) and/or [Claude Code](https://claude.com/claude-code) installed
+- [Codex Desktop](https://openai.com/codex), [Claude Code](https://claude.com/claude-code), and/or Claude Desktop installed
 
 ## Usage
 
@@ -37,6 +38,22 @@ Claude Code picks up the new `ANTHROPIC_BASE_URL` on its next launch.
 
 Do not set Claude Code by manually exporting `ANTHROPIC_BASE_URL` or `ANTHROPIC_AUTH_TOKEN` in your shell. Let `codex-copilot-dx` write the local config files instead. If you previously exported those variables, remove them from shell startup files and restart the terminal before launching Claude Code.
 
+### Claude Desktop opt-in
+
+Claude Desktop support is opt-in so the default Codex Desktop and Claude Code setup stays unchanged:
+
+```bash
+npx codex-copilot-dx@latest --configure-claude-desktop
+```
+
+Or set:
+
+```bash
+CCDX_CONFIGURE_CLAUDE_DESKTOP=1 npx codex-copilot-dx@latest
+```
+
+This writes a local Claude Desktop 3P gateway profile that points to the adapter root URL, such as `http://127.0.0.1:2026`. The profile uses a generated local bearer key unless `CCDX_CLAUDE_DESKTOP_API_KEY` is set. Restart Claude Desktop after running the command.
+
 ## Configuration
 
 Environment variables:
@@ -53,6 +70,9 @@ Environment variables:
 | `CCDX_IMG_MIN_BYTES` | `100000` | Images smaller than this are left untouched |
 | `CCDX_IMG_CONCURRENCY` | `4` | Concurrent image optimization tasks; values above `12` are capped at `12` |
 | `CCDX_DISABLE_IMG_OPT` | unset | Set to `1` to disable image optimization |
+| `CCDX_CONFIGURE_CLAUDE_DESKTOP` | unset | Set to `1` to write the Claude Desktop 3P gateway profile during startup |
+| `CCDX_CLAUDE_DESKTOP_API_KEY` | generated for opt-in setup | Bearer key written into the Claude Desktop profile and recognized by the adapter for model discovery |
+| `CCDX_CLAUDE_MODEL_ALIASES` | built-in Claude aliases | Comma-separated Desktop-to-upstream aliases, for example `claude-sonnet-4-6=claude-sonnet-4.6` |
 | `CCDX_USAGE_PATH` | `~/.local/share/codex-copilot-dx/usage.jsonl` | Local JSONL token usage log |
 | `CCDX_DISABLE_USAGE` | unset | Set to `1` to disable usage logging |
 

package/bin/cli.mjs

@@ -3,6 +3,7 @@
 import { ensureAuth, openCodex } from "../src/launcher.mjs";
 import { ensureCodexConfig } from "../src/config.mjs";
 import { ensureClaudeConfig } from "../src/claude-config.mjs";
+import { applyClaudeDesktopConfig, formatClaudeDesktopApplyResult, generatedClaudeDesktopApiKey } from "../src/claude-desktop-config.mjs";
 import { startAdapter } from "../src/adapter.mjs";
 import { refreshVSCodeVersion } from "../src/copilot.mjs";
 import { status } from "../src/status.mjs";
@@ -13,6 +14,7 @@ const ADAPTER_PORT = parseInt(process.env.ADAPTER_PORT || "2026");
 const ADAPTER_HOST = process.env.ADAPTER_HOST || "127.0.0.1";
 const LOCAL_VERSION = localPackageVersion();
 const command = process.argv[2];
+const CONFIGURE_CLAUDE_DESKTOP = command === "--configure-claude-desktop" || process.env.CCDX_CONFIGURE_CLAUDE_DESKTOP === "1";
 
 function isLoopbackHost(host) {
   return ["127.0.0.1", "localhost", "::1"].includes(String(host).toLowerCase());
@@ -50,18 +52,33 @@ try {
     console.log(status("warn", `ADAPTER_HOST=${ADAPTER_HOST} exposes the adapter beyond loopback. Use only on trusted networks.`));
   }
 
+  const claudeDesktopApiKey = CONFIGURE_CLAUDE_DESKTOP
+    ? (process.env.CCDX_CLAUDE_DESKTOP_API_KEY || process.env.CCDX_PROXY_API_KEY || generatedClaudeDesktopApiKey())
+    : (process.env.CCDX_CLAUDE_DESKTOP_API_KEY || process.env.CCDX_PROXY_API_KEY || "");
+
   // Start the in-process adapter.
-  await startAdapter(ADAPTER_PORT, ADAPTER_HOST);
+  await startAdapter(ADAPTER_PORT, ADAPTER_HOST, { claudeDesktopApiKey });
 
   // Point Codex and Claude Code at the adapter.
   ensureCodexConfig(ADAPTER_PORT);
   ensureClaudeConfig(ADAPTER_PORT);
+  if (CONFIGURE_CLAUDE_DESKTOP) {
+    const result = applyClaudeDesktopConfig({
+      port: ADAPTER_PORT,
+      host: ADAPTER_HOST,
+      gatewayApiKey: claudeDesktopApiKey,
+    });
+    console.log(status("ok", `Configured Claude Desktop gateway profile at ${result.baseUrl}`));
+    console.log(formatClaudeDesktopApplyResult(result));
+  }
 
   // Launch Codex when available.
   openCodex();
 
   console.log(`
-  ${status("ok", "Ready. Codex and Claude Code are using your GitHub Copilot subscription.")}
+  ${status("ok", CONFIGURE_CLAUDE_DESKTOP
+    ? "Ready. Codex, Claude Code, and Claude Desktop are using your GitHub Copilot subscription."
+    : "Ready. Codex and Claude Code are using your GitHub Copilot subscription.")}
 
   Adapter: http://${ADAPTER_HOST}:${ADAPTER_PORT}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Use Codex Desktop app with your GitHub Copilot subscription",
   "type": "module",
   "bin": {

package/src/adapter.mjs

@@ -5,6 +5,7 @@ import * as zlib from "node:zlib";
 import { chatCompletions, listModels, responses as copilotResponses, responsesCompact as copilotResponsesCompact } from "./copilot.mjs";
 import { webStreamLines } from "./stream.mjs";
 import { anthropicToChat, chatToAnthropic, streamAnthropicFromLines, countTokens } from "./anthropic.mjs";
+import { claudeDesktopModelsResponse, resolveAnthropicModel } from "./models.mjs";
 import { status } from "./status.mjs";
 import { recordAnthropicUsage, recordResponsesUsage } from "./usage.mjs";
 
@@ -125,6 +126,26 @@ function sendJsonError(res, err, fallbackStatus = 400) {
   res.end(JSON.stringify({ error: err?.message || "Request failed" }));
 }
 
+function sendUpstreamError(res, resp, text) {
+  if (!res.headersSent) {
+    res.writeHead(resp.status || 502, { "Content-Type": resp.headers?.get("content-type") || "application/json" });
+  }
+  res.end(text || JSON.stringify({ error: "Upstream request failed" }));
+}
+
+function bearerToken(headers = {}) {
+  const value = headers.authorization || headers.Authorization || "";
+  const match = /^Bearer\s+(.+)$/i.exec(String(value));
+  return match?.[1]?.trim() || "";
+}
+
+export function shouldServeClaudeDesktopModels(req, claudeDesktopApiKey) {
+  if (!claudeDesktopApiKey || claudeDesktopApiKey === "dummy") return false;
+  const token = bearerToken(req.headers);
+  const xApiKey = req.headers?.["x-api-key"] || req.headers?.["X-Api-Key"] || req.headers?.["X-API-Key"] || "";
+  return token === claudeDesktopApiKey || xApiKey === claudeDesktopApiKey;
+}
+
 export function writeOrDrain(res, chunk) {
   if (res.destroyed || res.writableEnded) return Promise.resolve(false);
   if (res.write(chunk)) return Promise.resolve(true);
@@ -180,6 +201,81 @@ function responsesOutputItems(output) {
   return cloneJson(output.filter((item) => item?.type === "message" || item?.type === "function_call"));
 }
 
+function stripEncryptedReasoningValue(value, state) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripEncryptedReasoningValue(item, state));
+  }
+
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (key === "encrypted_content") {
+        state.changed = true;
+        continue;
+      }
+      out[key] = stripEncryptedReasoningValue(child, state);
+    }
+    return out;
+  }
+
+  return value;
+}
+
+function isEncryptedReasoningInputItem(item) {
+  return item && typeof item === "object"
+    && (item.type === "reasoning" || Object.prototype.hasOwnProperty.call(item, "encrypted_content"));
+}
+
+export function sanitizeEncryptedReasoningRequest(reqContext) {
+  const state = { changed: false };
+  let body = cloneJson(reqContext.body);
+  if (Array.isArray(body.input)) {
+    const input = [];
+    for (const item of body.input) {
+      if (isEncryptedReasoningInputItem(item)) {
+        state.changed = true;
+        continue;
+      }
+      input.push(stripEncryptedReasoningValue(item, state));
+    }
+    body.input = input;
+  } else {
+    body = stripEncryptedReasoningValue(body, state);
+  }
+  if (!state.changed) return null;
+  return {
+    ...reqContext,
+    body,
+    inputItems: Array.isArray(body.input) ? body.input : reqContext.inputItems,
+  };
+}
+
+export function isEncryptedContentVerificationError(statusCode, text) {
+  if (statusCode < 400 || !text) return false;
+  const lower = String(text).toLowerCase();
+  return lower.includes("encrypted content")
+    && lower.includes("could not be verified")
+    && (lower.includes("could not be decrypted") || lower.includes("could not be parsed"));
+}
+
+export async function openCopilotResponse(reqContext, upstream = copilotResponses, options = {}) {
+  let resp = await upstream(reqContext.body, { signal: options.signal });
+  if (resp.ok) return { resp, reqContext };
+
+  const errorText = await resp.text();
+  if (!isEncryptedContentVerificationError(resp.status, errorText)) {
+    return { resp, reqContext, errorText };
+  }
+
+  const retryContext = sanitizeEncryptedReasoningRequest(reqContext);
+  if (!retryContext) return { resp, reqContext, errorText };
+
+  console.warn(status("warn", "encrypted reasoning rejected by upstream; retrying without encrypted reasoning"));
+  resp = await upstream(retryContext.body, { signal: options.signal });
+  if (resp.ok) return { resp, reqContext: retryContext };
+  return { resp, reqContext: retryContext, errorText: await resp.text() };
+}
+
 export function clearResponseHistoryForTests() {
   responseHistories.clear();
 }
@@ -256,7 +352,13 @@ function readSseEvents(buffer, onData) {
 }
 
 async function proxyCopilotResponses(reqContext, req, res, upstream = copilotResponses, options = {}) {
-  const resp = await upstream(reqContext.body, { signal: options.signal });
+  const opened = await openCopilotResponse(reqContext, upstream, options);
+  const { resp, errorText } = opened;
+  reqContext = opened.reqContext;
+  if (errorText !== undefined) {
+    sendUpstreamError(res, resp, errorText);
+    return;
+  }
 
   if (reqContext.body.stream) {
     res.writeHead(resp.status, {
@@ -416,7 +518,12 @@ async function forwardToChat(chatReq, emitEvent, onDone, onError, options = {})
 
 // Public server entry point.
 
-export function startAdapter(port = 2026, host = "127.0.0.1") {
+export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
+  const claudeDesktopApiKey = options.claudeDesktopApiKey
+    || process.env.CCDX_CLAUDE_DESKTOP_API_KEY
+    || process.env.CCDX_PROXY_API_KEY
+    || "";
+
   const server = http.createServer((req, res) => {
     const pathname = requestPath(req.url);
 
@@ -492,6 +599,11 @@ export function startAdapter(port = 2026, host = "127.0.0.1") {
     }
 
     if (req.method === "GET" && pathname === "/v1/models") {
+      if (shouldServeClaudeDesktopModels(req, claudeDesktopApiKey)) {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(claudeDesktopModelsResponse()));
+        return;
+      }
       const abort = createRequestAbort(req, res);
       abort.setTimeout(UPSTREAM_TIMEOUT_MS);
       listModels({ signal: abort.signal })
@@ -523,9 +635,11 @@ export function startAdapter(port = 2026, host = "127.0.0.1") {
         try {
           const parsed = await readJsonBody(req);
           if (!parsed.stream) abort.setTimeout(UPSTREAM_TIMEOUT_MS);
-          const model = parsed.model || "unknown";
-          console.log(status("info", `messages model=${model} stream=${!!parsed.stream}`));
-          const chatReq = anthropicToChat(parsed);
+          const { requestedModel, upstreamModel } = resolveAnthropicModel(parsed.model || "unknown");
+          const modelNote = upstreamModel === requestedModel ? requestedModel : `${requestedModel} -> ${upstreamModel}`;
+          console.log(status("info", `messages model=${modelNote} stream=${!!parsed.stream}`));
+          const chatReq = anthropicToChat(parsed, { upstreamModel });
+          const forceRequestedModel = upstreamModel !== requestedModel;
           if (parsed.stream) {
             const upstream = await chatCompletions({ ...chatReq, stream: true }, { signal: abort.signal });
             if (!upstream.ok) {
@@ -543,14 +657,15 @@ export function startAdapter(port = 2026, host = "127.0.0.1") {
                 if (event === "message_delta") usage = data.usage;
                 await writeOrDrain(res, `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
               },
-              model,
+              requestedModel,
+              { forceModel: forceRequestedModel },
             );
-            recordAnthropicUsage({ surface: "messages", mode: "stream", model, responseId: messageId, usage });
+            recordAnthropicUsage({ surface: "messages", mode: "stream", model: requestedModel, responseId: messageId, usage });
             if (!res.writableEnded) res.end();
           } else {
             const upstream = await chatCompletions({ ...chatReq, stream: false }, { signal: abort.signal });
             const data = await upstream.text();
-            const anthropicMsg = chatToAnthropic(JSON.parse(data), model);
+            const anthropicMsg = chatToAnthropic(JSON.parse(data), requestedModel, { forceModel: forceRequestedModel });
             recordAnthropicUsage({ surface: "messages", mode: "json", model: anthropicMsg.model, responseId: anthropicMsg.id, usage: anthropicMsg.usage });
             res.writeHead(200, { "Content-Type": "application/json" });
             res.end(JSON.stringify(anthropicMsg));

package/src/anthropic.mjs

@@ -89,7 +89,7 @@ function mapToolChoice(tc) {
   }
 }
 
-export function anthropicToChat(body) {
+export function anthropicToChat(body, options = {}) {
   const messages = [];
   const sys = systemToText(body.system);
   if (sys) messages.push({ role: "system", content: sys });
@@ -97,7 +97,7 @@ export function anthropicToChat(body) {
     for (const converted of convertMessage(m)) messages.push(converted);
   }
 
-  const chatReq = { model: body.model, messages };
+  const chatReq = { model: options.upstreamModel || body.model, messages };
   if (body.max_tokens !== undefined) chatReq.max_tokens = body.max_tokens;
   if (body.temperature !== undefined) chatReq.temperature = body.temperature;
   if (body.top_p !== undefined) chatReq.top_p = body.top_p;
@@ -117,7 +117,7 @@ export function anthropicToChat(body) {
 
 function uid() { return randomUUID().replace(/-/g, ""); }
 
-export function chatToAnthropic(openaiResp, model) {
+export function chatToAnthropic(openaiResp, model, options = {}) {
   const choice = openaiResp.choices?.[0];
   const msg = choice?.message || {};
   const content = [];
@@ -143,7 +143,7 @@ export function chatToAnthropic(openaiResp, model) {
     id: `msg_${uid()}`,
     type: "message",
     role: "assistant",
-    model: openaiResp.model || model,
+    model: options.forceModel ? model : (openaiResp.model || model),
     content,
     stop_reason: mapStopReason(choice?.finish_reason),
     stop_sequence: null,
@@ -152,7 +152,7 @@ export function chatToAnthropic(openaiResp, model) {
 }
 
 // Consume OpenAI chat SSE lines and emit Anthropic SSE events.
-export async function streamAnthropicFromLines(lineIterator, emit, model) {
+export async function streamAnthropicFromLines(lineIterator, emit, model, options = {}) {
   const msgId = `msg_${uid()}`;
   let started = false;
   let blockIndex = -1;
@@ -192,7 +192,7 @@ export async function streamAnthropicFromLines(lineIterator, emit, model) {
     if (data === "[DONE]") break;
     let parsed;
     try { parsed = JSON.parse(data); } catch { continue; }
-    if (parsed.model) actualModel = parsed.model;
+    if (!options.forceModel && parsed.model) actualModel = parsed.model;
     if (parsed.usage?.completion_tokens != null) outputTokens = parsed.usage.completion_tokens;
     const choice = parsed.choices?.[0];
     if (!choice) continue;

package/src/claude-desktop-config.mjs

@@ -0,0 +1,232 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { claudeDesktopModelIds } from "./models.mjs";
+import { status } from "./status.mjs";
+
+const CONFIG_FILE = "claude_desktop_config.json";
+const CONFIG_LIBRARY_DIR = "configLibrary";
+export const DEFAULT_CLAUDE_DESKTOP_PROFILE_ID = "00000000-0000-4000-8000-000000202600";
+export const DEFAULT_CLAUDE_DESKTOP_PROFILE_NAME = "Codex Copilot DX";
+
+function jsonClone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function valueOrDefault(value, fallback) {
+  const trimmed = String(value || "").trim();
+  return trimmed || fallback;
+}
+
+function isLoopbackHost(host) {
+  const normalized = String(host || "").toLowerCase().replace(/^\[(.*)\]$/, "$1");
+  return ["127.0.0.1", "localhost", "::1"].includes(normalized);
+}
+
+function localGatewayBaseUrl(host, port) {
+  const safeHost = String(host || "127.0.0.1");
+  const urlHost = safeHost.includes(":") && !safeHost.startsWith("[") ? `[${safeHost}]` : safeHost;
+  return `http://${urlHost}:${port}`;
+}
+
+export function claudeDesktopPaths(home = os.homedir(), platform = process.platform, env = process.env) {
+  if (platform === "win32") {
+    const localAppData = valueOrDefault(env.LOCALAPPDATA, path.join(home, "AppData", "Local"));
+    return pathsFromDirs(path.join(localAppData, "Claude"), path.join(localAppData, "Claude-3p"));
+  }
+  const appSupport = path.join(home, "Library", "Application Support");
+  return pathsFromDirs(path.join(appSupport, "Claude"), path.join(appSupport, "Claude-3p"));
+}
+
+function pathsFromDirs(normalDir, threepDir) {
+  const configLibraryPath = path.join(threepDir, CONFIG_LIBRARY_DIR);
+  return {
+    normalConfigPath: path.join(normalDir, CONFIG_FILE),
+    threepConfigPath: path.join(threepDir, CONFIG_FILE),
+    configLibraryPath,
+    metaPath: path.join(configLibraryPath, "_meta.json"),
+  };
+}
+
+export function validateClaudeDesktopBaseUrl(raw) {
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`Claude Desktop gateway base URL is not valid: ${raw}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Claude Desktop gateway base URL must use http or https");
+  }
+  if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
+    throw new Error("Claude Desktop allows http only for loopback; use https for LAN or remote gateways");
+  }
+  if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw new Error("Claude Desktop gateway base URL must be the root URL without /v1, query, or hash");
+  }
+}
+
+function isGatewayProfileField(key) {
+  return [
+    "inferenceProvider",
+    "inferenceGatewayBaseUrl",
+    "inferenceGatewayApiKey",
+    "inferenceGatewayAuthScheme",
+    "inferenceModels",
+  ].includes(key);
+}
+
+export function computeClaudeDesktopProfile(sourceProfile = {}, {
+  baseUrl,
+  gatewayApiKey,
+  modelIds = claudeDesktopModelIds(),
+} = {}) {
+  validateClaudeDesktopBaseUrl(baseUrl);
+  if (!String(gatewayApiKey || "").trim()) {
+    throw new Error("Claude Desktop gateway API key is required");
+  }
+
+  const profile = {};
+  for (const [key, value] of Object.entries(sourceProfile || {})) {
+    if (key === "enterpriseConfig" || isGatewayProfileField(key)) continue;
+    profile[key] = jsonClone(value);
+  }
+
+  profile.inferenceProvider = "gateway";
+  profile.inferenceGatewayBaseUrl = baseUrl;
+  profile.inferenceGatewayApiKey = gatewayApiKey;
+  profile.inferenceGatewayAuthScheme = "bearer";
+  profile.inferenceModels = JSON.stringify(modelIds);
+  if (!profile.disableDeploymentModeChooser) profile.disableDeploymentModeChooser = "true";
+  return profile;
+}
+
+export function computeClaudeDesktopMeta(meta = {}, profileId = DEFAULT_CLAUDE_DESKTOP_PROFILE_ID, profileName = DEFAULT_CLAUDE_DESKTOP_PROFILE_NAME) {
+  const out = { ...(meta || {}) };
+  const entries = Array.isArray(out.entries) ? out.entries : [];
+  out.entries = [
+    ...entries.filter((entry) => entry?.id !== profileId),
+    { id: profileId, name: profileName },
+  ];
+  out.appliedId = profileId;
+  return out;
+}
+
+export function computeDeploymentConfig(config = {}) {
+  return { ...(config || {}), deploymentMode: "3p" };
+}
+
+function readJsonFile(filePath, fallback = {}) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (e) {
+    if (e?.code === "ENOENT") return fallback;
+    throw e;
+  }
+}
+
+function writeJsonFile(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+}
+
+function snapshotFiles(files) {
+  return files.map((filePath) => {
+    try {
+      return { filePath, exists: true, data: fs.readFileSync(filePath) };
+    } catch (e) {
+      if (e?.code === "ENOENT") return { filePath, exists: false };
+      throw e;
+    }
+  });
+}
+
+function restoreSnapshots(snapshots) {
+  for (const snapshot of snapshots) {
+    if (!snapshot.exists) {
+      fs.rmSync(snapshot.filePath, { force: true });
+      continue;
+    }
+    fs.mkdirSync(path.dirname(snapshot.filePath), { recursive: true });
+    fs.writeFileSync(snapshot.filePath, snapshot.data, { mode: 0o600 });
+  }
+}
+
+function readActiveProfile(paths) {
+  const meta = readJsonFile(paths.metaPath, {});
+  const appliedId = String(meta.appliedId || "").trim();
+  if (!appliedId) return {};
+  return readJsonFile(path.join(paths.configLibraryPath, `${appliedId}.json`), {});
+}
+
+export function applyClaudeDesktopConfig({
+  port = 2026,
+  host = "127.0.0.1",
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+  baseUrl = localGatewayBaseUrl(host, port),
+  gatewayApiKey = env.CCDX_CLAUDE_DESKTOP_API_KEY || env.CCDX_PROXY_API_KEY || "dummy",
+  modelIds = claudeDesktopModelIds(env),
+  profileId = DEFAULT_CLAUDE_DESKTOP_PROFILE_ID,
+  profileName = DEFAULT_CLAUDE_DESKTOP_PROFILE_NAME,
+} = {}) {
+  const paths = claudeDesktopPaths(home, platform, env);
+  const profilePath = path.join(paths.configLibraryPath, `${profileId}.json`);
+  const snapshots = snapshotFiles([
+    paths.normalConfigPath,
+    paths.threepConfigPath,
+    paths.metaPath,
+    profilePath,
+  ]);
+
+  try {
+    const sourceProfile = readActiveProfile(paths);
+    const normalConfig = readJsonFile(paths.normalConfigPath, {});
+    const threepConfig = readJsonFile(paths.threepConfigPath, {});
+    const meta = readJsonFile(paths.metaPath, {});
+
+    writeJsonFile(paths.normalConfigPath, computeDeploymentConfig(normalConfig));
+    writeJsonFile(paths.threepConfigPath, computeDeploymentConfig(threepConfig));
+    writeJsonFile(profilePath, computeClaudeDesktopProfile(sourceProfile, { baseUrl, gatewayApiKey, modelIds }));
+    writeJsonFile(paths.metaPath, computeClaudeDesktopMeta(meta, profileId, profileName));
+  } catch (e) {
+    restoreSnapshots(snapshots);
+    throw e;
+  }
+
+  return {
+    paths,
+    profileId,
+    profilePath,
+    baseUrl,
+    modelIds,
+  };
+}
+
+export function formatClaudeDesktopApplyResult(result) {
+  return [
+    "Claude Desktop local gateway profile",
+    `profile id: ${result.profileId}`,
+    `profile path: ${result.profilePath}`,
+    `base url: ${result.baseUrl}`,
+    `models: ${result.modelIds.join(", ")}`,
+    "gateway api key: <redacted>",
+  ].join("\n");
+}
+
+export function ensureClaudeDesktopConfig(port = 2026, host = "127.0.0.1") {
+  const result = applyClaudeDesktopConfig({
+    port,
+    host,
+    gatewayApiKey: process.env.CCDX_CLAUDE_DESKTOP_API_KEY || process.env.CCDX_PROXY_API_KEY || generatedClaudeDesktopApiKey(),
+  });
+  console.log(status("ok", `Configured Claude Desktop gateway profile at ${result.baseUrl}`));
+  console.log(formatClaudeDesktopApplyResult(result));
+  return result;
+}
+
+export function generatedClaudeDesktopApiKey() {
+  return `ccdx_${randomUUID().replaceAll("-", "")}`;
+}

package/src/models.mjs

@@ -0,0 +1,110 @@
+const DEFAULT_CLAUDE_DESKTOP_MODEL_DEFS = [
+  {
+    id: "claude-sonnet-4.6",
+    upstream: "claude-sonnet-4.6",
+    displayName: "Claude Sonnet 4.6",
+    createdAt: "2026-02-17T00:00:00Z",
+    maxInputTokens: 200000,
+    maxOutputTokens: 8192,
+  },
+  {
+    id: "claude-opus-4.8",
+    upstream: "claude-opus-4.8",
+    displayName: "Claude Opus 4.8",
+    createdAt: "2026-05-28T00:00:00Z",
+    maxInputTokens: 200000,
+    maxOutputTokens: 8192,
+  },
+  {
+    id: "claude-haiku-4.5",
+    upstream: "claude-haiku-4.5",
+    displayName: "Claude Haiku 4.5",
+    createdAt: "2025-10-01T00:00:00Z",
+    maxInputTokens: 200000,
+    maxOutputTokens: 8192,
+  },
+  {
+    id: "claude-sonnet-4-6",
+    upstream: "claude-sonnet-4.6",
+    displayName: "Claude Sonnet 4.6",
+    createdAt: "2026-02-17T00:00:00Z",
+    maxInputTokens: 200000,
+    maxOutputTokens: 8192,
+  },
+  {
+    id: "claude-opus-4-8",
+    upstream: "claude-opus-4.8",
+    displayName: "Claude Opus 4.8",
+    createdAt: "2026-05-28T00:00:00Z",
+    maxInputTokens: 200000,
+    maxOutputTokens: 8192,
+  },
+  {
+    id: "claude-haiku-4-5",
+    upstream: "claude-haiku-4.5",
+    displayName: "Claude Haiku 4.5",
+    createdAt: "2025-10-01T00:00:00Z",
+    maxInputTokens: 200000,
+    maxOutputTokens: 8192,
+  },
+];
+
+function cleanList(value) {
+  return String(value || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function parseModelAliasEnv(value) {
+  const aliases = [];
+  for (const entry of cleanList(value)) {
+    const [id, upstream] = entry.split("=", 2).map((part) => part?.trim());
+    if (!id || !upstream) continue;
+    aliases.push({
+      id,
+      upstream,
+      displayName: id,
+      createdAt: "2025-01-01T00:00:00Z",
+      maxInputTokens: 200000,
+      maxOutputTokens: 8192,
+    });
+  }
+  return aliases;
+}
+
+export function claudeDesktopModelDefs(env = process.env) {
+  const custom = parseModelAliasEnv(env.CCDX_CLAUDE_MODEL_ALIASES);
+  return custom.length ? custom : DEFAULT_CLAUDE_DESKTOP_MODEL_DEFS.map((model) => ({ ...model }));
+}
+
+export function claudeDesktopModelIds(env = process.env) {
+  return claudeDesktopModelDefs(env).map((model) => model.id);
+}
+
+export function resolveAnthropicModel(model, env = process.env) {
+  const requestedModel = String(model || "");
+  const match = claudeDesktopModelDefs(env).find((entry) => entry.id === requestedModel);
+  return {
+    requestedModel,
+    upstreamModel: match?.upstream || requestedModel,
+  };
+}
+
+export function anthropicModelInfo(model) {
+  return {
+    id: model.id,
+    type: "model",
+    display_name: model.displayName || model.id,
+    created_at: model.createdAt || "2025-01-01T00:00:00Z",
+    max_input_tokens: model.maxInputTokens || 200000,
+    max_tokens: model.maxOutputTokens || 8192,
+  };
+}
+
+export function claudeDesktopModelsResponse(env = process.env) {
+  return {
+    object: "list",
+    data: claudeDesktopModelDefs(env).map(anthropicModelInfo),
+  };
+}