llm-switcher 1.2.7 → 1.2.9

package/plugin.mjs

@@ -0,0 +1,204 @@
+// ============================================================
+// plugin.mjs - installs the launch hook into the two coding tools, and edits no configuration.
+//
+// WHY A HOOK AT ALL
+//   The shim raises a notice at launch, but only when the shim runs, and that needs the shim
+//   directory first on PATH. A person who keeps their own `claude` wrapper never sees it. A hook
+//   runs inside the tool, so it reports whatever the launcher is.
+//
+// WHY NOTHING IS EDITED
+//   Claude Code loads any folder under a skills directory that holds `.claude-plugin/plugin.json`
+//   as a plugin, on the next session, with no marketplace and no install step. Codex loads
+//   `$CODEX_HOME/hooks.json` by itself. So each tool reads a file of its own, and `settings.json`
+//   and `config.toml` are never opened.
+//
+// WHY IT IS OPT-IN
+//   The notice is a reminder, not a part of the routing. A person who does not want it installs
+//   nothing and loses nothing: the traffic still goes through the gateway, and the shim toast
+//   still fires.
+// ============================================================
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const HOOK_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'hook-status.mjs');
+
+export const PLUGIN_NAME = 'llm-switcher-status';
+// Written into every file this module owns, and the only thing that authorizes an overwrite.
+const MARK = 'Generated by LLM Switcher - safe to delete';
+// A fresh start and a resumed session. A resume is the case the switcher exists for, and compact
+// is left out on purpose: the notice belongs at the start of a session, not in the middle of one.
+const SESSION_SOURCES = 'startup|resume';
+
+export function claudeSkillsDir(env = process.env, home = os.homedir()) {
+  return path.join(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'skills');
+}
+export function codexHome(env = process.env, home = os.homedir()) {
+  return env.CODEX_HOME || path.join(home, '.codex');
+}
+
+export function renderClaudePlugin(version = 'dev') {
+  return `${JSON.stringify({
+    name: PLUGIN_NAME,
+    version,
+    description: 'Reports at the start of a session when LLM Switcher routes this tool to another provider.',
+    author: { name: 'LLM Switcher' }
+  }, null, 2)}\n`;
+}
+
+// The args form, not one command string: a Windows path holds backslashes and spaces, and this
+// way no shell has to quote it.
+export function renderClaudeHooks() {
+  return `${JSON.stringify({
+    description: MARK,
+    hooks: {
+      SessionStart: [{
+        matcher: SESSION_SOURCES,
+        hooks: [{ type: 'command', command: 'node', args: [HOOK_SCRIPT, 'claude'], timeout: 10 }]
+      }]
+    }
+  }, null, 2)}\n`;
+}
+
+// Codex takes one command string. It is quoted here, once, for the same reason.
+export function renderCodexHooks() {
+  return `${JSON.stringify({ description: MARK, hooks: { SessionStart: [codexEntry()] } }, null, 2)}\n`;
+}
+
+function codexEntry() {
+  return {
+    matcher: SESSION_SOURCES,
+    hooks: [{ type: 'command', command: `node "${HOOK_SCRIPT}" codex`, timeout: 10 }]
+  };
+}
+
+// Ours is the entry that runs our script. Nothing else in the file is touched, by any operation.
+const isOurs = (group) => JSON.stringify(group).includes('hook-status.mjs');
+
+function writeAtomic(file, content) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  try {
+    fs.writeFileSync(tmp, content, 'utf8');
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+function readJsonFile(file) {
+  if (!fs.existsSync(file)) return { missing: true };
+  const raw = fs.readFileSync(file, 'utf8');
+  try { return { value: JSON.parse(raw) }; } catch (err) { return { error: err.message }; }
+}
+
+// ---- Claude Code -----------------------------------------------------------------------------
+
+function pluginDir(opts) {
+  return path.join(opts.claudeSkillsDir || claudeSkillsDir(), PLUGIN_NAME);
+}
+
+function installClaude(opts, version) {
+  const dir = pluginDir(opts);
+  const manifest = path.join(dir, '.claude-plugin', 'plugin.json');
+  // A folder with a manifest that is not ours belongs to someone else, whatever its name is.
+  if (fs.existsSync(manifest)) {
+    const cur = readJsonFile(manifest);
+    if (cur.error) return { ok: false, reason: `${manifest} does not parse: ${cur.error}` };
+    if (cur.value?.name !== PLUGIN_NAME) {
+      return { ok: false, reason: `${dir} holds another plugin (${cur.value?.name}), so nothing was changed` };
+    }
+  }
+  writeAtomic(manifest, renderClaudePlugin(version));
+  writeAtomic(path.join(dir, 'hooks', 'hooks.json'), renderClaudeHooks());
+  return { ok: true, path: dir };
+}
+
+function uninstallClaude(opts) {
+  const dir = pluginDir(opts);
+  const manifest = path.join(dir, '.claude-plugin', 'plugin.json');
+  if (!fs.existsSync(manifest)) return { ok: true, path: dir, absent: true };
+  const cur = readJsonFile(manifest);
+  if (cur.value?.name !== PLUGIN_NAME) return { ok: false, reason: `${dir} is not our plugin, so nothing was removed` };
+  fs.rmSync(dir, { recursive: true, force: true });
+  return { ok: true, path: dir };
+}
+
+// ---- Codex -----------------------------------------------------------------------------------
+
+function codexHooksPath(opts) {
+  return path.join(opts.codexHome || codexHome(), 'hooks.json');
+}
+
+// The file may already hold the hooks of this machine, so it is merged, never replaced. A file
+// that does not parse is left exactly as it is: it can hold work that no backup would return.
+function installCodex(opts) {
+  const file = codexHooksPath(opts);
+  const cur = readJsonFile(file);
+  if (cur.error) return { ok: false, reason: `${file} does not parse: ${cur.error}, so nothing was changed` };
+  if (cur.missing) {
+    writeAtomic(file, renderCodexHooks());
+    return { ok: true, path: file };
+  }
+  const doc = cur.value && typeof cur.value === 'object' ? cur.value : {};
+  doc.hooks = doc.hooks && typeof doc.hooks === 'object' ? doc.hooks : {};
+  const groups = Array.isArray(doc.hooks.SessionStart) ? doc.hooks.SessionStart : [];
+  doc.hooks.SessionStart = [...groups.filter(g => !isOurs(g)), codexEntry()];
+  writeAtomic(file, `${JSON.stringify(doc, null, 2)}\n`);
+  return { ok: true, path: file };
+}
+
+function uninstallCodex(opts) {
+  const file = codexHooksPath(opts);
+  const cur = readJsonFile(file);
+  if (cur.missing) return { ok: true, path: file, absent: true };
+  if (cur.error) return { ok: false, reason: `${file} does not parse: ${cur.error}, so nothing was changed` };
+  const doc = cur.value && typeof cur.value === 'object' ? cur.value : {};
+  const groups = Array.isArray(doc.hooks?.SessionStart) ? doc.hooks.SessionStart : [];
+  const kept = groups.filter(g => !isOurs(g));
+  if (kept.length) doc.hooks.SessionStart = kept;
+  else delete doc.hooks?.SessionStart;
+  // Only a file that holds nothing but our own mark is removed. Anything else is written back.
+  const empty = doc.hooks && Object.keys(doc.hooks).length === 0;
+  if (empty && doc.description === MARK) {
+    fs.rmSync(file, { force: true });
+    return { ok: true, path: file };
+  }
+  writeAtomic(file, `${JSON.stringify(doc, null, 2)}\n`);
+  return { ok: true, path: file };
+}
+
+// ---- The three commands ----------------------------------------------------------------------
+
+function summarize(results) {
+  const out = { installed: [], failed: [], paths: {} };
+  for (const [tool, r] of Object.entries(results)) {
+    if (r.ok) out.installed.push(tool); else out.failed.push({ tool, reason: r.reason });
+    if (r.path) out.paths[tool] = r.path;
+  }
+  return out;
+}
+
+/** { installed: ['claude','codex'], failed: [{ tool, reason }], paths: { claude, codex } } */
+export function installPlugin(opts = {}, version = 'dev') {
+  return summarize({ claude: installClaude(opts, version), codex: installCodex(opts) });
+}
+
+export function uninstallPlugin(opts = {}) {
+  return summarize({ claude: uninstallClaude(opts), codex: uninstallCodex(opts) });
+}
+
+export function pluginStatus(opts = {}) {
+  const dir = pluginDir(opts);
+  const claudeManifest = readJsonFile(path.join(dir, '.claude-plugin', 'plugin.json'));
+  const file = codexHooksPath(opts);
+  const codexDoc = readJsonFile(file);
+  const codexGroups = Array.isArray(codexDoc.value?.hooks?.SessionStart) ? codexDoc.value.hooks.SessionStart : [];
+  return {
+    claude: { installed: claudeManifest.value?.name === PLUGIN_NAME, path: dir, id: `${PLUGIN_NAME}@skills-dir` },
+    codex: { installed: codexGroups.some(isOurs), path: file }
+  };
+}

package/proxy.mjs

@@ -500,7 +500,54 @@ function previewOf(ir) {
 // ----------------------------------------------------
 const HOP_BY_HOP = new Set(['content-length', 'content-encoding', 'transfer-encoding', 'connection', 'keep-alive']);
 
-async function forwardAnthropicDirect(res, payload, bodyBuffer, url, headers, mappedModel, signal, profile) {
+// Bifrost: intact names, per model, the User-Agent prefix of the provider's own client (bifrost_ua).
+// When the caller is that client, the request crosses as it is: only the key changes.
+const bifrostUACache = new Map();
+async function bifrostUAFor(profile, model) {
+  const base = String(profile.baseURL || '').replace(/\/+$/, '');
+  if (!base || !model) return '';
+  const key = `${base}\n${model}`;
+  const hit = bifrostUACache.get(key);
+  if (hit && hit.until > Date.now()) return hit.ua;
+  let ua = '';
+  let ttl = 10 * 60 * 1000;
+  try {
+    const r = await fetch(`${base}/models/${model.split('/').map(encodeURIComponent).join('/')}`, {
+      headers: { authorization: `Bearer ${profile.apiKey || ''}` }, signal: AbortSignal.timeout(3000)
+    });
+    if (r.ok) ua = String((await r.json())?.bifrost_ua || '');
+  } catch {
+    ttl = 30 * 1000; // an unreachable list must not pin the decision for long
+  }
+  bifrostUACache.set(key, { ua, until: Date.now() + ttl });
+  return ua;
+}
+
+async function crossesBifrost(req, profile, model) {
+  const clientUA = String(req.headers['user-agent'] || '');
+  if (!clientUA) return false;
+  const ua = await bifrostUAFor(profile, model);
+  return Boolean(ua) && clientUA.startsWith(ua);
+}
+
+// Every client header except its own credentials, the switcher's control headers and hop-by-hop.
+function bifrostHeaders(req, profile) {
+  const headers = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    const lk = k.toLowerCase();
+    if (BLOCKED_PASSTHROUGH.has(lk) || HOP_BY_HOP.has(lk) || lk === 'host' || lk === 'authorization' || lk === 'accept-encoding') continue;
+    headers[lk] = v;
+  }
+  headers['x-api-key'] = profile.apiKey || '';
+  return headers;
+}
+
+function withClientQuery(url, req) {
+  const q = String(req.url || '').indexOf('?');
+  return q < 0 ? url : url + (url.includes('?') ? '&' : '?') + req.url.slice(q + 1);
+}
+
+async function forwardAnthropicDirect(res, payload, bodyBuffer, url, headers, mappedModel, signal, profile, bifrost = false) {
   debugLog('Direct forward to native Anthropic endpoint:', url);
 
   // Only re-serialize when a fix is actually needed; otherwise forward the client's original bytes.
@@ -510,13 +557,13 @@ async function forwardAnthropicDirect(res, payload, bodyBuffer, url, headers, ma
     json = { ...json, model: mappedModel };
     modified = true;
   }
-  const healed = healAnthropicPayload(json);
+  const healed = bifrost ? { changed: false, notes: [] } : healAnthropicPayload(json);
   if (healed.changed) {
     json = healed.payload;
     modified = true;
     debugLog('Healer (direct):', healed.notes.join('; '));
   }
-  if (profile?.thinkingMode === 'off' && json.thinking) {
+  if (!bifrost && profile?.thinkingMode === 'off' && json.thinking) {
     json = { ...json };
     delete json.thinking;
     modified = true;
@@ -752,6 +799,25 @@ async function handleConvert(clientFormat, req, res, bodyBuffer, opts = {}) {
   let answered = false; // set only after a complete 2xx answer; the half upload depends on it
 
   try {
+    // Bifrost: the provider's own client reaching its own account through intact. Bytes and headers
+    // go as sent, only the key changes: no healer, no thinkingMode, no conversion.
+    if (clientFormat === 'anthropic' && await crossesBifrost(req, profile, mappedModel)) {
+      const { url } = upstreamEndpoint(profile, 'anthropic', mappedModel, ir.stream, req);
+      const headers = bifrostHeaders(req, profile);
+      if (traceId) headers['x-intact-trace'] = traceId;
+      try {
+        const r = await forwardAnthropicDirect(res, payload, bodyBuffer, withClientQuery(url, req), headers, mappedModel, ac.signal, profile, true);
+        answered = !r.error && r.status >= 200 && r.status < 300;
+        log({ outFormat: 'anthropic', status: r.status, tokens: r.tokens, responsePreview: '(bifrost)', error: r.error || undefined });
+      } catch (err) {
+        if (ac.signal.aborted) return log({ status: 499, error: 'client disconnected' });
+        console.error(`[${profileKey}] Bifrost forward error:`, err.message);
+        sendClientError(res, clientFormat, 502, `Bifrost forward error: ${err.message}`);
+        log({ status: 502, error: err.message });
+      }
+      return;
+    }
+
     // Fast path: anthropic in/out goes straight through, preserving original bytes (including thinking signatures).
     // Note: this branch skips the Healer Engine because it bypasses the IR.
     if (clientFormat === 'anthropic' && outFormat === 'anthropic') {
@@ -889,11 +955,14 @@ async function handleCountTokens(req, res, buf) {
   const { profile } = getActiveProfile('anthropic', req);
   if (profile) {
     const mappedModel = mapModel(payload.model || '', profile, 'anthropic');
-    if (resolveOutFormat(profile, mappedModel) === 'anthropic') {
-      const { url, headers } = upstreamEndpoint(profile, 'anthropic', mappedModel, false, req);
-      const countUrl = profile.endpoints?.countTokens || url.replace(/\/messages$/, '/messages/count_tokens');
+    const bifrost = await crossesBifrost(req, profile, mappedModel);
+    if (bifrost || resolveOutFormat(profile, mappedModel) === 'anthropic') {
+      const ep = upstreamEndpoint(profile, 'anthropic', mappedModel, false, req);
+      const headers = bifrost ? bifrostHeaders(req, profile) : ep.headers;
+      let countUrl = profile.endpoints?.countTokens || ep.url.replace(/\/messages$/, '/messages/count_tokens');
+      if (bifrost) countUrl = withClientQuery(countUrl, req);
       try {
-        const body = healAnthropicPayload({ ...payload, model: mappedModel }).payload;
+        const body = bifrost ? { ...payload, model: mappedModel } : healAnthropicPayload({ ...payload, model: mappedModel }).payload;
         const r = await fetch(countUrl, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(15000) });
         if (r.ok) {
           const j = await r.json();

package/service.mjs

@@ -5,7 +5,7 @@ import path from 'node:path';
 
 // A service does not inherit the installing shell. Without these it would read another config.json
 // or clean another settings.json than the shell that installed it.
-const SERVICE_ENV_KEYS = ['CLAUDE_CONFIG_DIR', 'LLM_SWITCHER_CONFIG', 'LLM_SWITCHER_STATE_DIR', 'LLM_SWITCHER_BLINDFOLD_CERTS'];
+const SERVICE_ENV_KEYS = ['LLM_SWITCHER_HOME', 'CLAUDE_CONFIG_DIR', 'LLM_SWITCHER_CONFIG', 'LLM_SWITCHER_STATE_DIR', 'LLM_SWITCHER_BLINDFOLD_CERTS'];
 
 export function serviceEnv(env = process.env) {
   return SERVICE_ENV_KEYS.filter(k => env[k]).map(k => [k, env[k]]);

package/shim.mjs

@@ -36,15 +36,18 @@ export const SHIM_DIR = path.join(os.homedir(), '.llm-switcher', 'bin');
 // `node -e`, so neither cmd.exe quoting nor URL encoding can corrupt it: pathToFileURL turns a
 // space in the checkout into %20, which cmd.exe then reads as the (undefined) argument %2.
 const STATE_HELPER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'ensure-ca-bundle.mjs');
+const ROUTE_NOTIFIER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'notify-route.ps1');
 
 // CLIs to wrap. `claude` is the most important case (--resume), codex included for completeness.
 export const SHIMMED = ['claude', 'codex'];
 
 // One tool, one env file. Sourcing the shared one is how one tool used to capture the other.
 const envFileOf = (name) => (name === 'codex' ? 'env-codex.sh' : 'env-claude.sh');
+const routeFileOf = (name) => (name === 'codex' ? 'route-codex.txt' : 'route-claude.txt');
 
 const POSIX_TEMPLATE = (name) => {
   const envFile = envFileOf(name);
+  const routeFile = routeFileOf(name);
   const caBlock = name === 'codex' ? '' : `
 # R2: one bundle holds the user's own CA and the switcher CA, so trusting the interceptor never
 # costs a certificate the user already had. Decided here, at launch, because only now is it known
@@ -85,6 +88,13 @@ else
   TOOL_ACTIVE=0
 fi
 
+# Nothing on screen tells the person that the switcher took this tool's traffic, so say it once,
+# here. Only while THIS tool is routed: an empty route file means the tool is off, so the tool
+# reaches its official endpoint and there is nothing to warn about.
+if [ "$TOOL_ACTIVE" = "1" ] && [ -s "$SWITCHER_DIR/${routeFile}" ]; then
+  printf '[llm-switcher] %s\\n' "$(cat "$SWITCHER_DIR/${routeFile}")" >&2
+fi
+
 # R8: a variable is removed ONLY when its value is one an older switcher wrote. The user's own
 # proxy, base URL, model or LLM_SWITCHER_* setting is theirs and is kept.
 GW_PORT="$( { [ -O "$SWITCHER_DIR/gateway.port" ] && tr -d '[:space:]' < "$SWITCHER_DIR/gateway.port"; } 2>/dev/null )"
@@ -167,6 +177,7 @@ exec "$REAL" "$@"
 
 const WINDOWS_TEMPLATE = (name) => {
   const envFile = envFileOf(name).replace(/\.sh$/, '.cmd');
+  const routeFile = routeFileOf(name);
   const caBlock = name === 'codex' ? '' : `
 REM R2: one bundle holds the user's own CA and the switcher CA, so trusting the interceptor
 REM never costs a certificate the user already had. Decided here, at launch, because only now
@@ -202,6 +213,11 @@ if exist "%SWITCHER_DIR%\\active.flag" if exist "%SWITCHER_DIR%\\${envFile}" (
 )
 if "%TOOL_ACTIVE%"=="1" call "%SWITCHER_DIR%\\${envFile}"
 
+REM Nothing on screen tells the person that the switcher took this tool's traffic, and both TUIs
+REM can claim the whole screen, so a printed line would be hidden. A toast is not. It is detached:
+REM the tool never waits for it. Only while THIS tool is routed (%TOOL_ACTIVE%).
+if "%TOOL_ACTIVE%"=="1" if exist "%SWITCHER_DIR%\\${routeFile}" start "" /b powershell -NoProfile -ExecutionPolicy Bypass -File "${ROUTE_NOTIFIER}" "%SWITCHER_DIR%\\${routeFile}" >nul 2>&1
+
 REM R8: a variable is removed ONLY when its value is one an older switcher wrote. The user's own
 REM proxy, base URL, model or LLM_SWITCHER_* setting is theirs and is kept.
 set "_GWPORT="
@@ -359,10 +375,13 @@ export function shimStatus(names = SHIMMED) {
 /** Line to add to the shell rc so the shim comes before the real binary. */
 // Windows: setx truncates at 1024 characters and would copy the merged system+user PATH into the
 // user key, and PowerShell does not expand %PATH%. Prepend to the User-scope Path only.
-export function pathExportLine(platform = process.platform) {
+export function pathExportLine(platform = process.platform, shell = currentShell()) {
   if (platform === 'win32') {
     return `powershell -NoProfile -Command "[Environment]::SetEnvironmentVariable('Path', '${SHIM_DIR};' + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')"`;
   }
+  // fish has no `export`, and it prepends through the fish_user_paths universal variable.
+  // `-m` moves the directory to the front when it is on the path already.
+  if (shell === 'fish') return `fish_add_path -m "${SHIM_DIR}"`;
   return `export PATH="${SHIM_DIR}:$PATH"`;
 }
 
@@ -370,12 +389,19 @@ export function pathExportLine(platform = process.platform) {
 export function suggestedRcFiles(platform = process.platform) {
   if (platform === 'win32') return [];
   const home = os.homedir();
-  const shell = path.basename(process.env.SHELL || '');
+  const shell = currentShell();
   if (shell === 'zsh') return [path.join(home, '.zshrc'), path.join(home, '.zprofile')];
   if (shell === 'bash') return [path.join(home, '.bashrc'), path.join(home, '.bash_profile')];
+  // fish reads neither .profile nor any POSIX rc file.
+  if (shell === 'fish') return [path.join(home, '.config', 'fish', 'config.fish')];
   return [path.join(home, '.profile')];
 }
 
+/** The basename of the login shell, which decides both the file to edit and the syntax of the line. */
+function currentShell() {
+  return path.basename(process.env.SHELL || '');
+}
+
 // The shim is on PATH but behind the real binary: a line that runs later prepends another directory
 // (npm-global, Homebrew). Login shells read the profile file, interactive shells the rc file.
 export function pathOrderHint(platform = process.platform) {

package/state.mjs

@@ -134,6 +134,10 @@ export const paths = {
   envClaudeSh: path.join(STATE_DIR, 'env-claude.sh'),
   envCodexCmd: path.join(STATE_DIR, 'env-codex.cmd'),
   envCodexSh: path.join(STATE_DIR, 'env-codex.sh'),
+  // One line per tool, written with that tool's env file: what the launcher shows the person at
+  // launch. Empty exactly when the tool is not routed, so the launcher needs no second condition.
+  routeClaude: path.join(STATE_DIR, 'route-claude.txt'),
+  routeCodex: path.join(STATE_DIR, 'route-codex.txt'),
   // The gateway port of the last switch on. The shim scrubs a stale loopback base URL
   // against it, so a shell opened before a port change still reaches the right gateway.
   gatewayPort: path.join(STATE_DIR, 'gateway.port'),
@@ -454,6 +458,11 @@ export function validateProfileInput(p) {
   return null;
 }
 
+/** True while a profile still carries the example config's placeholder baseURL or apiKey. */
+export function hasPlaceholder(p) {
+  return !p?.baseURL || /YOUR-|REPLACE-ME/i.test(`${p.baseURL} ${p.apiKey ?? ''}`);
+}
+
 export function needsMigration(cfg) {
   if (!cfg || typeof cfg !== 'object') return false;
   if (Object.hasOwn(cfg, 'activeProfile')) return true;
@@ -1227,8 +1236,9 @@ export function setTargetProfile(cfg, target, profileKey) {
   if (!profileAcceptsTarget(p, tool)) {
     return `Profile "${profileKey}" only accepts "${p.tool || p.inFormat}" input and cannot serve target "${tool}"`;
   }
+  // No legacy `activeProfile` here: needsMigration flags it, so every switch would re-run the
+  // migration on the next load and leave another config.json.bak-* holding the API keys.
   map[tool] = profileKey;
-  cfg.activeProfile = profileKey;
   return null;
 }
 
@@ -1240,7 +1250,6 @@ export function activateProfile(cfg, profileKey) {
   for (const t of TOOLS) {
     if (profileAcceptsTarget(p, t)) map[t] = profileKey;
   }
-  cfg.activeProfile = profileKey;
   return null;
 }
 
@@ -1300,6 +1309,16 @@ export function primaryModel(profile) {
   return '';
 }
 
+// What a person needs at launch: which profile took the traffic, the host it goes to, the model it
+// maps to, and whether the 1M window is on, because that changes what the session costs. Never the
+// API key: a desktop notification reads this line, and so can any shell.
+function routeLine(tool, key, profile) {
+  let host = '';
+  try { host = new URL(profile.baseURL).host; } catch { /* a profile may carry no address yet */ }
+  return [`${tool} -> ${key}`, host, primaryModel(profile), anyTier1M(profile) ? '1M' : '']
+    .filter(Boolean).join(' | ');
+}
+
 // Derive launcher state from activeProfiles (single source of truth).
 export function computeLaunchState(cfg, port) {
   const map = getActiveMap(cfg);
@@ -1310,7 +1329,15 @@ export function computeLaunchState(cfg, port) {
 
   // One interceptor serves both tools (R3) and its port lives at the top level of config.json
   // (R3b). The per-profile port went with the per-profile host and prefix.
-  const bfPort = parsePort(cfg?.blindfold?.port) || DEFAULT_BLINDFOLD_PORT;
+  // Precedence mirrors resolvePort for the gateway: the environment, then the file, then the
+  // default. Without the variable a second instance could not move the interceptor, and a gateway
+  // sent to 3457 by --port or by LLM_SWITCHER_PORT landed on the interceptor's own port.
+  let bfPort = parsePort(process.env.LLM_SWITCHER_BLINDFOLD_PORT)
+    || parsePort(cfg?.blindfold?.port)
+    || DEFAULT_BLINDFOLD_PORT;
+  if (bfPort === port) {
+    bfPort = port === DEFAULT_BLINDFOLD_PORT ? DEFAULT_BLINDFOLD_PORT + 1 : DEFAULT_BLINDFOLD_PORT;
+  }
   const interceptor = `http://127.0.0.1:${bfPort}`;
   const loopbackOnly = '127.0.0.1,localhost';
   const proxyPairs = () => [
@@ -1339,7 +1366,10 @@ export function computeLaunchState(cfg, port) {
     // no --config (F1, F3, F4). The shim of the tool may therefore never capture the traffic
     // of the other tool, and a restart cannot leave a stale override behind.
     envClaude: [],
-    envCodex: []
+    envCodex: [],
+    // The launcher notice, one line per tool. Empty for a tool that is not routed (A1).
+    routeClaude: claude ? routeLine('claude', map.claude, claude) : '',
+    routeCodex: codex ? routeLine('codex', map.codex, codex) : ''
   };
 
   // NODE_EXTRA_CA_CERTS is deliberately absent from env-claude: the shim decides it at launch,
@@ -1446,6 +1476,7 @@ export function emptyToolEnvFiles(tool) {
     const before = codex ? readOrEmpty(paths.envCodexSh) : '';
     writeAtomic(codex ? paths.envCodexCmd : paths.envClaudeCmd, '');
     writeAtomic(codex ? paths.envCodexSh : paths.envClaudeSh, '');
+    writeAtomic(codex ? paths.routeCodex : paths.routeClaude, '');
     return before !== '';
   });
   return { codexRouteChanged, codexDaemon: codexRouteChanged ? restartCodexDaemon([]) : undefined };
@@ -1513,6 +1544,10 @@ function writeLaunchState(cfg, port) {
   try {
     writeToolFiles(st.envClaude, paths.envClaudeSh, paths.envClaudeCmd);
     writeToolFiles(st.envCodex, paths.envCodexSh, paths.envCodexCmd);
+    writeAtomic(paths.routeClaude, st.routeClaude ? `${st.routeClaude}
+` : '');
+    writeAtomic(paths.routeCodex, st.routeCodex ? `${st.routeCodex}
+` : '');
     st.codexRouteChanged = readOrEmpty(paths.envCodexSh) !== codexBefore;
     // Recorded on switch on so a shell opened while the gateway ran can still recognize its own
     // stale loopback URL later, after the port changed (R8).
@@ -1537,7 +1572,8 @@ export function clearLaunchState(port) {
     // leave env.sh present and containing no export and no unset.
     writeAtomic(paths.envCmd, STUB_CMD);
     writeAtomic(paths.envSh, STUB_SH);
-    for (const f of [paths.envClaudeCmd, paths.envClaudeSh, paths.envCodexCmd, paths.envCodexSh]) {
+    for (const f of [paths.envClaudeCmd, paths.envClaudeSh, paths.envCodexCmd, paths.envCodexSh,
+      paths.routeClaude, paths.routeCodex]) {
       writeAtomic(f, '');
     }
     return codexBefore !== '';

package/switch.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawn, execFileSync } from 'node:child_process';
 import {
-  ROOT_DIR, STATE_DIR, TOOLS, configPath, claudeSettingsPath, paths, certCoversHost, loadConfig, getConfigLoadError, saveConfig,
+  ROOT_DIR, STATE_DIR, TOOLS, configPath, hasPlaceholder, claudeSettingsPath, paths, certCoversHost, loadConfig, getConfigLoadError, saveConfig,
   resolvePort, parsePort, findProfileKey, getActiveMap, setTargetProfile, activateProfile, deactivateAll,
   applyLaunchState, clearLaunchState, computeLaunchState,
   modelSlotsForProfile, modelForSlot, model1MForSlot, readAdminToken, adminTokenPath, openLog,
@@ -14,6 +14,7 @@ import {
   casClearToolPointers, emptyToolEnvFiles, syncInterceptorTools
 } from './state.mjs';
 import { runProbe, runCheck } from './contract.mjs';
+import { installPlugin, uninstallPlugin, pluginStatus, PLUGIN_NAME } from './plugin.mjs';
 import {
   SHIM_DIR, installShims, uninstallShims, shimStatus, pathExportLine, pathOrderHint,
   suggestedRcFiles, auditRunningProcesses
@@ -391,6 +392,10 @@ async function turnOn(profileName, cliTarget) {
 
   // Plan on a copy. Nothing is written until every check below passes.
   let planned = planSwitch(config, key, cliTarget);
+  // The example config routes to YOUR-ROUTER-HOST; activating it silently makes every request fail.
+  if (hasPlaceholder(planned.profiles[key])) {
+    console.warn(`[WARN] Profile "${show(key)}" still has a placeholder baseURL/apiKey. Edit ${configPath} first, or requests will fail.`);
+  }
   console.log(`Activating profile: [${show(planned.profiles[key].name || key)}] (${show(key)})${cliTarget ? ` for ${cliTarget}` : ''} on port ${port}...`);
 
   const gatewayState = await probeGateway(port);
@@ -777,6 +782,47 @@ async function manageService(action) {
   console.log('Usage: switch service [install|uninstall]');
 }
 
+// The launch notice, as a hook inside each tool. Opt-in: the routing does not depend on it, and a
+// person who installs nothing still gets the toast from the shim.
+async function managePlugin(action = 'status') {
+  const act = (action || 'status').toLowerCase();
+
+  if (act === 'install' || act === 'on') {
+    const { CURRENT_VERSION } = await import('./version.mjs');
+    const { installed, failed, paths } = installPlugin({}, CURRENT_VERSION);
+    for (const tool of installed) console.log(`[OK] ${tool}: ${paths[tool]}`);
+    for (const f of failed) console.error(`[Error] ${f.tool}: ${f.reason}`);
+    if (installed.length) {
+      console.log('\nNeither settings.json nor config.toml was opened. Each tool reads a file of its own.');
+      console.log(`Claude Code loads it on the next session as ${PLUGIN_NAME}@skills-dir.`);
+      console.log('Codex asks you once to trust a new hook. Accept it, or the hook stays off.');
+      console.log('\nTo remove it:  switch plugin uninstall');
+    }
+    if (failed.length) process.exit(1);
+    return;
+  }
+
+  if (act === 'uninstall' || act === 'off' || act === 'remove') {
+    const { installed, failed, paths } = uninstallPlugin();
+    for (const tool of installed) console.log(`[OK] ${tool}: removed from ${paths[tool]}`);
+    for (const f of failed) console.error(`[Error] ${f.tool}: ${f.reason}`);
+    if (failed.length) process.exit(1);
+    return;
+  }
+
+  const st = pluginStatus();
+  console.log('=== Launch notice (hook inside each coding tool) ===\n');
+  console.log(`Claude Code: ${st.claude.installed ? `INSTALLED as ${st.claude.id}` : 'not installed'}`);
+  console.log(`             ${st.claude.path}`);
+  console.log(`Codex      : ${st.codex.installed ? 'INSTALLED' : 'not installed'}`);
+  console.log(`             ${st.codex.path}`);
+  if (!st.claude.installed || !st.codex.installed) {
+    console.log(`\nThe notice is optional. Without it the gateway still routes every request,`);
+    console.log(`and the shim still raises its own notice at launch.`);
+    console.log(`To add it:  switch plugin install`);
+  }
+}
+
 async function manageShim(action = 'status') {
   const act = (action || 'status').toLowerCase();
 
@@ -862,7 +908,7 @@ async function runDoctor() {
     if (!key) continue;
     const p = config.profiles[key];
     if (!p) warn(`[WARN] Target ${t} points to missing profile "${show(key)}".`);
-    else if (!p.baseURL || /YOUR-|REPLACE-ME/i.test(`${p.baseURL} ${p.apiKey}`)) warn(`[WARN] Profile "${show(key)}" (${t}) still has placeholder baseURL/apiKey.`);
+    else if (hasPlaceholder(p)) warn(`[WARN] Profile "${show(key)}" (${t}) still has placeholder baseURL/apiKey.`);
     if (p && t === 'codex') {
       const codexWarning = codexPublicModelsWarning(show(key), p);
       if (codexWarning) warn(`[WARN] ${codexWarning}`);
@@ -1109,6 +1155,8 @@ if (cmd === 'off' || cmd === 'stop') {
   await manageService(subArg.toLowerCase() || 'status');
 } else if (cmd === 'shim' || cmd === 'shims') {
   await manageShim(subArg.toLowerCase() || 'status');
+} else if (cmd === 'plugin' || cmd === 'plugins') {
+  await managePlugin(subArg.toLowerCase() || 'status');
 } else if (Object.hasOwn(TARGET_ALIASES, cmd)) {
   await turnOn(subArg, TARGET_ALIASES[cmd]);
 } else if (cmd === 'ui' || cmd === 'web' || cmd === 'gui') {
@@ -1141,6 +1189,9 @@ if (cmd === 'off' || cmd === 'stop') {
   console.log('  switch shim install            # Auto-inject env into resumed sessions (claude --resume)');
   console.log('  switch shim status             # Check shims + detect sessions bypassing the gateway');
   console.log('  switch shim uninstall          # Remove launcher shims');
+  console.log('  switch plugin install          # Optional launch notice inside Claude Code & Codex');
+  console.log('  switch plugin status           # Is that notice installed');
+  console.log('  switch plugin uninstall        # Remove that notice');
   console.log('  switch off [target]            # Restore official endpoints (all, or one target)');
   console.log('  switch models [--refresh]      # Show discovered models catalog for Claude Code & Codex');
   console.log('  switch contract-probe [--model m] # Drive the contract-lab variants through the gateway');

package/tests/blindfold.test.mjs

@@ -137,7 +137,7 @@ test('a compressed response body is decoded for the capture', () => {
   assert.equal(decodeBody(zlib.gzipSync(Buffer.from(sse)), 'GZIP'), sse, 'must be case-insensitive');
   assert.equal(decodeBody(zlib.brotliCompressSync(Buffer.from(sse)), 'br'), sse);
   assert.equal(decodeBody(zlib.deflateSync(Buffer.from(sse)), 'deflate'), sse);
-  assert.equal(decodeBody(zlib.zstdCompressSync(Buffer.from(sse)), 'zstd'), sse);
+  if (typeof zlib.zstdCompressSync === 'function') assert.equal(decodeBody(zlib.zstdCompressSync(Buffer.from(sse)), 'zstd'), sse);
 });
 
 test('an unencoded body is passed through untouched', () => {