llm-switcher 1.2.7 → 1.2.8

package/hook-status.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Reports the switcher route to a coding tool at the start of a session.
+//
+// The shim toast fires only when the shim runs, and that needs the shim directory first on PATH.
+// This runs inside the tool, so it reports even when the launcher is the person's own script. Claude
+// Code and Codex both read one JSON object from stdout and show `systemMessage` to the person.
+//
+// Two rules hold, whatever happens:
+//   - It prints exactly one JSON object and exits 0. A hook must never fail a session.
+//   - A tool with no profile gets an empty object. Silence for a tool on its official endpoint.
+//
+// Usage: node hook-status.mjs <claude|codex>
+import fs from 'node:fs';
+
+const TOOLS = ['claude', 'codex'];
+
+const readOrEmpty = (file) => {
+  try { return fs.readFileSync(file, 'utf8'); } catch { return ''; }
+};
+
+async function message(tool) {
+  if (!TOOLS.includes(tool)) return {};
+  // Imported here, not at the top: a failure to load the state module must still print an object.
+  const s = await import('./state.mjs');
+
+  // The route file is written with the env file of the same tool, so it is empty exactly when that
+  // tool is not routed. One read answers both "is the switcher on" and "is this tool on".
+  const route = readOrEmpty(tool === 'codex' ? s.paths.routeCodex : s.paths.routeClaude).trim();
+  if (!route || !fs.existsSync(s.paths.activeFlag)) return {};
+
+  const port = s.resolvePort([], s.loadConfig() || {});
+  const state = await s.probeGateway(port);
+  if (state === 'ours') {
+    return { systemMessage: `LLM Switcher is ON. ${route}. This tool does not reach its official endpoint.` };
+  }
+  // The dangerous state: the launch files route the tool, and nothing answers. The tool fails on
+  // its first request with a connection error that names no cause.
+  const held = state === 'free'
+    ? `the gateway on port ${port} does not answer`
+    : `port ${port} does not answer as this switcher (another program holds it)`;
+  return {
+    systemMessage: `WARNING: LLM Switcher is set to route this tool (${route}), but ${held}. `
+      + 'The tool cannot reach the provider. Run `switch on` to start the gateway, '
+      + 'or `switch off` to use the official endpoint.'
+  };
+}
+
+message(process.argv[2])
+  .then((out) => process.stdout.write(JSON.stringify(out)))
+  .catch(() => process.stdout.write('{}'))
+  .finally(() => process.exit(0));

package/notify-route.ps1

@@ -0,0 +1,46 @@
+# Raises one Windows toast that says the switcher took this tool's traffic.
+#
+# The launcher shim calls this detached, so it must never block and never fail loudly: a coding
+# tool must start even when the notification does not. It reads one argument, the route file of
+# the tool. An absent or empty file means the tool is not routed, and then nothing is shown.
+#
+# No module is installed. WinRT is used through the PowerShell application id, which exists on
+# every Windows 10 and 11 machine.
+param([Parameter(Mandatory = $true)][string]$RouteFile)
+
+$ErrorActionPreference = 'Stop'
+trap { exit 0 }
+
+if (-not (Test-Path -LiteralPath $RouteFile)) { exit 0 }
+$line = (Get-Content -LiteralPath $RouteFile -Raw -ErrorAction SilentlyContinue)
+if ($null -eq $line) { exit 0 }
+$line = $line.Trim()
+if ($line.Length -eq 0) { exit 0 }
+
+# The line is data, so it is escaped before it enters the toast XML.
+$body = [System.Security.SecurityElement]::Escape($line)
+
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom, ContentType = WindowsRuntime] | Out-Null
+
+$appId = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe'
+$xml = @"
+<toast activationType="protocol" launch="http://127.0.0.1:3456/ui">
+  <visual>
+    <binding template="ToastGeneric">
+      <text>LLM Switcher is ON</text>
+      <text>$body</text>
+      <text placement="attribution">This tool does not reach its official endpoint.</text>
+    </binding>
+  </visual>
+</toast>
+"@
+
+$doc = [Windows.Data.Xml.Dom.XmlDocument]::new()
+$doc.LoadXml($xml)
+$toast = [Windows.UI.Notifications.ToastNotification]::new($doc)
+# One tag per tool: a second launch of the same tool replaces its notice instead of stacking.
+$toast.Tag = 'llm-switcher-route'
+$toast.Group = 'llm-switcher'
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($appId).Show($toast)
+exit 0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "llm-switcher",
-  "version": "1.2.7",
-  "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code, Codex, OpenAI and Gemini clients",
+  "version": "1.2.8",
+  "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code and Codex, with OpenAI-compatible, Anthropic and Vertex upstreams",
   "keywords": [
     "llm",
     "gateway",

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/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/skills/llm-switcher/SKILL.md

@@ -1,93 +1,93 @@
----
-name: llm-switcher
-description: Mandatory guidance for AI coding agents and token compression tools (Headroom, RTK, Ponytail, Repomix). Enforces routing all LLM traffic through the local LLM Switcher edge gateway (http://127.0.0.1:3456) instead of directly calling provider endpoints.
----
-
-# LLM Switcher Edge Gateway Skill
-
-This skill governs how AI coding agents (Claude Code, Codex, Cursor, Windsurf, Opencode) and prompt optimization/compression tools (Headroom, RTK, Ponytail, Repomix) must interact with LLM providers on this workstation.
-
-## 1. The Core Directive
-
-> **ALL OUTBOUND LLM REQUESTS MUST ROUTE THROUGH LLM SWITCHER (`http://127.0.0.1:3456`).**
-> 
-> Never configure any tool, script, sub-agent, or token compression proxy to call external provider endpoints directly (such as `https://api.anthropic.com`, `https://api.openai.com`, or `https://generativelanguage.googleapis.com`).
->
-> If a token compression tool (Headroom, RTK, Ponytail) is used, it MUST be positioned as an **inner processing layer**, and its **upstream destination MUST be configured to point to LLM Switcher** at `http://127.0.0.1:3456`.
-
-```
-[Client CLI / Agent]
-         │
-         ▼
-[Token Compressor: RTK / Headroom / Ponytail]  <-- Inner Layer
-         │
-         ▼ (MANDATORY: Upstream MUST point to http://127.0.0.1:3456)
-[LLM Switcher Edge Gateway (:3456)]            <-- Outermost Gatekeeper
-         │
-         ▼ (Heals schemas, maps 1M context, extracts thinking, converts protocol)
-[Internet / intact (Recommended) / 9Router / Upstream LLM]
-```
-
-## 2. Why This is Mandatory
-
-Direct outbound calls from token compressors will break the developer environment for several reasons:
-
-1. **Schema Breakage & The Healer Engine:**
-   Token optimizers frequently prune conversation history to save tokens. In doing so, they often delete an `assistant` turn containing a `tool_use`, while leaving the subsequent `user` turn containing a `tool_result`.
-   - Anthropic and OpenAI APIs strictly reject this with `HTTP 400 (orphaned tool_use_id)`.
-   - **LLM Switcher** intercepts these malformed requests and runs its **Healer Engine**, automatically converting orphaned results into safe context text blocks and merging consecutive same-role turns so upstream providers accept the payload cleanly.
-2. **Thinking / Reasoning Protection:**
-   Many token compressors naively strip `thinking` parameters or reasoning budgets to reduce token count.
-   - When routed through LLM Switcher, the gateway detects reasoning models (such as `ag/claude-opus-4-6-thinking` or `ag/gemini-3.8-flash`) and **automatically restores thinking parameters**, ensuring the model retains its full reasoning capabilities.
-3. **Official Context Windows & Dynamic Model Discovery:**
-   Context windows follow the model you select without mutating permanent settings. The gateway auto-discovers official models from Anthropic and OpenAI, refreshing mappings on tool version upgrades (`switch models`).
-4. **Server Gateway Synergy (intact / 9Router):**
-   LLM Switcher pairs directly with server-side gateways like **intact** (strongly recommended for credential proxying, account pooling, and contract lab self-healing) or 9Router, handling retries and quotas far better than any local tool.
-
-## 3. Configuring Token Compression Tools
-
-When setting up or assisting the user with token compression tools, apply these exact configurations:
-
-### A. Headroom (Prompt Compression Proxy)
-When configuring Headroom's upstream endpoint:
-- In Headroom config (`headroom.yaml` or environment variables):
-  ```bash
-  ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
-  OPENAI_BASE_URL="http://127.0.0.1:3456/v1"
-  ```
-- Point your CLI to Headroom's listening port (e.g. `http://127.0.0.1:8787`). Headroom compresses the prompt and forwards it to LLM Switcher on port `3456`.
-
-### B. RTK (Rust Token Killer / Repomix)
-- In RTK configuration or execution flags:
-  ```bash
-  # Ensure RTK's target upstream proxy is LLM Switcher
-  export UPSTREAM_URL="http://127.0.0.1:3456"
-  ```
-
-### C. Ponytail / Custom Proxies
-- Always set the proxy's upstream host to:
-  `http://127.0.0.1:3456` (or `http://127.0.0.1:3456/v1` for OpenAI-compatible tools).
-
-### D. Sub-Agents & Spawned Terminal Commands
-When an agent spawns sub-processes that call LLM CLIs:
-- **Never advise sourcing `env.sh` or `env.cmd`.** Those files carry no proxy variables any
-  more, so sourcing one changes nothing — and a stale variable an older version once wrote
-  would still point the tool at a port where nothing listens.
-- Run `switch claude <profile>` or `switch codex <profile>` instead. The shims in
-  `~/.llm-switcher/bin` inject the proxy variables into the tool process itself and clear
-  anything stale first.
-- `claude` and `codex` on `PATH` already are those shims: invoke them normally, and never
-  wrap them in another script.
-
-## 4. Operational Rules for AI Agents
-
-1. **NEVER edit `~/.claude/settings.json` directly.**
-   LLM Switcher uses zero-mutation launcher flags (`active.flag`). Writing custom base URLs or auth tokens into `settings.json` triggers warning banners in Claude Code and risks breaking the user's official subscription. Use `switch` CLI commands instead.
-2. **Check Gateway Health Before Complex Operations:**
-   Run `switch status` or call the `switcher_audit` MCP tool to confirm:
-   - LLM Switcher is active on port `3456`.
-   - The active profile matches the intended CLI target (Claude Code, Codex, or OpenAI).
-3. **Verify Routing When Errors Occur:**
-   If a tool fails with `HTTP 400`, `HTTP 502`, or connection errors:
-   - Run `switch doctor` to audit port collisions and environment variables.
-   - Inspect recent request logs via `http://127.0.0.1:3456/ui` (Tab 4: Live Inspector) to see if an intermediary tool mangled the payload.
+---
+name: llm-switcher
+description: Mandatory guidance for AI coding agents and token compression tools (Headroom, RTK, Ponytail, Repomix). Enforces routing all LLM traffic through the local LLM Switcher edge gateway (http://127.0.0.1:3456) instead of directly calling provider endpoints.
+---
+
+# LLM Switcher Edge Gateway Skill
+
+This skill governs how AI coding agents (Claude Code, Codex, Cursor, Windsurf, Opencode) and prompt optimization/compression tools (Headroom, RTK, Ponytail, Repomix) must interact with LLM providers on this workstation.
+
+## 1. The Core Directive
+
+> **ALL OUTBOUND LLM REQUESTS MUST ROUTE THROUGH LLM SWITCHER (`http://127.0.0.1:3456`).**
+> 
+> Never configure any tool, script, sub-agent, or token compression proxy to call external provider endpoints directly (such as `https://api.anthropic.com`, `https://api.openai.com`, or `https://generativelanguage.googleapis.com`).
+>
+> If a token compression tool (Headroom, RTK, Ponytail) is used, it MUST be positioned as an **inner processing layer**, and its **upstream destination MUST be configured to point to LLM Switcher** at `http://127.0.0.1:3456`.
+
+```
+[Client CLI / Agent]
+         │
+         ▼
+[Token Compressor: RTK / Headroom / Ponytail]  <-- Inner Layer
+         │
+         ▼ (MANDATORY: Upstream MUST point to http://127.0.0.1:3456)
+[LLM Switcher Edge Gateway (:3456)]            <-- Outermost Gatekeeper
+         │
+         ▼ (Heals schemas, maps 1M context, extracts thinking, converts protocol)
+[Internet / intact (Recommended) / 9Router / Upstream LLM]
+```
+
+## 2. Why This is Mandatory
+
+Direct outbound calls from token compressors will break the developer environment for several reasons:
+
+1. **Schema Breakage & The Healer Engine:**
+   Token optimizers frequently prune conversation history to save tokens. In doing so, they often delete an `assistant` turn containing a `tool_use`, while leaving the subsequent `user` turn containing a `tool_result`.
+   - Anthropic and OpenAI APIs strictly reject this with `HTTP 400 (orphaned tool_use_id)`.
+   - **LLM Switcher** intercepts these malformed requests and runs its **Healer Engine**, automatically converting orphaned results into safe context text blocks and merging consecutive same-role turns so upstream providers accept the payload cleanly.
+2. **Thinking / Reasoning Protection:**
+   Many token compressors naively strip `thinking` parameters or reasoning budgets to reduce token count.
+   - When routed through LLM Switcher, the gateway detects reasoning models (such as `ag/claude-opus-4-6-thinking` or `ag/gemini-3.8-flash`) and **automatically restores thinking parameters**, ensuring the model retains its full reasoning capabilities.
+3. **Official Context Windows & Dynamic Model Discovery:**
+   Context windows follow the model you select without mutating permanent settings. The gateway auto-discovers official models from Anthropic and OpenAI, refreshing mappings on tool version upgrades (`switch models`).
+4. **Server Gateway Synergy (intact / 9Router):**
+   LLM Switcher pairs directly with server-side gateways like **intact** (strongly recommended for credential proxying, account pooling, and contract lab self-healing) or 9Router, handling retries and quotas far better than any local tool.
+
+## 3. Configuring Token Compression Tools
+
+When setting up or assisting the user with token compression tools, apply these exact configurations:
+
+### A. Headroom (Prompt Compression Proxy)
+When configuring Headroom's upstream endpoint:
+- In Headroom config (`headroom.yaml` or environment variables):
+  ```bash
+  ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
+  OPENAI_BASE_URL="http://127.0.0.1:3456/v1"
+  ```
+- Point your CLI to Headroom's listening port (e.g. `http://127.0.0.1:8787`). Headroom compresses the prompt and forwards it to LLM Switcher on port `3456`.
+
+### B. RTK (Rust Token Killer / Repomix)
+- In RTK configuration or execution flags:
+  ```bash
+  # Ensure RTK's target upstream proxy is LLM Switcher
+  export UPSTREAM_URL="http://127.0.0.1:3456"
+  ```
+
+### C. Ponytail / Custom Proxies
+- Always set the proxy's upstream host to:
+  `http://127.0.0.1:3456` (or `http://127.0.0.1:3456/v1` for OpenAI-compatible tools).
+
+### D. Sub-Agents & Spawned Terminal Commands
+When an agent spawns sub-processes that call LLM CLIs:
+- **Never advise sourcing `env.sh` or `env.cmd`.** Those files carry no proxy variables any
+  more, so sourcing one changes nothing — and a stale variable an older version once wrote
+  would still point the tool at a port where nothing listens.
+- Run `switch claude <profile>` or `switch codex <profile>` instead. The shims in
+  `~/.llm-switcher/bin` inject the proxy variables into the tool process itself and clear
+  anything stale first.
+- `claude` and `codex` on `PATH` already are those shims: invoke them normally, and never
+  wrap them in another script.
+
+## 4. Operational Rules for AI Agents
+
+1. **NEVER edit `~/.claude/settings.json` directly.**
+   LLM Switcher uses zero-mutation launcher flags (`active.flag`). Writing custom base URLs or auth tokens into `settings.json` triggers warning banners in Claude Code and risks breaking the user's official subscription. Use `switch` CLI commands instead.
+2. **Check Gateway Health Before Complex Operations:**
+   Run `switch status` or call the `switcher_audit` MCP tool to confirm:
+   - LLM Switcher is active on port `3456`.
+   - The active profile matches the intended CLI target (Claude Code, Codex, or OpenAI).
+3. **Verify Routing When Errors Occur:**
+   If a tool fails with `HTTP 400`, `HTTP 502`, or connection errors:
+   - Run `switch doctor` to audit port collisions and environment variables.
+   - Inspect recent request logs via `http://127.0.0.1:3456/ui` (Tab 4: Live Inspector) to see if an intermediary tool mangled the payload.