pennyrouter 0.3.3 → 0.3.5

package/README.md

@@ -40,7 +40,14 @@ directory to the user PATH:
 
 ```bash
 penny claude
+penny claude desktop
+penny claude desktop gateway
+penny claude desktop native
+penny claude desktop status
 penny codex
+penny codex desktop
+penny codex desktop gateway
+penny codex desktop native
 penny opencode
 ```
 
@@ -51,6 +58,33 @@ completely native; their normal configuration files are not redirected. Choose t
 "make PennyRouter the default" option, or pass `--make-default`, to retain the original global
 routing behavior.
 
+`penny codex desktop` launches Codex Desktop with a temporary `CODEX_HOME` overlay that selects
+PennyRouter without changing the user's real Codex configuration. Auth, history, and other
+Codex files remain linked to the normal home, and the overlay is removed when the app exits.
+The command detaches by default and returns the shell prompt immediately; use
+`penny codex desktop gateway --logs` to keep the desktop process and its logs attached to the
+terminal. `penny codex desktop native` provides the symmetric explicit native launch used by the
+PennyRouter Mac app; clicking the Codex icon directly remains native as well.
+Launching Codex normally afterward therefore returns to the user's native provider.
+
+`penny claude desktop` (or the explicit `gateway` subcommand) configures Claude Desktop's
+official third-party Gateway provider and launches the app. `penny claude desktop native`
+deactivates third-party inference for the next launch while preserving the Penny profile, and
+`penny claude desktop status` reports the selected mode and whether the app is running. Claude
+reads its provider once at startup, so Gateway and Native commands refuse to change modes until
+Claude Desktop has been fully quit.
+
+The integration does not intercept HTTPS traffic and does not modify terminal Claude Code's
+`~/.claude/settings.json`. The generated Desktop profile contains no API key: its credential
+helper reads the existing mode-0600 PennyRouter config when Claude requests a token. The profile
+enables gateway model discovery, so the Desktop picker comes from PennyRouter's `/v1/models`
+catalog rather than a launcher-maintained fixed list. Native Claude and third-party Claude keep
+their own application data, so moving between them does not replace either mode's conversations.
+PennyRouter also remembers the Desktop profile that was selected beforehand; use
+`penny claude desktop --restore` for uninstall/recovery to remove the Penny profile and select
+that previous third-party profile again. Launches detach by default; append `--logs` to a Gateway
+or Native command to keep the app attached.
+
 Existing PennyRouter installs preserve their current bare-command behavior during upgrade unless
 the user explicitly changes it. Close running Claude Code or Codex sessions only when adding or
 removing global bare-command routing. A Penny-only install does not require closing native sessions.

package/bin/penny.js

@@ -1,7 +1,18 @@
 #!/usr/bin/env node
-import { runPenny } from "../src/launch.js";
+import {
+  runClaudeDesktopCredentialHelper,
+  runCodexDesktopSupervisor,
+  runPenny,
+} from "../src/launch.js";
 
-runPenny().then((code) => {
+const args = process.argv.slice(2);
+const run = args[0] === "__codex-desktop-supervisor"
+  ? runCodexDesktopSupervisor(args[1])
+  : args[0] === "__claude-desktop-credential-helper"
+    ? runClaudeDesktopCredentialHelper()
+    : runPenny();
+
+run.then((code) => {
   process.exitCode = code;
 }).catch((error) => {
   console.error(error?.message || String(error));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {

package/src/cli.js

@@ -1397,7 +1397,7 @@ async function configureUserFunding(flags, selected, claudeAnthropicAuth,
         + "or --openrouter-api-key (or OPENROUTER_API_KEY). Nothing was installed.",
       );
     }
-    console.log("Claude Code needs a user-funded provider. PennyRouter will never fall back to its own API keys.");
+    console.log("Claude Code needs a user-funded provider.");
     anthropicApiKey = (await promptSecretish(
       "Anthropic API key (leave blank to use OpenRouter): ",
     )).trim();
@@ -1418,7 +1418,6 @@ async function configureUserFunding(flags, selected, claudeAnthropicAuth,
       );
     }
     console.log("Codex is not logged into ChatGPT and needs a user-funded provider.");
-    console.log("PennyRouter will never fall back to its own API keys.");
     openaiApiKey = (await promptSecretish(
       "OpenAI API key (leave blank to use OpenRouter): ",
     )).trim();

package/src/harnesses/opencode.js

@@ -65,6 +65,10 @@ export const opencodeHarness = {
       options: {
         baseURL: `${String(gatewayBaseUrl).replace(/\/+$/, "")}/v1`,
         apiKey,
+        headers: {
+          "x-pennyrouter-title-session": "{env:PENNYROUTER_TITLE_SESSION_ID}",
+          "x-pennyrouter-harness": "opencode",
+        },
       },
       models: Object.fromEntries(
         (models || OPENCODE_MODEL_CHOICES).map((model) => [

package/src/install-manifest.json

@@ -53,7 +53,7 @@
         },
         {
           "id": "anthropic-proxy",
-          "name": "Other proxy (custom base URL)",
+          "name": "Proxy (e.g., Bedrock, Azure, private server)",
           "fields": [
             {
               "config_key": "proxyBaseUrl",
@@ -82,9 +82,16 @@
             { "config_key": "openaiApiKey", "label": "OpenAI API key", "secret": true }
           ]
         },
+        {
+          "id": "openrouter",
+          "name": "OpenRouter API key",
+          "fields": [
+            { "config_key": "openrouterApiKey", "label": "OpenRouter API key", "secret": true }
+          ]
+        },
         {
           "id": "openai-proxy",
-          "name": "Other OpenAI-compatible proxy",
+          "name": "Proxy (e.g., Bedrock, Azure, private server)",
           "fields": [
             {
               "config_key": "openaiProxyBaseUrl",
@@ -94,20 +101,13 @@
             },
             { "config_key": "openaiProxyApiKey", "label": "OpenAI proxy API key", "secret": true }
           ]
-        },
-        {
-          "id": "openrouter",
-          "name": "OpenRouter API key",
-          "fields": [
-            { "config_key": "openrouterApiKey", "label": "OpenRouter API key", "secret": true }
-          ]
         }
       ]
     }
   },
   "advanced": {
-    "title": "Private gateway",
-    "description": "Route through your own PennyRouter gateway instead of the hosted one.",
+    "title": "Private PennyRouter gateway",
+    "description": "Route through a private PennyRouter gateway if supplied by your IT team.",
     "fields": [
       {
         "config_key": "gatewayBaseUrl",

package/src/launch.js

@@ -2,18 +2,28 @@ import { spawn, spawnSync } from "node:child_process";
 import {
   chmod,
   cp,
+  mkdtemp,
   mkdir,
+  readFile,
   rm,
+  readdir,
   stat,
+  symlink,
   unlink,
   writeFile,
 } from "node:fs/promises";
 import { constants as osConstants } from "node:os";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { basename, dirname, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
 
 import { configureClaudeCodeStatusline } from "./statusline.js";
-import { upgradeClaudeCodeModelValue, writeClaudeCodeModelPresentation } from "./harnesses/claude-code.js";
+import {
+  upgradeClaudeCodeModelValue,
+  writeClaudeCodeModelPresentation,
+} from "./harnesses/claude-code.js";
+import { renderCodexConfig } from "./harnesses/codex.js";
 import { atomicWrite, homeDir, readJsonFile, readText } from "./state.js";
 
 const CONFIG_VERSION = 1;
@@ -21,6 +31,10 @@ const PATH_START = "# >>> pennyrouter PATH >>>";
 const PATH_END = "# <<< pennyrouter PATH <<<";
 const CODEX_PROFILE_MARKER = "# PennyRouter per-command profile (managed; no secrets)";
 const CLAUDE_COMMAND_MARKER = "<!-- PennyRouter managed Claude command -->";
+// A stable UUID keeps upgrades idempotent and avoids creating a new visible profile on
+// every launch. It is deliberately not the user's hand-authored profile id.
+const CLAUDE_DESKTOP_PROFILE_ID = "70656e6e-7972-4f75-8465-720000000001";
+const CLAUDE_DESKTOP_PROFILE_NAME = "PennyRouter";
 const TERMINAL_TITLE_REFRESH_MS = 1000;
 const TERMINAL_STATUS_REFRESH_MS = 15000;
 
@@ -59,6 +73,31 @@ export function claudeLaunchSettingsPath() {
   return join(pennyConfigDir(), "claude-settings.json");
 }
 
+export function claudeDesktopConfigLibraryPath() {
+  if (process.platform === "win32") {
+    return join(
+      process.env.LOCALAPPDATA || process.env.APPDATA || homeDir(),
+      "Claude-3p",
+      "configLibrary",
+    );
+  }
+  if (process.platform === "darwin") {
+    return join(homeDir(), "Library", "Application Support", "Claude-3p", "configLibrary");
+  }
+  return join(
+    process.env.XDG_CONFIG_HOME || join(homeDir(), ".config"),
+    "Claude-3p",
+    "configLibrary",
+  );
+}
+
+export function claudeDesktopCredentialHelperPath() {
+  return join(
+    pennyConfigDir(),
+    process.platform === "win32" ? "claude-desktop-credential.cmd" : "claude-desktop-credential",
+  );
+}
+
 export function codexLaunchProfilePath() {
   const codexHome = process.env.CODEX_HOME || join(homeDir(), ".codex");
   return join(codexHome, "pennyrouter.config.toml");
@@ -78,6 +117,11 @@ async function privateWrite(path, text) {
   await chmod(path, 0o600);
 }
 
+async function executableWrite(path, text) {
+  await privateWrite(path, text);
+  if (process.platform !== "win32") await chmod(path, 0o700);
+}
+
 export async function loadPennyConfig() {
   return (await readJsonFile(pennyConfigPath(), null)) || {
     version: CONFIG_VERSION,
@@ -251,9 +295,12 @@ export function renderCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {
   const authLines = subscriptionAuth
     ? [
         "requires_openai_auth = true",
-        'env_http_headers = { "x-pennyrouter-key" = "PENNYROUTER_API_KEY" }',
+        'env_http_headers = { "x-pennyrouter-key" = "PENNYROUTER_API_KEY", "x-pennyrouter-title-session" = "PENNYROUTER_TITLE_SESSION_ID", "x-pennyrouter-harness" = "codex" }',
       ]
-    : ['env_key = "PENNYROUTER_API_KEY"'];
+    : [
+        'env_key = "PENNYROUTER_API_KEY"',
+        'http_headers = { "x-pennyrouter-title-session" = "PENNYROUTER_TITLE_SESSION_ID", "x-pennyrouter-harness" = "codex" }',
+      ];
   return [
     CODEX_PROFILE_MARKER,
     'model_provider = "pennyrouter"',
@@ -274,6 +321,258 @@ export function renderCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {
   ].join("\n");
 }
 
+export function codexDesktopExecutable() {
+  if (process.platform === "darwin") return "/Applications/Codex.app/Contents/MacOS/Codex";
+  if (process.platform === "win32") return "Codex.exe";
+  return "codex";
+}
+
+export function claudeDesktopExecutable() {
+  if (process.platform === "darwin") return "/Applications/Claude.app/Contents/MacOS/Claude";
+  if (process.platform === "win32") return "Claude.exe";
+  return "claude-desktop";
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function renderClaudeDesktopCredentialHelper() {
+  const entry = join(pennyRuntimeDir(), "bin", "penny.js");
+  if (process.platform === "win32") {
+    return `@echo off\r\n"${process.execPath.replaceAll('"', '""')}" "${entry.replaceAll('"', '""')}" __claude-desktop-credential-helper\r\n`;
+  }
+  return `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(entry)} __claude-desktop-credential-helper\n`;
+}
+
+/**
+ * Apply a dedicated local Claude Desktop 3P profile without touching Claude Code's
+ * ~/.claude settings. The profile contains no credential: Claude invokes the helper,
+ * which reads the existing mode-0600 Penny config at request time.
+ */
+export async function configureClaudeDesktopProfile(config) {
+  if (!config.api_key) {
+    throw new Error("No PennyRouter key found. Run `npx pennyrouter install` first.");
+  }
+  if (!config.gateway_base_url) {
+    throw new Error("No PennyRouter gateway configured. Run `npx pennyrouter install` first.");
+  }
+
+  const library = claudeDesktopConfigLibraryPath();
+  const metaPath = join(library, "_meta.json");
+  const profilePath = join(library, `${CLAUDE_DESKTOP_PROFILE_ID}.json`);
+  const helperPath = claudeDesktopCredentialHelperPath();
+  const meta = (await readJsonFile(metaPath, null)) || { entries: [] };
+  const entries = Array.isArray(meta.entries) ? meta.entries : [];
+  const priorState = config.claude_desktop || {};
+  const previousAppliedId = meta.appliedId !== CLAUDE_DESKTOP_PROFILE_ID
+    ? (meta.appliedId || priorState.previous_applied_id || null)
+    : (priorState.previous_applied_id || null);
+
+  await executableWrite(helperPath, renderClaudeDesktopCredentialHelper());
+  const gatewayBaseUrl = String(config.gateway_base_url)
+    .replace(/\/+$/, "")
+    .replace(/\/v1$/, "");
+  const profile = {
+    inferenceProvider: "gateway",
+    inferenceGatewayBaseUrl: gatewayBaseUrl,
+    inferenceGatewayAuthScheme: "x-api-key",
+    inferenceCredentialKind: "helper-script",
+    inferenceCredentialHelper: helperPath,
+    inferenceCredentialHelperTtlSec: 60,
+    // Let Desktop populate its picker from PennyRouter's Anthropic-compatible
+    // /v1/models response. Do not also set inferenceModels: that key is an explicit
+    // override and would silently suppress discovery.
+    modelDiscoveryEnabled: true,
+  };
+  await privateWrite(profilePath, `${JSON.stringify(profile, null, 2)}\n`);
+  const nextEntries = entries.filter((entry) => entry?.id !== CLAUDE_DESKTOP_PROFILE_ID);
+  nextEntries.push({ id: CLAUDE_DESKTOP_PROFILE_ID, name: CLAUDE_DESKTOP_PROFILE_NAME });
+  await privateWrite(metaPath, `${JSON.stringify({
+    ...meta,
+    appliedId: CLAUDE_DESKTOP_PROFILE_ID,
+    entries: nextEntries,
+  }, null, 2)}\n`);
+
+  config.claude_desktop = {
+    managed_profile_id: CLAUDE_DESKTOP_PROFILE_ID,
+    previous_applied_id: previousAppliedId,
+  };
+  await savePennyConfig(config);
+  return { helperPath, library, profilePath, previousAppliedId };
+}
+
+/**
+ * Select standard, first-party Claude Desktop without deleting PennyRouter's saved
+ * third-party profile. Claude chooses its data directory and provider once at startup;
+ * an absent local appliedId is the standard/native selection, while the Penny profile
+ * remains available for the next explicit gateway launch.
+ */
+export async function selectClaudeDesktopNativeMode() {
+  const library = claudeDesktopConfigLibraryPath();
+  const metaPath = join(library, "_meta.json");
+  const meta = await readJsonFile(metaPath, null);
+  if (!meta || !Object.hasOwn(meta, "appliedId")) return;
+  const next = { ...meta };
+  delete next.appliedId;
+  await privateWrite(metaPath, `${JSON.stringify(next, null, 2)}\n`);
+}
+
+/** Read the local Claude Desktop mode selected for the next app launch. */
+export async function readClaudeDesktopMode() {
+  const library = claudeDesktopConfigLibraryPath();
+  const meta = await readJsonFile(join(library, "_meta.json"), null);
+  const appliedId = meta?.appliedId || null;
+  const entries = Array.isArray(meta?.entries) ? meta.entries : [];
+  const entry = entries.find((candidate) => candidate?.id === appliedId);
+  if (!appliedId) {
+    return { mode: "native", label: "Native Claude", profileId: null, profileName: null };
+  }
+  if (appliedId === CLAUDE_DESKTOP_PROFILE_ID) {
+    return {
+      mode: "gateway",
+      label: "PennyRouter Gateway",
+      profileId: appliedId,
+      profileName: CLAUDE_DESKTOP_PROFILE_NAME,
+    };
+  }
+  return {
+    mode: "third-party",
+    label: entry?.name ? `Third-party: ${entry.name}` : "Third-party inference",
+    profileId: appliedId,
+    profileName: entry?.name || null,
+  };
+}
+
+/**
+ * Claude is a single-instance app and reads provider configuration only at launch.
+ * Refuse mode changes while its main process is alive so an on-disk selection never
+ * disagrees with the mode the visible app is actually using.
+ */
+export function isClaudeDesktopRunning(run = spawnSync) {
+  return isDesktopProcessRunning(
+    process.platform === "darwin" ? ["Claude"] : ["claude-desktop", "Claude"],
+    "Claude.exe",
+    run,
+  );
+}
+
+export function isCodexDesktopRunning(run = spawnSync) {
+  return isDesktopProcessRunning(
+    process.platform === "darwin" ? ["Codex"] : ["codex-desktop", "Codex"],
+    "Codex.exe",
+    run,
+  );
+}
+
+function isDesktopProcessRunning(names, windowsImageName, run) {
+  if (process.platform === "win32") {
+    const result = run("tasklist", ["/FI", `IMAGENAME eq ${windowsImageName}`, "/NH"], {
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    return result.status === 0 && (result.stdout || "").toLowerCase()
+      .includes(windowsImageName.toLowerCase());
+  }
+  return names.some((name) => run("pgrep", ["-x", name], {
+    encoding: "utf8",
+    stdio: "ignore",
+  }).status === 0);
+}
+
+export async function restoreClaudeDesktopProfile() {
+  const config = await loadPennyConfig();
+  const state = config.claude_desktop;
+  const library = claudeDesktopConfigLibraryPath();
+  const metaPath = join(library, "_meta.json");
+  const profilePath = join(library, `${CLAUDE_DESKTOP_PROFILE_ID}.json`);
+  const meta = await readJsonFile(metaPath, null);
+
+  if (meta) {
+    const entries = (Array.isArray(meta.entries) ? meta.entries : [])
+      .filter((entry) => entry?.id !== CLAUDE_DESKTOP_PROFILE_ID);
+    const next = { ...meta, entries };
+    if (meta.appliedId === CLAUDE_DESKTOP_PROFILE_ID) {
+      const previous = state?.previous_applied_id;
+      const previousExists = previous
+        && entries.some((entry) => entry?.id === previous)
+        && await readText(join(library, `${previous}.json`), "");
+      if (previousExists) next.appliedId = previous;
+      else delete next.appliedId;
+    }
+    await privateWrite(metaPath, `${JSON.stringify(next, null, 2)}\n`);
+  }
+  await unlink(profilePath).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  await unlink(claudeDesktopCredentialHelperPath()).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  if (state) {
+    delete config.claude_desktop;
+    await savePennyConfig(config);
+  }
+}
+
+export async function readClaudeDesktopCredential() {
+  const config = await loadPennyConfig();
+  if (!config.api_key) throw new Error("PennyRouter credential is not configured.");
+  return config.api_key;
+}
+
+export async function runClaudeDesktopCredentialHelper() {
+  process.stdout.write(await readClaudeDesktopCredential());
+  return 0;
+}
+
+/**
+ * Build a disposable Codex home for the desktop app. Codex Desktop does not accept the
+ * CLI's --profile flag, so its default provider has to be selected in config.toml. Putting
+ * that config in an overlay keeps the user's real Codex mode native after the app exits,
+ * including after a crash or force-quit.
+ */
+export async function createCodexDesktopHome({ config, realHome }) {
+  const overlay = await mkdtemp(join(tmpdir(), "penny-codex-desktop-"));
+  try {
+    for (const entry of await readdir(realHome)) {
+      if (entry === "config.toml") continue;
+      await symlink(join(realHome, entry), join(overlay, entry));
+    }
+    if (!config.api_key) throw new Error("No PennyRouter key found. Run `npx pennyrouter install` first.");
+    if (!config.gateway_base_url) throw new Error("No PennyRouter gateway configured. Run `npx pennyrouter install` first.");
+    const nativeConfig = await readText(join(realHome, "config.toml"), "");
+    const desktopConfig = setCodexDesktopDefault(renderCodexConfig(removeCodexPennyProvider(nativeConfig), {
+      apiKey: config.api_key,
+      gatewayBaseUrl: config.gateway_base_url,
+      subscriptionAuth: Boolean(config.harnesses?.codex?.subscription_auth),
+    }));
+    await privateWrite(join(overlay, "config.toml"), desktopConfig);
+    return overlay;
+  } catch (error) {
+    await rm(overlay, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function setCodexDesktopDefault(text) {
+  const lines = String(text).split("\n");
+  const firstTable = lines.findIndex((line) => /^\s*\[/.test(line));
+  const rootEnd = firstTable < 0 ? lines.length : firstTable;
+  const root = lines.slice(0, rootEnd).filter((line) => !/^\s*model_provider\s*=/.test(line));
+  root.unshift('model_provider = "pennyrouter"');
+  return [...root, ...lines.slice(rootEnd)].join("\n");
+}
+
+function removeCodexPennyProvider(text) {
+  const lines = String(text).split("\n");
+  const start = lines.findIndex((line) => /^\s*\[model_providers\.pennyrouter\]\s*$/.test(line));
+  if (start < 0) return String(text);
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[/.test(lines[end])) end += 1;
+  lines.splice(start, end - start);
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
 function terminalTitle(text) {
   // OSC titles are interpreted by the terminal, so remove control characters and
   // the OSC terminators rather than allowing gateway-provided text into the escape.
@@ -290,14 +589,15 @@ function renderPennyTerminalTitle(status) {
   if (status?.model_display_name) parts.push(status.model_display_name);
   else if (status?.model) parts.push(status.model);
   if (status?.auth_mode) parts.push(`(${status.auth_mode})`);
-  parts.push(renderCacheWarmth(status));
+  const warmth = renderCacheWarmth(status);
+  if (warmth) parts.push(warmth);
   return parts.join(" · ");
 }
 
 function renderCacheWarmth(status) {
   const expiresAt = status?.cache_expires_at;
   if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= 0) {
-    return "❄️ cold";
+    return "";
   }
   const remaining = Math.floor(expiresAt - Date.now() / 1000);
   if (remaining <= 0) return "❄️ cold";
@@ -311,19 +611,27 @@ function renderCacheWarmth(status) {
  * This is deliberately local and best-effort: failure to poll the gateway must never
  * affect Codex, and non-TTY invocations (CI, pipes) receive no escape sequences.
  */
-export function startPennyTerminalTitle({ gatewayBaseUrl, apiKey }) {
+export function startPennyTerminalTitle({ gatewayBaseUrl, apiKey, titleSessionId,
+                                           titleSessionFile }) {
   if (!process.stdout.isTTY) return () => {};
 
   let status = null;
   let stopped = false;
   let statusInFlight = false;
+  let resolvedTitleSessionId = titleSessionId || "";
 
   const refreshStatus = async () => {
     if (stopped || statusInFlight || !gatewayBaseUrl || !apiKey) return;
     statusInFlight = true;
     try {
+      if (!resolvedTitleSessionId && titleSessionFile) {
+        try { resolvedTitleSessionId = (await readFile(titleSessionFile, "utf8")).trim(); }
+        catch { /* Claude statusline has not handed off its session yet */ }
+      }
+      const headers = { "x-api-key": apiKey };
+      if (resolvedTitleSessionId) headers["x-pennyrouter-title-session"] = resolvedTitleSessionId;
       const response = await fetch(`${String(gatewayBaseUrl).replace(/\/$/, "")}/v1/penny/statusline`, {
-        headers: { "x-api-key": apiKey },
+        headers,
         signal: AbortSignal.timeout(4000),
       });
       if (response.ok) status = await response.json();
@@ -498,6 +806,9 @@ function removeWindowsPathEntry() {
 }
 
 export async function removePennyRuntime() {
+  // The Desktop profile's credential helper lives in the Penny runtime. Restore the
+  // previously selected Claude Desktop profile before removing that executable.
+  await restoreClaudeDesktopProfile();
   const config = await loadPennyConfig();
   if (process.platform === "win32") {
     if (config.windows_path_managed) removeWindowsPathEntry();
@@ -547,6 +858,7 @@ export function buildPennyInvocation(harness, args, config) {
   assertNoConflictingArgs(harness, args);
   const env = { ...process.env, PENNYROUTER_API_KEY: config.api_key };
   if (harness === "claude") {
+    env.PENNYROUTER_TITLE_SESSION_FILE = join(pennyDataDir(), `title-session-${randomUUID()}`);
     const models = item.models || {};
     env.ANTHROPIC_BASE_URL = config.gateway_base_url;
     env.ANTHROPIC_AUTH_TOKEN = config.api_key;
@@ -572,9 +884,14 @@ export function buildPennyInvocation(harness, args, config) {
     };
   }
   if (harness === "codex") {
+    // The parent process owns the OSC tab title, while Codex owns the actual conversation
+    // identity. Give both sides a launch-local join token so title warmth cannot bleed between
+    // two Codex TUIs using the same Penny key.
+    env.PENNYROUTER_TITLE_SESSION_ID = randomUUID();
     return { command: "codex", args: ["--profile", "pennyrouter", ...args], env };
   }
   if (harness === "opencode") {
+    env.PENNYROUTER_TITLE_SESSION_ID = randomUUID();
     return { command: "opencode", args, env };
   }
   throw new Error(`Unknown Penny harness "${harness}". Try penny claude, penny codex, or penny opencode.`);
@@ -597,6 +914,56 @@ export async function runPenny(argv = process.argv.slice(2)) {
     throw new Error(`Unknown harness "${harness}". Try penny claude, penny codex, or penny opencode.`);
   }
   const config = await loadPennyConfig();
+  if (harness === "claude" && argv[1]?.toLowerCase() === "desktop") {
+    const option = argv[2]?.toLowerCase();
+    if (option === "--restore" || option === "restore") {
+      if (argv.length > 3) {
+        throw new Error("Usage: penny claude desktop [gateway|native|status|--restore]");
+      }
+      await restoreClaudeDesktopProfile();
+      console.log("PennyRouter's Claude Desktop profile was removed and the previous profile restored.");
+      console.log("Fully quit and reopen Claude Desktop for the restored profile to take effect.");
+      return 0;
+    }
+    if (option === "status" || option === "--status") {
+      const json = argv[3]?.toLowerCase() === "--json";
+      if (argv.length > (json ? 4 : 3)) {
+        throw new Error("Usage: penny claude desktop status [--json]");
+      }
+      const status = { ...(await readClaudeDesktopMode()), running: isClaudeDesktopRunning() };
+      if (json) console.log(JSON.stringify(status));
+      else {
+        console.log(`Claude Desktop mode: ${status.label}`);
+        console.log(`Claude Desktop is ${status.running ? "running" : "not running"}.`);
+      }
+      return 0;
+    }
+    const mode = option === "native" || option === "--native" ? "native" : "gateway";
+    const legacyLogs = option === "--logs" || option === "logs";
+    const modeLogs = argv[3]?.toLowerCase() === "--logs" || argv[3]?.toLowerCase() === "logs";
+    const logs = legacyLogs || modeLogs;
+    const validOption = option === undefined || legacyLogs
+      || ["gateway", "--gateway", "native", "--native"].includes(option);
+    if (!validOption || argv.length > (modeLogs ? 4 : (legacyLogs ? 3 : (option ? 3 : 2)))) {
+      throw new Error(
+        "Usage: penny claude desktop [gateway|native|status] [--logs|--json]",
+      );
+    }
+    return runClaudeDesktop(config, { logs, mode });
+  }
+  if (harness === "codex" && argv[1]?.toLowerCase() === "desktop") {
+    const option = argv[2]?.toLowerCase();
+    const mode = option === "native" || option === "--native" ? "native" : "gateway";
+    const legacyLogs = option === "--logs" || option === "logs";
+    const modeLogs = argv[3]?.toLowerCase() === "--logs" || argv[3]?.toLowerCase() === "logs";
+    const logs = legacyLogs || modeLogs;
+    const validOption = option === undefined || legacyLogs
+      || ["gateway", "--gateway", "native", "--native"].includes(option);
+    if (!validOption || argv.length > (modeLogs ? 4 : (legacyLogs ? 3 : (option ? 3 : 2)))) {
+      throw new Error("Usage: penny codex desktop [gateway|native] [--logs]");
+    }
+    return runCodexDesktop(config, { logs, mode });
+  }
   const invocation = buildPennyInvocation(harness, argv.slice(1), config);
   const child = spawn(invocation.command, invocation.args, {
     cwd: process.cwd(),
@@ -604,10 +971,12 @@ export async function runPenny(argv = process.argv.slice(2)) {
     stdio: "inherit",
     shell: process.platform === "win32",
   });
-  const stopTerminalTitle = ["codex", "opencode"].includes(harness)
+  const stopTerminalTitle = ["claude", "codex", "opencode"].includes(harness)
     ? startPennyTerminalTitle({
         gatewayBaseUrl: config.gateway_base_url,
         apiKey: config.api_key,
+        titleSessionId: invocation.env.PENNYROUTER_TITLE_SESSION_ID,
+        titleSessionFile: invocation.env.PENNYROUTER_TITLE_SESSION_FILE,
       })
     : () => {};
   const result = await waitForChild(child);
@@ -616,6 +985,92 @@ export async function runPenny(argv = process.argv.slice(2)) {
   return result.code ?? 1;
 }
 
+async function runClaudeDesktop(config, { logs = false, mode = "gateway" } = {}) {
+  if (isClaudeDesktopRunning()) {
+    throw new Error(
+      `Claude Desktop is already running. Fully quit it before switching to ${mode} mode.`,
+    );
+  }
+  if (mode === "native") await selectClaudeDesktopNativeMode();
+  else await configureClaudeDesktopProfile(config);
+  const child = spawn(claudeDesktopExecutable(), [], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: logs ? "inherit" : "ignore",
+    detached: !logs,
+    shell: process.platform === "win32",
+  });
+  if (!logs) {
+    child.unref();
+    console.log(mode === "native"
+      ? "Claude Desktop launched in native mode (detached)."
+      : "Claude Desktop launched with PennyRouter Gateway (detached).");
+    console.log("Use `penny claude desktop status` to see the selected mode.");
+    return 0;
+  }
+  const result = await waitForChild(child);
+  if (result.signal) return 128 + (osConstants.signals[result.signal] || 0);
+  return result.code ?? 1;
+}
+
+async function runCodexDesktop(config, { logs = false, mode = "gateway" } = {}) {
+  if (isCodexDesktopRunning()) {
+    throw new Error(`Codex Desktop is already running. Fully quit it before launching ${mode} mode.`);
+  }
+  if (mode === "native") {
+    const child = spawn(codexDesktopExecutable(), [], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: logs ? "inherit" : "ignore",
+      detached: !logs,
+      shell: process.platform === "win32",
+    });
+    if (!logs) {
+      child.unref();
+      console.log("Codex Desktop launched in native mode (detached).");
+      return 0;
+    }
+    const result = await waitForChild(child);
+    if (result.signal) return 128 + (osConstants.signals[result.signal] || 0);
+    return result.code ?? 1;
+  }
+  const realHome = process.env.CODEX_HOME || join(homeDir(), ".codex");
+  const overlay = await createCodexDesktopHome({ config, realHome });
+  if (!logs) {
+    const supervisor = spawn(process.execPath, [
+      fileURLToPath(new URL("../bin/penny.js", import.meta.url)),
+      "__codex-desktop-supervisor",
+      overlay,
+    ], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: "ignore",
+      detached: true,
+    });
+    supervisor.unref();
+    console.log("Codex Desktop launched with PennyRouter (detached). Use `penny codex desktop gateway --logs` to keep logs in this terminal.");
+    return 0;
+  }
+
+  return runCodexDesktopSupervisor(overlay);
+}
+
+export async function runCodexDesktopSupervisor(overlay) {
+  const child = spawn(codexDesktopExecutable(), [], {
+    cwd: process.cwd(),
+    env: { ...process.env, CODEX_HOME: overlay },
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  try {
+    const result = await waitForChild(child);
+    if (result.signal) return 128 + (osConstants.signals[result.signal] || 0);
+    return result.code ?? 1;
+  } finally {
+    await rm(overlay, { recursive: true, force: true });
+  }
+}
+
 export async function fileMode(path) {
   return (await stat(path)).mode & 0o777;
 }

package/src/launch.test.js

@@ -1,22 +1,33 @@
 import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 import {
   buildPennyInvocation,
+  claudeDesktopConfigLibraryPath,
+  claudeDesktopCredentialHelperPath,
   claudeLaunchSettingsPath,
   claudeUserSkillPath,
   codexLaunchProfilePath,
+  configureClaudeDesktopProfile,
+  createCodexDesktopHome,
   configurePennyHarness,
   fileMode,
   installPennyRuntime,
+  isClaudeDesktopRunning,
+  isCodexDesktopRunning,
   loadPennyConfig,
   pennyConfigPath,
   pennyRuntimeDir,
   pennyShimPath,
+  readClaudeDesktopCredential,
+  readClaudeDesktopMode,
   removePennyHarness,
   removePennyRuntime,
+  restoreClaudeDesktopProfile,
+  selectClaudeDesktopNativeMode,
   renderCodexLaunchProfile,
 } from "./launch.js";
 import { claudeCodeHarness } from "./harnesses/claude-code.js";
@@ -40,7 +51,7 @@ async function main() {
     permissions: { allow: ["Read"] },
     statusLine: { type: "command", command: "native-status" },
   }, null, 2)}\n`;
-  const nativeCodex = 'model = "native-model"\n';
+  const nativeCodex = 'model = "native-model"\n\nmodel_provider = "pennyrouter"\n\n[model_providers.pennyrouter]\nname = "PennyRouter"\nbase_url = "http://localhost:8400/v1"\n';
   fs.writeFileSync(path.join(home, ".claude", "settings.json"), nativeClaude);
   fs.writeFileSync(path.join(home, ".codex", "config.toml"), nativeCodex);
   fs.writeFileSync(path.join(home, ".zshrc"), "# user setting\n");
@@ -56,6 +67,21 @@ async function main() {
   });
 
   try {
+    const desktopLibrary = claudeDesktopConfigLibraryPath();
+    const nativeDesktopId = "native-profile";
+    fs.mkdirSync(desktopLibrary, { recursive: true });
+    fs.writeFileSync(
+      path.join(desktopLibrary, `${nativeDesktopId}.json`),
+      `${JSON.stringify({ inferenceProvider: "anthropic" }, null, 2)}\n`,
+    );
+    fs.writeFileSync(
+      path.join(desktopLibrary, "_meta.json"),
+      `${JSON.stringify({
+        appliedId: nativeDesktopId,
+        entries: [{ id: nativeDesktopId, name: "Native" }],
+      }, null, 2)}\n`,
+    );
+
     const first = await installPennyRuntime();
     const staleSkill = path.join(pennyRuntimeDir(), "claude-plugin", "skills", "penny", "SKILL.md");
     fs.mkdirSync(path.dirname(staleSkill), { recursive: true });
@@ -97,9 +123,70 @@ async function main() {
     const config = await loadPennyConfig();
     assert.equal(config.api_key, "pr-super-secret");
     assert.equal(config.harnesses.opencode.enabled, true);
+    const desktop = await configureClaudeDesktopProfile(config);
+    const desktopProfile = JSON.parse(fs.readFileSync(desktop.profilePath, "utf8"));
+    const desktopMeta = JSON.parse(
+      fs.readFileSync(path.join(desktopLibrary, "_meta.json"), "utf8"),
+    );
+    assert.equal(desktopProfile.inferenceProvider, "gateway");
+    assert.equal(desktopProfile.inferenceGatewayBaseUrl, "https://gateway.example");
+    assert.equal(desktopProfile.inferenceCredentialKind, "helper-script");
+    assert.equal(desktopProfile.inferenceGatewayApiKey, undefined);
+    assert.equal(desktopProfile.modelDiscoveryEnabled, true);
+    assert.equal(desktopProfile.inferenceModels, undefined);
+    assert.equal(desktopMeta.appliedId, "70656e6e-7972-4f75-8465-720000000001");
+    assert.equal((await loadPennyConfig()).claude_desktop.previous_applied_id, nativeDesktopId);
+    assert.equal(await readClaudeDesktopCredential(), "pr-super-secret");
+    assert.equal(await fileMode(claudeDesktopCredentialHelperPath()), 0o700);
+    const helperResult = spawnSync(claudeDesktopCredentialHelperPath(), [], {
+      encoding: "utf8",
+      env: process.env,
+    });
+    assert.equal(helperResult.status, 0, helperResult.stderr);
+    assert.equal(helperResult.stdout, "pr-super-secret");
+    assert.equal((await readClaudeDesktopMode()).mode, "gateway");
+
+    await selectClaudeDesktopNativeMode();
+    const nativeModeMeta = JSON.parse(
+      fs.readFileSync(path.join(desktopLibrary, "_meta.json"), "utf8"),
+    );
+    assert.equal(nativeModeMeta.appliedId, undefined);
+    assert.ok(fs.existsSync(desktop.profilePath), "native mode preserves the Penny profile");
+    assert.ok(fs.existsSync(claudeDesktopCredentialHelperPath()), "native mode preserves its helper");
+    assert.equal((await readClaudeDesktopMode()).mode, "native");
+
+    await configureClaudeDesktopProfile(await loadPennyConfig());
+    assert.equal((await readClaudeDesktopMode()).mode, "gateway");
+    assert.equal((await loadPennyConfig()).claude_desktop.previous_applied_id, nativeDesktopId);
+
+    assert.equal(isClaudeDesktopRunning(() => ({ status: 1, stdout: "" })), false);
+    assert.equal(isClaudeDesktopRunning(() => ({ status: 0, stdout: "Claude" })), true);
+    assert.equal(isCodexDesktopRunning(() => ({ status: 1, stdout: "" })), false);
+    assert.equal(isCodexDesktopRunning(() => ({ status: 0, stdout: "Codex" })), true);
+
+    await restoreClaudeDesktopProfile();
+    const restoredDesktopMeta = JSON.parse(
+      fs.readFileSync(path.join(desktopLibrary, "_meta.json"), "utf8"),
+    );
+    assert.equal(restoredDesktopMeta.appliedId, nativeDesktopId);
+    assert.ok(!fs.existsSync(desktop.profilePath));
+    assert.ok(!fs.existsSync(claudeDesktopCredentialHelperPath()));
+    await configureClaudeDesktopProfile(await loadPennyConfig());
+    const desktopHome = await createCodexDesktopHome({
+      config,
+      realHome: path.join(home, ".codex"),
+    });
+    const desktopConfig = fs.readFileSync(path.join(desktopHome, "config.toml"), "utf8");
+    assert.match(desktopConfig, /^model_provider = "pennyrouter"/);
+    assert.match(desktopConfig, /\[model_providers\.pennyrouter\]/);
+    assert.match(desktopConfig, /http_headers = \{ "x-pennyrouter-key" = "pr-super-secret" \}/);
+    assert.equal(fs.readFileSync(path.join(home, ".codex", "config.toml"), "utf8"), nativeCodex);
+    fs.rmSync(desktopHome, { recursive: true, force: true });
     const codexProfile = fs.readFileSync(codexLaunchProfilePath(), "utf8");
-    assert.ok(codexProfile.includes('env_http_headers = { "x-pennyrouter-key" = "PENNYROUTER_API_KEY" }'));
+    assert.ok(codexProfile.includes('"x-pennyrouter-key" = "PENNYROUTER_API_KEY"'));
     assert.ok(codexProfile.includes("[tui]\nterminal_title = []"));
+    assert.ok(codexProfile.includes('"x-pennyrouter-title-session" = "PENNYROUTER_TITLE_SESSION_ID"'));
+    assert.ok(codexProfile.includes('"x-pennyrouter-harness" = "codex"'));
     assert.ok(!codexProfile.includes("pr-super-secret"));
     assert.ok(!rc.includes("pr-super-secret"));
 
@@ -174,6 +261,13 @@ async function main() {
     assert.ok(!fs.existsSync(pennyShimPath()));
     assert.ok(!fs.existsSync(pennyRuntimeDir()));
     assert.ok(!fs.existsSync(pennyConfigPath()));
+    const uninstallDesktopMeta = JSON.parse(
+      fs.readFileSync(path.join(desktopLibrary, "_meta.json"), "utf8"),
+    );
+    assert.equal(uninstallDesktopMeta.appliedId, nativeDesktopId);
+    assert.ok(!uninstallDesktopMeta.entries.some(
+      (entry) => entry.id === "70656e6e-7972-4f75-8465-720000000001",
+    ));
     assert.equal(fs.readFileSync(path.join(home, ".zshrc"), "utf8"), "# user setting\n");
     assert.equal(fs.readFileSync(path.join(home, ".zprofile"), "utf8"), "");
 

package/src/statusline.js

@@ -91,6 +91,7 @@ const stateDir = join(
   "pennyrouter",
 );
 const cacheDir = join(stateDir, "statusline-cache");
+const titleSessionFile = process.env.PENNYROUTER_TITLE_SESSION_FILE || "";
 // A wrapped user statusline command can be slow to spawn (npx especially: on Windows
 // it goes through an extra cmd.exe/npx.cmd hop and can take 2-4s per invocation, vs
 // well under 1s on macOS/Linux). Claude Code re-invokes this script every ~1s
@@ -135,9 +136,6 @@ if (process.argv[2] === "--refresh") {
     });
     if (resp.ok) {
       const data = await resp.json();
-      if (data.cache_expires_at && typeof data.cache_expires_at === "number") {
-        data.cache_expires_at = Math.round(data.cache_expires_at / 10) * 10;
-      }
       mkdirSync(cacheDir, { recursive: true });
       writeFileSync(join(cacheDir, sessionId + ".json"), JSON.stringify(data));
     }
@@ -167,6 +165,11 @@ const raw = readFileSync(0, "utf8");
 let input = {};
 try { input = JSON.parse(raw); } catch { /* keep {} */ }
 const sessionId = input.session_id || "";
+// The parent Penny launcher owns the tab title, while this command knows Claude Code's
+// actual session id. Hand it across a launch-local file for an exact title lookup.
+if (titleSessionFile && sessionId) {
+  try { writeFileSync(titleSessionFile, sessionId, { mode: 0o600 }); } catch { /* best-effort */ }
+}
 const refreshMs = (config.refresh_seconds ?? 15) * 1000;
 
 const cachePath = join(cacheDir, sessionId + ".json");