free-coding-models 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ---
 
+## 0.3.3
+
+### Fixed
+- **Claude Code now uses the real `free-claude-code` proxy contract**: FCM stopped injecting proxy slugs into `claude --model` / `ANTHROPIC_MODEL` and now launches Claude Code with only `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`.
+- **Claude routing is now proxy-side `MODEL` / `MODEL_*` mapping**: The selected FCM model is persisted into the proxy's Anthropic routing config and hot-reloaded by the daemon, so fake Claude model ids resolve to the chosen free backend exactly like `free-claude-code`.
+- **Claude launch now forces a real Claude alias**: FCM starts Claude Code with `--model sonnet`, which overrides stale broken local selections like `gpt-oss-120b` that Claude rejects before the proxy is even contacted.
+- **Claude proxy sync leftovers were removed**: Claude Code is no longer treated as a persisted proxy-sync target, avoiding stale `ANTHROPIC_MODEL=<fcm-slug>` env files that broke the integration.
+
+### Added
+- **Terminal width warning progress bar and toggle**: Added visual progress bar to the terminal width warning overlay and a Settings toggle “Disable Widths Warning” to permanently suppress it.
+- **Config setting `disableWidthsWarning`**: New boolean setting stored in profile and global config, default false.
+
 ## 0.3.2
 
 ### Fixed

package/README.md

@@ -182,12 +182,13 @@ bunx free-coding-models YOUR_API_KEY
 
 ### 🆕 What's New
 
-**Version 0.3.2 hardens the Claude Code proxy path to match the routing strategy that works in `free-claude-code`:**
+**Version 0.3.3 switches Claude Code to the exact `free-claude-code` pattern instead of injecting FCM slugs into Claude itself:**
 
-- **Claude Code family-model routing is now proxy-side** — FCM remaps Claude's internal family ids such as `claude-3-5-sonnet-*`, `claude-3-haiku-*`, `claude-3-opus-*`, `sonnet`, `haiku`, and `default` back to the selected FCM proxy model.
-- **Claude Code helper model slots are pinned** — FCM now exports the selected model into `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, and `CLAUDE_CODE_SUBAGENT_MODEL` so background/helper requests stop drifting.
-- **Claude proxy auth now carries the selected model hint** — The launcher encodes the chosen proxy model into `ANTHROPIC_AUTH_TOKEN`, giving the proxy a reliable fallback even when Claude Code ignores the visible `/model` selection.
-- **Proxy support remains beta** — External-tool proxy support is still stabilizing, but Claude Code should now behave much closer to the working `free-claude-code` setup.
+- **Claude Code is proxy-only now** — FCM no longer tries to make Claude Code “select” `gpt-oss-120b` or any other free model directly. Claude still speaks in Claude model ids, and the proxy picks the real backend.
+- **Proxy-side `MODEL` / `MODEL_OPUS` / `MODEL_SONNET` / `MODEL_HAIKU` routing now drives Claude** — When you launch Claude Code from a selected FCM row, FCM writes the selected proxy slug into the proxy's Anthropic routing config, exactly like `free-claude-code`, then lets the daemon hot-reload it.
+- **Claude no longer gets `--model <fcm-slug>` or `ANTHROPIC_MODEL=<fcm-slug>`** — the launcher now passes only `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`, which is the same clean client-side contract used by `free-claude-code`.
+- **Claude is now forced onto a real Claude alias at launch** — FCM starts Claude Code with `--model sonnet`, so stale local values like `gpt-oss-120b` cannot fail client-side before the proxy even receives the request.
+- **Claude sync/install leftovers were removed from the proxy path** — Claude Code is no longer treated like a persisted-config target for proxy sync; its integration is runtime-only, with fake Claude ids resolved by the proxy.
 
 ---
 
@@ -686,7 +687,7 @@ Press **Z** to cycle through all 13 tool modes in the TUI, or use flags to start
 
 Proxy-backed external tool support is still beta. Expect occasional launch/auth rough edges while third-party CLI contracts are still settling.
 
-`Codex` is launched through an explicit custom provider config so it stays in API-key mode through the proxy. `Gemini` proxy launches are version-gated: older builds like `0.33.0` are blocked with a clear diagnostic instead of being misconfigured silently.
+`Claude Code` is launched with a real Claude alias (`--model sonnet`) while the proxy maps that fake Claude family back to your selected FCM backend, which avoids stale local `gpt-oss-*` selections breaking before the proxy is hit. `Codex` is launched through an explicit custom provider config so it stays in API-key mode through the proxy. `Gemini` proxy launches are version-gated: older builds like `0.33.0` are blocked with a clear diagnostic instead of being misconfigured silently.
 
 The **Install Endpoints** flow (`Y` key) now targets only the tools with a stable persisted config contract. `Claude Code`, `Codex`, and `Gemini` stay launcher-only and should be started directly from FCM.
 

package/bin/fcm-proxy-daemon.js

@@ -88,7 +88,7 @@ async function main() {
   const { sources } = await import('../sources.js')
 
   // 📖 Load config and build initial topology — wrapped in try/catch to provide clear error on startup failures
-  let fcmConfig, proxySettings, mergedModels, accounts, proxyModels
+  let fcmConfig, proxySettings, mergedModels, accounts, proxyModels, anthropicRouting
   try {
     fcmConfig = loadConfig()
     proxySettings = getProxySettings(fcmConfig)
@@ -113,6 +113,7 @@ async function main() {
     const topology = buildProxyTopologyFromConfig(fcmConfig, mergedModels, sources)
     accounts = topology.accounts
     proxyModels = topology.proxyModels
+    anthropicRouting = topology.anthropicRouting
   } catch (err) {
     logError(`Fatal: Failed to build initial topology: ${err.message}`)
     process.exit(1)
@@ -130,6 +131,7 @@ async function main() {
     port,
     accounts,
     proxyApiKey: token,
+    anthropicRouting,
   })
 
   try {
@@ -175,9 +177,10 @@ async function main() {
             return
           }
 
-          proxy.updateAccounts(newTopology.accounts)
+          proxy.updateAccounts(newTopology.accounts, newTopology.anthropicRouting)
           accounts = newTopology.accounts
           proxyModels = newTopology.proxyModels
+          anthropicRouting = newTopology.anthropicRouting
 
           // 📖 Update status file
           writeDaemonStatus({

package/bin/free-coding-models.js

@@ -484,11 +484,12 @@ async function main() {
     mode,                         // 📖 'opencode' or 'openclaw' — controls Enter action
     tierFilterMode: 0,            // 📖 Index into TIER_CYCLE (0=All, 1=S+, 2=S, ...)
     originFilterMode: 0,          // 📖 Index into ORIGIN_CYCLE (0=All, then providers)
-    hideUnconfiguredModels: startupProfileSettings?.hideUnconfiguredModels === true || config.settings?.hideUnconfiguredModels === true, // 📖 Hide providers with no configured API key when true.
-    scrollOffset: 0,              // 📖 First visible model index in viewport
-    terminalRows: process.stdout.rows || 24,  // 📖 Current terminal height
-    terminalCols: process.stdout.columns || 80, // 📖 Current terminal width
-    widthWarningStartedAt: (process.stdout.columns || 80) < 166 ? now : null, // 📖 Start the narrow-terminal countdown immediately when booting in a small viewport.
+hideUnconfiguredModels: startupProfileSettings?.hideUnconfiguredModels === true || config.settings?.hideUnconfiguredModels === true, // 📖 Hide providers with no configured API key when true.
+      disableWidthsWarning: config.settings?.disableWidthsWarning ?? false, // 📖 Disable widths warning toggle (default off)
+      scrollOffset: 0,              // 📖 First visible model index in viewport
+      terminalRows: process.stdout.rows || 24,  // 📖 Current terminal height
+      terminalCols: process.stdout.columns || 80, // 📖 Current terminal width
+      widthWarningStartedAt: (process.stdout.columns || 80) < 166 ? now : null, // 📖 Start the narrow-terminal countdown immediately when booting in a small viewport.
     widthWarningDismissed: false, // 📖 Esc hides the narrow-terminal warning early for the current narrow-width session.
     widthWarningShowCount: 0, // 📖 Counter for how many times the narrow-terminal warning has been shown (max 2 per session).
     // 📖 Settings screen state (P key opens it)
@@ -575,7 +576,7 @@ async function main() {
     const prevCols = state.terminalCols
     state.terminalRows = process.stdout.rows || 24
     state.terminalCols = process.stdout.columns || 80
-    if (state.terminalCols < 166) {
+    if (state.terminalCols < 166 && !state.disableWidthsWarning) {
       if (prevCols >= 166 || state.widthWarningDismissed) {
         state.widthWarningStartedAt = Date.now()
         state.widthWarningDismissed = false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",

package/src/config.js

@@ -100,12 +100,13 @@
  *   → setActiveProfile(config, name) — Set which profile is active (null to clear)
  *   → _emptyProfileSettings() — Default TUI settings for a profile
  *   → getProxySettings(config) — Return normalized proxy settings from config
+ *   → setClaudeProxyModelRouting(config, modelId) — Mirror free-claude-code MODEL/MODEL_* routing onto one selected FCM model
  *   → normalizeEndpointInstalls(endpointInstalls) — Keep tracked endpoint installs stable across app versions
  *
  * @exports loadConfig, saveConfig, validateConfigFile, getApiKey, isProviderEnabled
  * @exports addApiKey, removeApiKey, listApiKeys — multi-key management helpers
  * @exports saveAsProfile, loadProfile, listProfiles, deleteProfile
- * @exports getActiveProfileName, setActiveProfile, getProxySettings, normalizeEndpointInstalls
+ * @exports getActiveProfileName, setActiveProfile, getProxySettings, setClaudeProxyModelRouting, normalizeEndpointInstalls
  * @exports CONFIG_PATH — path to the JSON config file
  *
  * @see bin/free-coding-models.js — main CLI that uses these functions
@@ -645,6 +646,24 @@ export function _emptyProfileSettings() {
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
     preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
     proxy: normalizeProxySettings(),
+    disableWidthsWarning: false, // 📖 Disable widths warning (default off)
+  }
+}
+
+function normalizeAnthropicRouting(anthropicRouting = null) {
+  const normalizeModelId = (value) => {
+    if (typeof value !== 'string') return null
+    const trimmed = value.trim().replace(/^fcm-proxy\//, '')
+    return trimmed || null
+  }
+
+  return {
+    // 📖 Mirror free-claude-code naming: MODEL is the fallback, and MODEL_* are
+    // 📖 Claude-family overrides. FCM currently pins all four to one selected model.
+    model: normalizeModelId(anthropicRouting?.model),
+    modelOpus: normalizeModelId(anthropicRouting?.modelOpus),
+    modelSonnet: normalizeModelId(anthropicRouting?.modelSonnet),
+    modelHaiku: normalizeModelId(anthropicRouting?.modelHaiku),
   }
 }
 
@@ -658,7 +677,7 @@ export function _emptyProfileSettings() {
  * 📖 daemonConsent — ISO timestamp of when user consented to daemon install, or null.
  *
  * @param {object|undefined|null} proxy
- * @returns {{ enabled: boolean, syncToOpenCode: boolean, preferredPort: number, stableToken: string, daemonEnabled: boolean, daemonConsent: string|null }}
+ * @returns {{ enabled: boolean, syncToOpenCode: boolean, preferredPort: number, stableToken: string, daemonEnabled: boolean, daemonConsent: string|null, anthropicRouting: { model: string|null, modelOpus: string|null, modelSonnet: string|null, modelHaiku: string|null } }}
  */
 export function normalizeProxySettings(proxy = null) {
   const preferredPort = Number.isInteger(proxy?.preferredPort) && proxy.preferredPort >= 0 && proxy.preferredPort <= 65535
@@ -679,6 +698,7 @@ export function normalizeProxySettings(proxy = null) {
     daemonConsent: (typeof proxy?.daemonConsent === 'string' && proxy.daemonConsent.length > 0)
       ? proxy.daemonConsent
       : null,
+    anthropicRouting: normalizeAnthropicRouting(proxy?.anthropicRouting),
     // 📖 activeTool — legacy field kept only for backward compatibility.
     // 📖 Runtime sync now follows the current Z-selected tool automatically.
     activeTool: (typeof proxy?.activeTool === 'string' && proxy.activeTool.length > 0)
@@ -698,6 +718,44 @@ export function getProxySettings(config) {
   return normalizeProxySettings(config?.settings?.proxy)
 }
 
+/**
+ * 📖 Persist the free-claude-code style MODEL / MODEL_OPUS / MODEL_SONNET /
+ * 📖 MODEL_HAIKU routing onto one selected proxy model. Claude Code itself then
+ * 📖 keeps speaking in fake Claude model ids while the proxy chooses the backend.
+ *
+ * @param {object} config
+ * @param {string} modelId
+ * @returns {boolean} true when the normalized proxy settings changed
+ */
+export function setClaudeProxyModelRouting(config, modelId) {
+  const normalizedModelId = typeof modelId === 'string' ? modelId.trim().replace(/^fcm-proxy\//, '') : ''
+  if (!normalizedModelId) return false
+
+  if (!config.settings || typeof config.settings !== 'object') config.settings = {}
+
+  const current = getProxySettings(config)
+  const nextAnthropicRouting = {
+    model: normalizedModelId,
+    modelOpus: normalizedModelId,
+    modelSonnet: normalizedModelId,
+    modelHaiku: normalizedModelId,
+  }
+
+  const changed = current.enabled !== true
+    || current.anthropicRouting.model !== nextAnthropicRouting.model
+    || current.anthropicRouting.modelOpus !== nextAnthropicRouting.modelOpus
+    || current.anthropicRouting.modelSonnet !== nextAnthropicRouting.modelSonnet
+    || current.anthropicRouting.modelHaiku !== nextAnthropicRouting.modelHaiku
+
+  config.settings.proxy = {
+    ...current,
+    enabled: true,
+    anthropicRouting: nextAnthropicRouting,
+  }
+
+  return changed
+}
+
 /**
  * 📖 normalizeEndpointInstalls keeps the endpoint-install tracking list safe to replay.
  *
@@ -852,6 +910,7 @@ function _emptyConfig() {
     settings: {
       hideUnconfiguredModels: true,
       proxy: normalizeProxySettings(),
+      disableWidthsWarning: false, // 📖 Disable widths warning toggle (default off)
     },
     // 📖 Pinned favorites rendered at top of the table ("providerKey/modelId").
     favorites: [],

package/src/endpoint-installer.js

@@ -531,11 +531,9 @@ function installIntoEnvBasedTool(providerKey, models, apiKey, toolMode, paths, c
       const proxyBase = effectiveBaseUrl.replace(/\/v1$/, '')
       envLines.push(`export ANTHROPIC_AUTH_TOKEN="${effectiveApiKey}"`)
       envLines.push(`export ANTHROPIC_BASE_URL="${proxyBase}"`)
-      envLines.push(`export ANTHROPIC_MODEL="${effectiveModelId}"`)
     } else {
       envLines.push(`export ANTHROPIC_AUTH_TOKEN="${effectiveApiKey}"`)
       envLines.push(`export ANTHROPIC_BASE_URL="${effectiveBaseUrl}"`)
-      envLines.push(`export ANTHROPIC_MODEL="${effectiveModelId}"`)
     }
   }
 

package/src/key-handler.js

@@ -959,13 +959,14 @@ export function createKeyHandler(ctx) {
     if (state.settingsOpen) {
       const proxySettings = getProxySettings(state.config)
       const providerKeys = Object.keys(sources)
-      const updateRowIdx = providerKeys.length
-      const proxyDaemonRowIdx = updateRowIdx + 1
-      const changelogViewRowIdx = updateRowIdx + 2
-      // 📖 Profile rows start after maintenance + proxy/daemon + changelog
-      const savedProfiles = listProfiles(state.config)
-      const profileStartIdx = updateRowIdx + 3
-      const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : changelogViewRowIdx
+const updateRowIdx = providerKeys.length
+       const widthWarningRowIdx = updateRowIdx + 1
+       const proxyDaemonRowIdx = widthWarningRowIdx + 1
+       const changelogViewRowIdx = proxyDaemonRowIdx + 1
+       // 📖 Profile rows start after maintenance + width warning + proxy/daemon + changelog
+       const savedProfiles = listProfiles(state.config)
+       const profileStartIdx = updateRowIdx + 5
+       const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : changelogViewRowIdx
 
       // 📖 Edit/Add-key mode: capture typed characters for the API key
       if (state.settingsEditMode || state.settingsAddKeyMode) {
@@ -1098,6 +1099,14 @@ export function createKeyHandler(ctx) {
           return
         }
 
+        // 📖 Widths Warning toggle (Enter to toggle)
+        if (state.settingsCursor === widthWarningRowIdx) {
+          if (!state.config.settings) state.config.settings = {}
+          state.config.settings.disableWidthsWarning = !state.config.settings.disableWidthsWarning
+          saveConfig(state.config)
+          return
+        }
+
         // 📖 Proxy & Daemon row: Enter → open dedicated overlay
         if (state.settingsCursor === proxyDaemonRowIdx) {
           state.settingsOpen = false
@@ -1161,7 +1170,15 @@ export function createKeyHandler(ctx) {
       }
 
       if (key.name === 'space') {
+        // 📖 Exclude certain rows from space toggle
         if (state.settingsCursor === updateRowIdx || state.settingsCursor === proxyDaemonRowIdx || state.settingsCursor === changelogViewRowIdx) return
+        // 📖 Widths Warning toggle (disable/enable)
+        if (state.settingsCursor === widthWarningRowIdx) {
+          if (!state.config.settings) state.config.settings = {}
+          state.config.settings.disableWidthsWarning = !state.config.settings.disableWidthsWarning
+          saveConfig(state.config)
+          return
+        }
         // 📖 Profile rows don't respond to Space
         if (state.settingsCursor >= profileStartIdx) return
 
@@ -1204,7 +1221,7 @@ export function createKeyHandler(ctx) {
           saveConfig(state.config)
           // 📖 Re-clamp cursor after deletion (profile list just got shorter)
           const newProfiles = listProfiles(state.config)
-          const newMaxRowIdx = newProfiles.length > 0 ? profileStartIdx + newProfiles.length - 1 : updateRowIdx
+          const newMaxRowIdx = newProfiles.length > 0 ? profileStartIdx + newProfiles.length - 1 : changelogViewRowIdx
           if (state.settingsCursor > newMaxRowIdx) {
             state.settingsCursor = Math.max(0, newMaxRowIdx)
           }
@@ -1715,7 +1732,7 @@ export function createKeyHandler(ctx) {
     // 📖 Shift+R is reserved for reset view settings
     const sortKeys = {
       'r': 'rank', 'o': 'origin', 'm': 'model',
-      'l': 'ping', 'a': 'avg', 's': 'swe', 'c': 'ctx', 'h': 'condition', 'v': 'verdict', 'b': 'stability', 'u': 'uptime', 'g': 'usage'
+      'l': 'ping', 'a': 'avg', 's': 'swe', 'c': 'ctx', 'h': 'condition', 'v': 'verdict', 'b': 'stability', 'u': 'uptime'
     }
 
     if (sortKeys[key.name] && !key.ctrl && !key.shift) {

package/src/opencode.js

@@ -575,25 +575,25 @@ export async function ensureProxyRunning(fcmConfig, { forceRestart = false } = {
     throw new Error('Proxy mode is disabled in Settings')
   }
 
-  // 📖 Phase 1: Check if background daemon is running — delegate instead of starting in-process
-  if (!forceRestart) {
-    try {
-      const daemonRunning = await isDaemonRunning()
-      if (daemonRunning) {
-        const info = getDaemonInfo()
-        if (info) {
-          return {
-            port: info.port,
-            accountCount: info.accountCount || 0,
-            proxyToken: info.token,
-            proxyModels: null,
-            availableModelSlugs: new Set(), // 📖 daemon handles model discovery
-            isDaemon: true,
-          }
+  // 📖 Always prefer the background daemon when it is available. Launcher code
+  // 📖 can update config and let the daemon hot-reload, which is closer to the
+  // 📖 free-claude-code model than spinning up tool-specific local proxies.
+  try {
+    const daemonRunning = await isDaemonRunning()
+    if (daemonRunning) {
+      const info = getDaemonInfo()
+      if (info) {
+        return {
+          port: info.port,
+          accountCount: info.accountCount || 0,
+          proxyToken: info.token,
+          proxyModels: null,
+          availableModelSlugs: new Set(), // 📖 daemon handles model discovery
+          isDaemon: true,
         }
       }
-    } catch { /* daemon check failed — fall through to in-process */ }
-  }
+    }
+  } catch { /* daemon check failed — fall through to in-process */ }
 
   if (forceRestart && activeProxy) {
     await cleanupProxy()
@@ -613,7 +613,7 @@ export async function ensureProxyRunning(fcmConfig, { forceRestart = false } = {
     }
   }
 
-  const { accounts, proxyModels } = buildProxyTopologyFromConfig(fcmConfig)
+  const { accounts, proxyModels, anthropicRouting } = buildProxyTopologyFromConfig(fcmConfig)
   if (accounts.length === 0) {
     throw new Error('No API keys found for proxy-capable models')
   }
@@ -622,7 +622,7 @@ export async function ensureProxyRunning(fcmConfig, { forceRestart = false } = {
   const proxySettings = getProxySettings(fcmConfig)
   const proxyToken = proxySettings.stableToken || `fcm_${randomUUID().replace(/-/g, '')}`
   const preferredPort = Number.isInteger(proxySettings.preferredPort) ? proxySettings.preferredPort : 0
-  const proxy = new ProxyServer({ port: preferredPort, accounts, proxyApiKey: proxyToken })
+  const proxy = new ProxyServer({ port: preferredPort, accounts, proxyApiKey: proxyToken, anthropicRouting })
   const { port } = await proxy.start()
   activeProxy = proxy
   setActiveProxy(activeProxy)

package/src/overlays.js

@@ -145,9 +145,10 @@ export function createOverlayRenderers(state, deps) {
   // 📖 Key "T" in settings = test API key for selected provider.
   function renderSettings() {
     const providerKeys = Object.keys(sources)
-    const updateRowIdx = providerKeys.length
-    const proxyDaemonRowIdx = updateRowIdx + 1
-    const changelogViewRowIdx = updateRowIdx + 2
+const updateRowIdx = providerKeys.length
+      const widthWarningRowIdx = updateRowIdx + 1
+      const proxyDaemonRowIdx = widthWarningRowIdx + 1
+      const changelogViewRowIdx = proxyDaemonRowIdx + 1
     const proxySettings = getProxySettings(state.config)
     const EL = '\x1b[K'
     const lines = []
@@ -274,6 +275,13 @@ export function createOverlayRenderers(state, deps) {
     const updateRow = `${updateBullet}${chalk.bold(updateActionLabel).padEnd(44)} ${updateStatus}`
     cursorLineByRow[updateRowIdx] = lines.length
     lines.push(updateCursor ? chalk.bgRgb(30, 30, 60)(updateRow) : updateRow)
+    // 📖 Widths Warning toggle row (disable widths warning)
+    const disableWidthsWarning = Boolean(state.config.settings?.disableWidthsWarning)
+    const widthWarningBullet = state.settingsCursor === widthWarningRowIdx ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+    const widthWarningStatus = disableWidthsWarning ? chalk.greenBright('DISABLED') : chalk.dim('enabled')
+    const widthWarningRow = `${widthWarningBullet}${chalk.bold('Disable Widths Warning').padEnd(44)} ${widthWarningStatus}`
+    cursorLineByRow[widthWarningRowIdx] = lines.length
+    lines.push(state.settingsCursor === widthWarningRowIdx ? chalk.bgRgb(30, 30, 60)(widthWarningRow) : widthWarningRow)
     if (updateState === 'error' && state.settingsUpdateError) {
       lines.push(chalk.red(`      ${state.settingsUpdateError}`))
     }
@@ -304,8 +312,8 @@ export function createOverlayRenderers(state, deps) {
 
     // 📖 Profiles section — list saved profiles with active indicator + delete support
     const savedProfiles = listProfiles(state.config)
-    const profileStartIdx = updateRowIdx + 3
-    const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : updateRowIdx
+const profileStartIdx = updateRowIdx + 5
+      const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : changelogViewRowIdx
 
     lines.push('')
     lines.push(`  ${chalk.bold('📋 Profiles')}  ${chalk.dim(savedProfiles.length > 0 ? `(${savedProfiles.length} saved)` : '(none — press Shift+S in main view to save)')}`)
@@ -612,8 +620,7 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${chalk.cyan('Used')}        Total prompt+completion tokens consumed in logs for this exact provider/model pair`)
     lines.push(`              ${chalk.dim('Loaded once at startup from request-log.jsonl. Displayed in K tokens, or M tokens above one million.')}`)
     lines.push('')
-    lines.push(`  ${chalk.cyan('Usage')}       Remaining quota for this exact provider when quota telemetry is exposed  ${chalk.dim('Sort:')} ${chalk.yellow('G')}`)
-    lines.push(`              ${chalk.dim('If a provider does not expose a trustworthy remaining %, the table shows a green dot instead of a fake number.')}`)
+
 
     lines.push('')
     lines.push(`  ${chalk.bold('Main TUI')}`)

package/src/proxy-server.js

@@ -115,6 +115,15 @@ function normalizeRequestedModel(modelId) {
   return trimmed.replace(/^fcm-proxy\//, '')
 }
 
+function normalizeAnthropicRouting(anthropicRouting = null) {
+  return {
+    model: normalizeRequestedModel(anthropicRouting?.model),
+    modelOpus: normalizeRequestedModel(anthropicRouting?.modelOpus),
+    modelSonnet: normalizeRequestedModel(anthropicRouting?.modelSonnet),
+    modelHaiku: normalizeRequestedModel(anthropicRouting?.modelHaiku),
+  }
+}
+
 function classifyClaudeVirtualModel(modelId) {
   const normalized = normalizeRequestedModel(modelId)
   if (!normalized) return null
@@ -135,6 +144,22 @@ function classifyClaudeVirtualModel(modelId) {
   return null
 }
 
+function resolveAnthropicMappedModel(modelId, anthropicRouting) {
+  const routing = normalizeAnthropicRouting(anthropicRouting)
+  const fallbackModel = routing.model
+  if (!fallbackModel && !routing.modelOpus && !routing.modelSonnet && !routing.modelHaiku) {
+    return null
+  }
+
+  const family = classifyClaudeVirtualModel(modelId)
+  if (family === 'opus') return routing.modelOpus || fallbackModel
+  if (family === 'sonnet') return routing.modelSonnet || fallbackModel
+  if (family === 'haiku') return routing.modelHaiku || fallbackModel
+
+  // 📖 free-claude-code falls back to MODEL for unknown Claude ids too.
+  return fallbackModel
+}
+
 function parseProxyAuthorizationHeader(authorization, expectedToken) {
   if (!expectedToken) return { authorized: true, modelHint: null }
   if (typeof authorization !== 'string' || !authorization.startsWith('Bearer ')) {
@@ -160,6 +185,7 @@ export class ProxyServer {
  *   accounts?: Array<{ id: string, providerKey: string, apiKey: string, modelId: string, url: string }>,
  *   retries?: number,
  *   proxyApiKey?: string,
+ *   anthropicRouting?: { model?: string|null, modelOpus?: string|null, modelSonnet?: string|null, modelHaiku?: string|null },
  *   accountManagerOpts?: object,
  *   tokenStatsOpts?: object,
  *   thinkingConfig?: { mode: string, budget_tokens?: number },
@@ -172,6 +198,7 @@ export class ProxyServer {
     accounts = [],
     retries = 3,
     proxyApiKey = null,
+    anthropicRouting = null,
     accountManagerOpts = {},
     tokenStatsOpts = {},
     thinkingConfig,
@@ -183,6 +210,7 @@ export class ProxyServer {
     this._thinkingConfig = thinkingConfig
     this._compressionOpts = compressionOpts
     this._proxyApiKey = proxyApiKey
+    this._anthropicRouting = normalizeAnthropicRouting(anthropicRouting)
     this._accounts = accounts
     this._upstreamTimeoutMs = upstreamTimeoutMs
     // 📖 Progressive backoff delays (ms) for retries — first attempt is immediate,
@@ -236,6 +264,7 @@ export class ProxyServer {
       port: this._listeningPort,
       accountCount: this._accounts.length,
       healthByAccount: this._accountManager.getAllHealth(),
+      anthropicRouting: this._anthropicRouting,
     }
   }
 
@@ -253,13 +282,17 @@ export class ProxyServer {
       return requestedModel
     }
 
+    const mappedModel = resolveAnthropicMappedModel(requestedModel, this._anthropicRouting)
+    if (mappedModel && this._accountManager.hasAccountsForModel(mappedModel)) {
+      return mappedModel
+    }
+
     // 📖 Claude Code still emits internal aliases / tier model ids for some
-    // 📖 background and helper paths. When the launcher encoded the selected
-    // 📖 proxy slug into the auth token, remap those virtual Claude ids here.
-    // 📖 This intentionally matches Claude families by substring so ids like
-    // 📖 `claude-3-5-sonnet-20241022` behave the same as `sonnet`.
+    // 📖 background and helper paths. Keep the old auth-token hint as a final
+    // 📖 compatibility fallback for already-launched sessions, but the primary
+    // 📖 routing path is now the free-claude-code style proxy-side mapping above.
     if (authModelHint && this._accountManager.hasAccountsForModel(authModelHint)) {
-      if (!requestedModel || classifyClaudeVirtualModel(requestedModel)) {
+      if (!requestedModel || classifyClaudeVirtualModel(requestedModel) || requestedModel.toLowerCase().startsWith('claude-')) {
         return authModelHint
       }
     }
@@ -783,6 +816,7 @@ export class ProxyServer {
         byModel: summary.byModel || {},
         recentRequests: summary.recentRequests || [],
       },
+      anthropicRouting: this._anthropicRouting,
       totals: {
         requests: totalRequests,
         tokens: totalTokens,
@@ -1390,9 +1424,11 @@ export class ProxyServer {
    * 📖 In-flight requests on old accounts will finish naturally.
    *
    * @param {Array} accounts — new account list
+   * @param {{ model?: string|null, modelOpus?: string|null, modelSonnet?: string|null, modelHaiku?: string|null }} anthropicRouting
    */
-  updateAccounts(accounts) {
+  updateAccounts(accounts, anthropicRouting = this._anthropicRouting) {
     this._accounts = accounts
+    this._anthropicRouting = normalizeAnthropicRouting(anthropicRouting)
     this._accountManager = new AccountManager(accounts, {})
   }
 }

package/src/proxy-sync.js

@@ -33,10 +33,12 @@ import { getToolMeta } from './tool-metadata.js'
 const PROXY_PROVIDER_ID = 'fcm-proxy'
 
 // 📖 Tools that support proxy sync (have base URL + API key config)
-// 📖 Gemini is excluded — it only stores a model name, no URL/key fields
+// 📖 Gemini is excluded — it only stores a model name, no URL/key fields.
+// 📖 Claude Code is excluded too: its free-claude-code style integration is
+// 📖 runtime-only now, with fake Claude ids handled by the proxy itself.
 export const PROXY_SYNCABLE_TOOLS = [
   'opencode', 'opencode-desktop', 'openclaw', 'crush', 'goose', 'pi',
-  'aider', 'amp', 'qwen', 'claude-code', 'codex', 'openhands',
+  'aider', 'amp', 'qwen', 'codex', 'openhands',
 ]
 
 const PROXY_SYNCABLE_CANONICAL = new Set(PROXY_SYNCABLE_TOOLS.map(tool => tool === 'opencode-desktop' ? 'opencode' : tool))
@@ -341,9 +343,8 @@ function syncEnvTool(proxyInfo, mergedModels, toolMode) {
   // 📖 Claude Code: Anthropic-specific env vars
   if (toolMode === 'claude-code') {
     const proxyBase = proxyInfo.baseUrl.replace(/\/v1$/, '')
-    envLines.push(`export ANTHROPIC_API_KEY="${proxyInfo.token}"`)
+    envLines.push(`export ANTHROPIC_AUTH_TOKEN="${proxyInfo.token}"`)
     envLines.push(`export ANTHROPIC_BASE_URL="${proxyBase}"`)
-    envLines.push(`export ANTHROPIC_MODEL="${primarySlug}"`)
   }
 
   ensureDirFor(envFilePath)

package/src/proxy-topology.js

@@ -9,7 +9,7 @@
  *    The proxy server uses these accounts for multi-key rotation and load balancing.
  *
  * @functions
- *   → buildProxyTopologyFromConfig(fcmConfig, mergedModels, sources) — build accounts + proxyModels
+ *   → buildProxyTopologyFromConfig(fcmConfig, mergedModels, sources) — build accounts + proxyModels + Anthropic family routing
  *   → buildMergedModelsForDaemon() — standalone helper to build merged models without TUI
  *
  * @exports buildProxyTopologyFromConfig, buildMergedModelsForDaemon
@@ -17,7 +17,7 @@
  * @see bin/fcm-proxy-daemon.js — standalone daemon that uses this directly
  */
 
-import { resolveApiKeys } from './config.js'
+import { resolveApiKeys, getProxySettings } from './config.js'
 import { resolveCloudflareUrl } from './ping.js'
 
 /**
@@ -29,7 +29,7 @@ import { resolveCloudflareUrl } from './ping.js'
  * @param {object} fcmConfig — live config from loadConfig()
  * @param {Array} mergedModels — output of buildMergedModels(MODELS)
  * @param {object} sourcesMap — the sources object keyed by providerKey
- * @returns {{ accounts: Array, proxyModels: Record<string, { name: string }> }}
+ * @returns {{ accounts: Array, proxyModels: Record<string, { name: string }>, anthropicRouting: { model: string|null, modelOpus: string|null, modelSonnet: string|null, modelHaiku: string|null } }}
  */
 export function buildProxyTopologyFromConfig(fcmConfig, mergedModels, sourcesMap) {
   const accounts = []
@@ -64,7 +64,12 @@ export function buildProxyTopologyFromConfig(fcmConfig, mergedModels, sourcesMap
     }
   }
 
-  return { accounts, proxyModels }
+  return {
+    accounts,
+    proxyModels,
+    // 📖 Mirror free-claude-code: proxy-side Claude family routing is config-driven.
+    anthropicRouting: getProxySettings(fcmConfig).anthropicRouting,
+  }
 }
 
 /**

package/src/render-table.js

@@ -93,7 +93,7 @@ export function setActiveProxy(proxyInstance) {
 }
 
 // ─── renderTable: mode param controls footer hint text (opencode vs openclaw) ─────────
-export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, widthWarningShowCount = 0, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false, startupLatestVersion = null, versionAlertsEnabled = true) {
+export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, widthWarningShowCount = 0, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false, startupLatestVersion = null, versionAlertsEnabled = true, disableWidthsWarning = false) {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
 
@@ -192,12 +192,12 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
   const W_STAB = 11
   const W_UPTIME = 6
   const W_TOKENS = 7
-  const W_USAGE = 7
+  // const W_USAGE = 7 // Usage column removed
   const MIN_TABLE_WIDTH = 166
   const warningDurationMs = 4_000
   const elapsed = widthWarningStartedAt ? Math.max(0, Date.now() - widthWarningStartedAt) : warningDurationMs
   const remainingMs = Math.max(0, warningDurationMs - elapsed)
-  const showWidthWarning = terminalCols > 0 && terminalCols < MIN_TABLE_WIDTH && !widthWarningDismissed && widthWarningShowCount < 2 && remainingMs > 0
+  const showWidthWarning = terminalCols > 0 && terminalCols < MIN_TABLE_WIDTH && !disableWidthsWarning && !widthWarningDismissed && widthWarningShowCount < 2 && remainingMs > 0
 
   if (showWidthWarning) {
     const lines = []
@@ -216,6 +216,10 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     lines.push(' '.repeat(padLeft3) + chalk.red(warning3))
     lines.push('')
     lines.push(' '.repeat(Math.max(0, Math.floor((terminalCols - 34) / 2))) + chalk.yellow(`this message will hide in ${(remainingMs / 1000).toFixed(1)}s`))
+    const barTotal = Math.max(0, Math.min(terminalCols - 4, 30))
+    const barFill = Math.round((elapsed / warningDurationMs) * barTotal)
+    const barStr = chalk.green('█'.repeat(barFill)) + chalk.dim('░'.repeat(barTotal - barFill))
+    lines.push(' '.repeat(Math.max(0, Math.floor((terminalCols - barTotal) / 2))) + barStr)
     lines.push(' '.repeat(Math.max(0, Math.floor((terminalCols - 20) / 2))) + chalk.dim('press esc to dismiss'))
     while (terminalRows > 0 && lines.length < terminalRows) lines.push('')
     const EL = '\x1b[K'
@@ -297,17 +301,11 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     return chalk.yellow.bold('U') + chalk.dim('p%' + padding)
   })()
   const tokensH_c  = chalk.dim(tokensH.padEnd(W_TOKENS))
-  // 📖 Usage sorts on plain G, so the highlighted letter must stay in the visible header.
-  const usageH_c   = sortColumn === 'usage' ? chalk.bold.cyan(usageH.padEnd(W_USAGE)) : (() => {
-    const plain = 'UsaGe'
-    const padding = ' '.repeat(Math.max(0, W_USAGE - plain.length))
-    return chalk.dim('Usa') + chalk.yellow.bold('G') + chalk.dim('e' + padding)
-  })()
-
-  // 📖 Header with proper spacing (column order: Rank, Tier, SWE%, CTX, Model, Provider, Latest Ping, Avg Ping, Health, Verdict, Stability, Up%, Used, Usage)
-  lines.push('  ' + rankH_c + '  ' + tierH_c + '  ' + sweH_c + '  ' + ctxH_c + '  ' + modelH_c + '  ' + originH_c + '  ' + pingH_c + '  ' + avgH_c + '  ' + healthH_c + '  ' + verdictH_c + '  ' + stabH_c + '  ' + uptimeH_c + '  ' + tokensH_c + '  ' + usageH_c)
+  // 📖 Usage column removed from UI – no header or separator for it.
+  // Header without Usage column (column order: Rank, Tier, SWE%, CTX, Model, Provider, Latest Ping, Avg Ping, Health, Verdict, Stability, Up%, Used)
+  lines.push('  ' + rankH_c + '  ' + tierH_c + '  ' + sweH_c + '  ' + ctxH_c + '  ' + modelH_c + '  ' + originH_c + '  ' + pingH_c + '  ' + avgH_c + '  ' + healthH_c + '  ' + verdictH_c + '  ' + stabH_c + '  ' + uptimeH_c + '  ' + tokensH_c)
 
-  // 📖 Separator line
+  // Separator line without Usage column
   lines.push(
     '  ' +
     chalk.dim('─'.repeat(W_RANK)) + '  ' +
@@ -322,8 +320,7 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     chalk.dim('─'.repeat(W_VERDICT)) + '  ' +
     chalk.dim('─'.repeat(W_STAB)) + '  ' +
     chalk.dim('─'.repeat(W_UPTIME)) + '  ' +
-    chalk.dim('─'.repeat(W_TOKENS)) + '  ' +
-    chalk.dim('─'.repeat(W_USAGE))
+    chalk.dim('─'.repeat(W_TOKENS))
   )
 
   if (sorted.length === 0) {
@@ -563,26 +560,9 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     const sourceCursorText = providerName.padEnd(W_SOURCE)
     const sourceCell = isCursor ? chalk.rgb(...providerRgb).bold(sourceCursorText) : source
 
-    // 📖 Usage column — provider-scoped remaining quota when measurable,
-    // 📖 otherwise a green dot to show "usable but not meaningfully quantifiable".
-    let usageCell
-    if (r.usagePercent !== undefined && r.usagePercent !== null) {
-      const usageStr = Math.round(r.usagePercent) + '%'
-      if (r.usagePercent >= 80) {
-        usageCell = chalk.greenBright(usageStr.padEnd(W_USAGE))
-      } else if (r.usagePercent >= 50) {
-        usageCell = chalk.yellow(usageStr.padEnd(W_USAGE))
-      } else if (r.usagePercent >= 20) {
-        usageCell = chalk.rgb(255, 165, 0)(usageStr.padEnd(W_USAGE)) // orange
-      } else {
-        usageCell = chalk.red(usageStr.padEnd(W_USAGE))
-      }
-    } else {
-      const usagePlaceholder = usagePlaceholderForProvider(r.providerKey)
-      usageCell = usagePlaceholder === '🟢'
-        ? chalk.greenBright(usagePlaceholder.padEnd(W_USAGE))
-        : chalk.dim(usagePlaceholder.padEnd(W_USAGE))
-    }
+    // 📖 Usage column removed from UI – no usage data displayed.
+    // (We keep the logic but do not render it.)
+    const usageCell = ''
 
     // 📖 Used column — total historical prompt+completion tokens consumed for this
     // 📖 exact provider/model pair, loaded once from request-log.jsonl at startup.
@@ -591,8 +571,8 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
       ? chalk.rgb(120, 210, 255)(formatTokenTotalCompact(tokenTotal).padEnd(W_TOKENS))
       : chalk.dim('0'.padEnd(W_TOKENS))
 
-    // 📖 Build row with double space between columns (order: Rank, Tier, SWE%, CTX, Model, Provider, Latest Ping, Avg Ping, Health, Verdict, Stability, Up%, Used, Usage)
-    const row = '  ' + num + '  ' + tier + '  ' + sweCell + '  ' + ctxCell + '  ' + nameCell + '  ' + sourceCell + '  ' + pingCell + '  ' + avgCell + '  ' + status + '  ' + speedCell + '  ' + stabCell + '  ' + uptimeCell + '  ' + tokensCell + '  ' + usageCell
+    // 📖 Build row with double space between columns (order: Rank, Tier, SWE%, CTX, Model, Provider, Latest Ping, Avg Ping, Health, Verdict, Stability, Up%, Used)
+    const row = '  ' + num + '  ' + tier + '  ' + sweCell + '  ' + ctxCell + '  ' + nameCell + '  ' + sourceCell + '  ' + pingCell + '  ' + avgCell + '  ' + status + '  ' + speedCell + '  ' + stabCell + '  ' + uptimeCell + '  ' + tokensCell
 
     if (isCursor) {
       lines.push(chalk.bgRgb(155, 55, 135)(row))

package/src/tool-launchers.js

@@ -19,22 +19,24 @@
  *   📖 Crush: writes crush.json with provider config + models.large/small defaults
  *   📖 Pi: uses --provider/--model CLI flags for guaranteed auto-selection
  *   📖 Aider: writes ~/.aider.conf.yml + passes --model flag
- *   📖 Claude Code: uses ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN only (mirrors free-claude-code)
+ *   📖 Claude Code: mirrors free-claude-code by keeping fake Claude model ids on the client,
+ *      forcing a valid Claude alias at launch, and moving MODEL / MODEL_OPUS / MODEL_SONNET /
+ *      MODEL_HAIKU routing into the proxy
  *   📖 Codex CLI: uses a custom model_provider override so Codex stays in explicit API-provider mode
  *   📖 Gemini CLI: proxy mode is capability-gated because older builds do not support custom base URL routing cleanly
  *
  * @functions
  *   → `resolveLauncherModelId` — choose the provider-specific id or proxy slug for a launch
- *   → `applyClaudeCodeModelOverrides` — force Claude Code auxiliary model slots onto the chosen proxy model
- *   → `buildClaudeProxyAuthToken` — encode the proxy token + selected model hint for Claude-only fallback routing
+ *   → `waitForClaudeProxyRouting` — wait until the daemon/proxy has reloaded the free-claude-code style Claude-family mapping
+ *   → `buildClaudeProxyArgs` — force a valid Claude alias so stale local non-Claude selections cannot break launch
  *   → `buildCodexProxyArgs` — force Codex into a proxy-backed custom provider config
  *   → `inspectGeminiCliSupport` — detect whether the installed Gemini CLI can use proxy mode safely
  *   → `writeGooseConfig` — install provider + set GOOSE_PROVIDER/GOOSE_MODEL in config.yaml
  *   → `writeCrushConfig` — write provider + models.large/small to crush.json
  *   → `startExternalTool` — configure and launch the selected external tool mode
  *
- * @exports resolveLauncherModelId, applyClaudeCodeModelOverrides, buildClaudeProxyAuthToken
- * @exports buildCodexProxyArgs, inspectGeminiCliSupport, startExternalTool
+ * @exports resolveLauncherModelId, waitForClaudeProxyRouting, buildClaudeProxyArgs, buildCodexProxyArgs
+ * @exports inspectGeminiCliSupport, startExternalTool
  *
  * @see src/tool-metadata.js
  * @see src/provider-metadata.js
@@ -48,7 +50,7 @@ import { delimiter, dirname, join } from 'path'
 import { spawn, spawnSync } from 'child_process'
 import { sources } from '../sources.js'
 import { PROVIDER_COLOR } from './render-table.js'
-import { getApiKey, getProxySettings } from './config.js'
+import { getApiKey, getProxySettings, saveConfig, setClaudeProxyModelRouting } from './config.js'
 import { ENV_VAR_NAMES, isWindows } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
 import { ensureProxyRunning, resolveProxyModelId } from './opencode.js'
@@ -83,6 +85,9 @@ const GEMINI_ENV_KEYS = [
 const PROXY_SANITIZED_ENV_KEYS = [...OPENAI_COMPAT_ENV_KEYS, ...ANTHROPIC_ENV_KEYS, ...GEMINI_ENV_KEYS]
 const GEMINI_PROXY_MIN_VERSION = '0.34.0'
 const EXPERIMENTAL_PROXY_TOOLS_NOTE = 'FCM Proxy V2 support for external tools is still in beta, so some launch and authentication flows can remain flaky while the integration stabilizes.'
+const CLAUDE_PROXY_RELOAD_TIMEOUT_MS = 4000
+const CLAUDE_PROXY_RELOAD_INTERVAL_MS = 200
+const CLAUDE_PROXY_CLIENT_MODEL = 'sonnet'
 
 function ensureDir(filePath) {
   const dir = dirname(filePath)
@@ -154,26 +159,15 @@ export function resolveLauncherModelId(model, useProxy = false) {
   return model?.modelId ?? ''
 }
 
-export function applyClaudeCodeModelOverrides(env, modelId) {
-  const resolvedModelId = typeof modelId === 'string' ? modelId.trim() : ''
-  if (!resolvedModelId) return env
-
-  // 📖 Claude Code still uses auxiliary model slots (opus/sonnet/haiku/subagents)
-  // 📖 even when a custom primary model is selected. Pin them all to the same slug.
-  env.ANTHROPIC_MODEL = resolvedModelId
-  env.ANTHROPIC_DEFAULT_OPUS_MODEL = resolvedModelId
-  env.ANTHROPIC_DEFAULT_SONNET_MODEL = resolvedModelId
-  env.ANTHROPIC_DEFAULT_HAIKU_MODEL = resolvedModelId
-  env.ANTHROPIC_SMALL_FAST_MODEL = resolvedModelId
-  env.CLAUDE_CODE_SUBAGENT_MODEL = resolvedModelId
-  return env
-}
-
-export function buildClaudeProxyAuthToken(proxyToken, modelId) {
-  const resolvedProxyToken = typeof proxyToken === 'string' ? proxyToken.trim() : ''
-  const resolvedModelId = typeof modelId === 'string' ? modelId.trim() : ''
-  if (!resolvedProxyToken) return ''
-  return resolvedModelId ? `${resolvedProxyToken}:${resolvedModelId}` : resolvedProxyToken
+/**
+ * 📖 Force Claude Code to start on a real Claude alias, never on an FCM slug.
+ * 📖 Older FCM launches poisoned Claude's local model state with `gpt-oss-*`,
+ * 📖 and Claude rejects those client-side before any proxy request is made.
+ *
+ * @returns {string[]}
+ */
+export function buildClaudeProxyArgs() {
+  return ['--model', CLAUDE_PROXY_CLIENT_MODEL]
 }
 
 export function buildToolEnv(mode, model, config, options = {}) {
@@ -186,7 +180,7 @@ export function buildToolEnv(mode, model, config, options = {}) {
   const providerKey = model.providerKey
   const providerUrl = sources[providerKey]?.url || ''
   const baseUrl = getProviderBaseUrl(providerKey)
-  const apiKey = getApiKey(config, providerKey)
+  const apiKey = sanitize ? (config?.apiKeys?.[providerKey] ?? null) : getApiKey(config, providerKey)
   const env = cloneInheritedEnv(inheritedEnv, sanitize ? PROXY_SANITIZED_ENV_KEYS : [])
   const providerEnvName = ENV_VAR_NAMES[providerKey]
   if (includeProviderEnv && providerEnvName && apiKey) env[providerEnvName] = apiKey
@@ -206,7 +200,6 @@ export function buildToolEnv(mode, model, config, options = {}) {
   if (mode === 'claude-code' && apiKey && baseUrl) {
     env.ANTHROPIC_AUTH_TOKEN = apiKey
     env.ANTHROPIC_BASE_URL = baseUrl
-    env.ANTHROPIC_MODEL = model.modelId
   }
 
   if (mode === 'gemini' && apiKey && baseUrl) {
@@ -218,6 +211,31 @@ export function buildToolEnv(mode, model, config, options = {}) {
   return { env, apiKey, baseUrl, providerUrl }
 }
 
+export async function waitForClaudeProxyRouting(port, token, expectedModelId) {
+  const expected = typeof expectedModelId === 'string' ? expectedModelId.trim().replace(/^fcm-proxy\//, '') : ''
+  if (!expected || !port || !token) return false
+
+  const deadline = Date.now() + CLAUDE_PROXY_RELOAD_TIMEOUT_MS
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/stats`, {
+        headers: { authorization: `Bearer ${token}` },
+      })
+      if (res.ok) {
+        const payload = await res.json()
+        const active = payload?.anthropicRouting?.model
+        if (typeof active === 'string' && active.replace(/^fcm-proxy\//, '') === expected) {
+          return true
+        }
+      }
+    } catch { /* daemon may still be reloading — keep polling */ }
+
+    await new Promise(resolve => setTimeout(resolve, CLAUDE_PROXY_RELOAD_INTERVAL_MS))
+  }
+
+  return false
+}
+
 export function buildCodexProxyArgs(baseUrl) {
   return [
     '-c', 'model_provider="fcm_proxy"',
@@ -608,9 +626,8 @@ export async function startExternalTool(mode, model, config) {
     return spawnCommand('goose', [], env)
   }
 
-  // 📖 Claude Code, Codex, and Gemini require the FCM Proxy V2 background service.
-  // 📖 Without it, these tools cannot connect to the free providers (protocol mismatch / no direct support).
-  if (mode === 'claude-code' || mode === 'codex' || mode === 'gemini') {
+  // 📖 Codex and Gemini require FCM Proxy V2 to talk to the free-provider mesh.
+  if (mode === 'codex' || mode === 'gemini') {
     if (!proxySettings.enabled) {
       console.log()
       console.log(chalk.red(`  ✖ ${meta.label} requires FCM Proxy V2 to work with free providers.`))
@@ -629,21 +646,46 @@ export async function startExternalTool(mode, model, config) {
   }
 
   if (mode === 'claude-code') {
-    // 📖 Claude Code needs Anthropic-compatible wire format (POST /v1/messages).
-    // 📖 Mirror free-claude-code: one auth env only (`ANTHROPIC_AUTH_TOKEN`) plus base URL.
-    const started = await ensureProxyRunning(config)
+    // 📖 Mirror free-claude-code exactly on the client side:
+    // 📖 Claude gets only ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN, and the
+    // 📖 proxy owns the fake Claude model ids -> real backend model mapping.
+    const launchModelId = resolveLauncherModelId(model, true)
+    const routingChanged = setClaudeProxyModelRouting(config, launchModelId)
+    if (routingChanged) {
+      const saveResult = saveConfig(config)
+      if (!saveResult.success) {
+        console.log()
+        console.log(chalk.red('  ✖ Failed to persist the Claude proxy routing before launch.'))
+        console.log(chalk.dim(`  ${saveResult.error || 'Unknown config write error.'}`))
+        console.log()
+        return 1
+      }
+    }
+
+    const started = await ensureProxyRunning(config, { forceRestart: true })
     const { env: proxyEnv } = buildToolEnv(mode, model, config, {
       sanitize: true,
       includeCompatDefaults: false,
       includeProviderEnv: false,
     })
     const proxyBase = `http://127.0.0.1:${started.port}`
-    const launchModelId = resolveLauncherModelId(model, true)
+    const claudeProxyToken = `${started.proxyToken}:${launchModelId}`
     proxyEnv.ANTHROPIC_BASE_URL = proxyBase
-    proxyEnv.ANTHROPIC_AUTH_TOKEN = buildClaudeProxyAuthToken(started.proxyToken, launchModelId)
-    applyClaudeCodeModelOverrides(proxyEnv, launchModelId)
-    console.log(chalk.dim(`  📖 Claude Code routed through FCM proxy on :${started.port} (Anthropic translation enabled)`))
-    return spawnCommand('claude', ['--model', launchModelId], proxyEnv)
+    proxyEnv.ANTHROPIC_AUTH_TOKEN = claudeProxyToken
+
+    const routingReady = await waitForClaudeProxyRouting(started.port, started.proxyToken, launchModelId)
+    if (!routingReady) {
+      console.log(chalk.yellow(`  ⚠ Claude proxy routing reload is taking longer than expected; launching anyway.`))
+      console.log(chalk.dim(`  ${EXPERIMENTAL_PROXY_TOOLS_NOTE}`))
+    }
+
+    if (routingChanged && proxySettings.enabled !== true) {
+      console.log(chalk.dim('  📖 Proxy mode was auto-enabled for Claude Code because this integration is proxy-only.'))
+    }
+    console.log(chalk.dim(`  📖 Claude Code routed through FCM proxy on :${started.port} with proxy-side Claude model mapping`))
+    console.log(chalk.dim(`  📖 Claude itself is forced onto the safe alias: ${CLAUDE_PROXY_CLIENT_MODEL}`))
+    console.log(chalk.dim(`  📖 All Claude families now resolve to: ${model.label} (${launchModelId})`))
+    return spawnCommand('claude', buildClaudeProxyArgs(), proxyEnv)
   }
 
   if (mode === 'codex') {