free-coding-models 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ---
 
+## 0.3.2
+
+### Fixed
+- **Claude Code model-family routing now mirrors `free-claude-code`**: The proxy remaps Claude's internal model ids like `claude-3-5-sonnet-*`, `claude-3-haiku-*`, `claude-3-opus-*`, `sonnet`, `haiku`, and `default` back to the selected FCM proxy model instead of rejecting them as missing.
+- **Claude Code helper/background requests stay on the selected model**: Launches now pin the Anthropic helper model env vars and encode the selected proxy model inside `ANTHROPIC_AUTH_TOKEN`, so Claude Code has a stable fallback even when it emits internal aliases.
+
+## 0.3.1
+
+### Added
+- **CLI `--help` output**: `free-coding-models --help` now prints the full launcher, analysis, config, and daemon command matrix in a non-interactive format.
+
+### Fixed
+- **Outdated-version footer alert**: The main TUI now shows a full-width red footer line with manual `npm install -g free-coding-models@latest` recovery instructions, but only when a newer npm version is actually known.
+- **Claude Code proxy auth conflict**: Proxy launches now sanitize inherited env vars and use only `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_BASE_URL`, matching the `free-claude-code` contract instead of mixing Anthropic auth modes.
+- **Codex CLI proxy routing**: Codex launches now force an explicit custom provider config and the proxy now supports `POST /v1/responses`, so `codex-cli 0.114.0` no longer depends on the broken built-in OAuth/base-url path.
+- **Anthropic token counting**: Added `POST /v1/messages/count_tokens` with a fast local estimate so Claude-compatible clients keep their budgeting flow through FCM Proxy V2.
+- **Gemini proxy failure mode**: Gemini launch now preflights the installed CLI/config, blocks incompatible builds like `0.33.0`, and surfaces `~/.gemini/settings.json` schema errors instead of pretending proxy mode works.
+
+### Changed
+- **Proxy auto-sync now follows the current tool**: The proxy overlay no longer asks for a separate active tool; cleanup and auto-sync now target the current `Z` mode whenever that tool supports persisted proxy config.
+- **Install Endpoints (`Y`) is narrower on purpose**: `Claude Code`, `Codex`, and `Gemini` were removed from the install-target menu so the flow only lists tools with a stable persisted-config contract.
+- **Proxy model listing is more Codex-friendly**: `GET /v1/models` now returns both the usual OpenAI `data` array and a `models` array with `slug` fields for clients that expect a richer catalog shape.
+- **Launcher diagnostics now mention the beta state clearly**: Proxy-backed external tools now remind users that the integration is still stabilizing when a launch is blocked.
+
 ## 0.3.0
 
 ### Added

package/README.md

@@ -46,6 +46,9 @@ By Vanessa Depraute
   <sub>Ping free coding models from 20 providers in real-time — pick the best one for OpenCode, OpenClaw, or any AI coding assistant</sub>
 </p>
 
+> ⚠️ **Beta notice**  
+> FCM Proxy V2 support for external tools is still in beta. Claude Code, Codex, Gemini, and the other proxy-backed launchers already work in many setups, but auth and startup edge cases can still fail while the integration stabilizes.
+
 <p align="center">
   <img src="demo.gif" alt="free-coding-models demo" width="100%">
 </p>
@@ -87,7 +90,7 @@ By Vanessa Depraute
 - **💻 OpenCode integration** — Auto-detects NIM setup, sets model as default, launches OpenCode
 - **🦞 OpenClaw integration** — Sets selected model as default provider in `~/.openclaw/openclaw.json`
 - **🧰 Public tool launchers** — `Enter` auto-configures and launches 10+ tools: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Aider`, `Claude Code`, `Codex`, `Gemini`, `Qwen`, `OpenHands`, `Amp`, and `Pi`. All tools auto-select the chosen model on launch.
-- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider into any of the 13 supported tools, with a choice between **Direct Provider** (pure API) or **FCM Proxy V2** (key rotation + usage tracking), then pick all models or a curated subset
+- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider into the compatible persisted-config tools, with a choice between **Direct Provider** (pure API) or **FCM Proxy V2** (key rotation + usage tracking), then pick all models or a curated subset
 - **📝 Feature Request (J key)** — Send anonymous feedback directly to the project team
 - **🐛 Bug Report (I key)** — Send anonymous bug reports directly to the project team
  - **🎨 Clean output** — Zero scrollback pollution, interface stays open until Ctrl+C
@@ -179,15 +182,12 @@ bunx free-coding-models YOUR_API_KEY
 
 ### 🆕 What's New
 
-**Version 0.2.6 brings powerful new features:**
-
-- **`--json` flag** — Output model results as JSON for scripting, CI/CD pipelines, and monitoring dashboards. Perfect for automation: `free-coding-models --tier S --json | jq '.[0].modelId'`
-
-- **Persistent ping cache** — Results are cached for 5 minutes between runs. Startup is nearly instant when cache is fresh, and you save API rate limits. Cache file: `~/.free-coding-models.cache.json`
-
-- **Config security check** — Automatically warns if your API key config file has insecure permissions and offers one-click auto-fix with `chmod 600`
+**Version 0.3.2 hardens the Claude Code proxy path to match the routing strategy that works in `free-claude-code`:**
 
-- **Provider colors everywhere** — Provider names are now colored consistently in logs, settings, and the main table for better visual recognition
+- **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.
 
 ---
 
@@ -216,11 +216,14 @@ free-coding-models --best
  # Analyze for 10 seconds and output the most reliable model
  free-coding-models --fiable
 
- # Output results as JSON (for scripting/automation)
+# Output results as JSON (for scripting/automation)
 free-coding-models --json
 free-coding-models --tier S --json | jq '.[0].modelId'  # Get fastest S-tier model ID
 free-coding-models --json | jq '.[] | select(.avgPing < 500)'  # Filter by latency
 
+# Print the complete CLI help with every supported flag and daemon command
+free-coding-models --help
+
  # Filter models by tier letter
 free-coding-models --tier S          # S+ and S only
 free-coding-models --tier A          # A+, A, A- only
@@ -315,6 +318,7 @@ Press **`P`** to open the Settings screen at any time:
  Keys are saved to `~/.free-coding-models.json` (permissions `0600`).
 
  Manual update is in the same Settings screen (`P`) under **Maintenance** (Enter to check, Enter again to install when an update is available).
+ When a newer npm release is known, the main footer also adds a full-width red warning line with the manual recovery command `npm install -g free-coding-models@latest`.
  Favorites are also persisted in the same config file and survive restarts.
  The main table now starts in `Configured Only` mode, so if nothing is set up yet you can press `P` and add your first API key immediately.
 
@@ -601,9 +605,9 @@ free-coding-models daemon logs        # Show recent service logs
 
 The dedicated **FCM Proxy V2** overlay (accessible via `J` from main TUI, or Settings → Enter) provides full control:
 
-- **Active tool selector** — Choose which AI coding tool receives proxy config (cycles through all 12 syncable tools)
-- **Auto-sync toggle** — Automatically write the `fcm-proxy` provider to the active tool's config when the proxy starts
-- **Cleanup** — Remove `fcm-proxy` entries from the active tool's config (works for any syncable tool)
+- **Current tool hint** — Shows which Z-selected tool will receive persisted proxy config (when that mode supports it)
+- **Auto-sync toggle** — Automatically write the `fcm-proxy` provider to the current tool's config when the proxy starts
+- **Cleanup** — Remove `fcm-proxy` entries from the current tool's config
 - **Status display** — Running/Stopped/Stale/Unhealthy with PID, port, uptime, account/model counts
 - **Version mismatch detection** — warns if service version differs from installed FCM version
 - **Restart** — stop + start via the OS service manager
@@ -627,7 +631,7 @@ The dedicated **FCM Proxy V2** overlay (accessible via `J` from main TUI, or Set
 | `~/.free-coding-models/daemon.json` | Status file (PID, port, token) — written by the background service |
 | `~/.free-coding-models/daemon-stdout.log` | Service output log |
 
-The `proxy.activeTool` field in the config file tracks which tool the proxy auto-syncs to (e.g. `"opencode"`, `"aider"`, `"claude-code"`).
+The `proxy.activeTool` field is now legacy-only. FCM Proxy V2 follows the current **Z-selected** tool automatically whenever that mode supports persisted proxy sync.
 
 ### Cleanup
 
@@ -680,7 +684,11 @@ Press **Z** to cycle through all 13 tool modes in the TUI, or use flags to start
 
 ⚡ = Requires FCM Proxy V2 background service (press `J` to enable). These tools cannot connect to free providers without the proxy.
 
-All tools are also available as install targets in the **Install Endpoints** flow (`Y` key) — install an entire provider catalog into any tool with one flow, choosing between Direct Provider or FCM Proxy V2 connection.
+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.
+
+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.
 
 ---
 
@@ -979,7 +987,7 @@ This script:
 | `--tier C` | Show only C tier models |
 | `--profile <name>` | Load a saved config profile on startup |
 | `--recommend` | Auto-open Smart Recommend overlay on start |
-| `--clean-proxy` | Remove persisted `fcm-proxy` config from the active tool |
+| `--clean-proxy` | Remove persisted `fcm-proxy` config from OpenCode |
 
 **Keyboard shortcuts (main TUI):**
 - **↑↓** — Navigate models
@@ -1011,9 +1019,9 @@ Pressing **K** now shows a full in-app reference: main hotkeys, settings hotkeys
 `Y` opens a dedicated install flow for configured providers. The 5-step flow is:
 
 1. **Provider** — Pick one provider that already has an API key in Settings
-2. **Tool** — Pick the target tool from all 13 supported tools:
-   - Config-based: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Pi`, `Aider`, `Amp`, `Gemini`, `Qwen`
-   - Env-file based: `Claude Code`, `Codex CLI`, `OpenHands` (writes `~/.fcm-{tool}-env` — source it before launching)
+2. **Tool** — Pick the target tool from the compatible install targets:
+   - Config-based: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Pi`, `Aider`, `Amp`, `Qwen`
+   - Env-file based: `OpenHands` (writes `~/.fcm-openhands-env` — source it before launching)
 3. **Connection Mode** — Choose how the tool connects to the provider:
    - **⚡ Direct Provider** — pure API connection, no proxy involved
    - **🔄 FCM Proxy V2** — route through FCM Proxy V2 with key rotation and usage tracking
@@ -1026,7 +1034,8 @@ Important behavior:
 - `Install all models` is the recommended path because FCM can refresh that catalog automatically on later launches when the provider model list changes
 - `Install selected models only` is useful when you want a smaller curated picker inside the target tool
 - `OpenCode CLI` and `OpenCode Desktop` share the same `opencode.json`, so the managed provider appears in both
-- For env-based tools (Claude Code, Codex, OpenHands), FCM writes a sourceable file at `~/.fcm-{tool}-env` — run `source ~/.fcm-claude-code-env` before launching
+- `Claude Code`, `Codex`, and `Gemini` are launcher-only in this flow for now. Use the normal `Enter` launcher path so FCM can apply the right proxy/runtime contract automatically.
+- For env-based install targets like `OpenHands`, FCM writes a sourceable helper file at `~/.fcm-{tool}-env`
 
  **Keyboard shortcuts (Settings screen — `P` key):**
  - **↑↓** — Navigate providers, maintenance row, and profile rows

package/bin/free-coding-models.js

@@ -78,7 +78,11 @@
  *   - --best: Show only top-tier models (A+, S, S+)
  *   - --fiable: Analyze 10s and output the most reliable model
  *   - --json: Output results as JSON (for scripting/automation)
+ *   - --recommend: Open Smart Recommend immediately on startup
+ *   - --profile <name>: Load a saved config profile before entering the TUI
+ *   - --clean-proxy / --proxy-clean: Remove persisted fcm-proxy config from OpenCode
  *   - --no-telemetry: Disable anonymous usage analytics for this run
+ *   - --help / -h: Print the full CLI help and exit
  *   - --tier S/A/B/C: Filter models by tier letter (S=S+/S, A=A+/A/A-, B=B+/B, C=C)
  *
  *   @see {@link https://build.nvidia.com} NVIDIA API key generation
@@ -88,6 +92,7 @@
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
+import { fileURLToPath } from 'url'
 import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs'
 import { randomUUID } from 'crypto'
 import { homedir } from 'os'
@@ -124,6 +129,7 @@ import { startExternalTool } from '../src/tool-launchers.js'
 import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels, CONNECTION_MODES } from '../src/endpoint-installer.js'
 import { loadCache, saveCache, clearCache, getCacheAge } from '../src/cache.js'
 import { checkConfigSecurity } from '../src/security.js'
+import { buildCliHelpText } from '../src/cli-help.js'
 
 // 📖 mergedModels: cross-provider grouped model list (one entry per label, N providers each)
 // 📖 mergedModelByLabel: fast lookup map from display label → merged model entry
@@ -173,6 +179,13 @@ const LOCAL_VERSION = pkg.version
 async function main() {
   const cliArgs = parseArgs(process.argv)
 
+  if (cliArgs.helpMode) {
+    console.log()
+    console.log(buildCliHelpText({ chalk, title: 'free-coding-models' }))
+    console.log()
+    process.exit(0)
+  }
+
   // Validate --tier early, before entering alternate screen
   if (cliArgs.tierFilter && !TIER_LETTER_MAP[cliArgs.tierFilter]) {
     console.error(chalk.red(`  Unknown tier "${cliArgs.tierFilter}". Valid tiers: S, A, B, C`))
@@ -336,28 +349,48 @@ async function main() {
     ts: new Date().toISOString(),
   })
 
-  // 📖 Check for updates in the background (non-blocking, non-forced)
-  // 📖 The old auto-update on startup caused infinite loops, so we've moved to:
-  // 📖 1. Optional prompt when a new version is available (user chooses to update or not)
-  // 📖 2. Display "OUTDATED" in TUI footer if update check fails repeatedly
+  // 📖 Auto-update detection: check npm registry for new versions at startup.
+  // 📖 If a new version is available, show an interactive prompt (Update / Changelogs / Skip).
+  // 📖 Dev mode (git checkout) skips auto-update to avoid infinite relaunch loops.
   let latestVersion = null
-  let isOutdated = false
+  const isDevMode = existsSync(join(dirname(fileURLToPath(import.meta.url)), '..', '.git'))
   try {
     latestVersion = await checkForUpdate()
-    // 📖 Track update check failures - if it fails 3+ times, mark as outdated
-    if (!latestVersion && config.settings?.updateCheckFailures >= 3) {
-      isOutdated = true
+    // 📖 Reset failure counter on successful check
+    if (config.settings?.updateCheckFailures) {
+      config.settings.updateCheckFailures = 0
+      saveConfig(config)
     }
   } catch (err) {
-    // 📖 Silently fail - don't block the app if npm registry is unreachable
-    // 📖 But track the failure for outdated detection
     const failures = (config.settings?.updateCheckFailures || 0) + 1
     if (!config.settings) config.settings = {}
     config.settings.updateCheckFailures = Math.min(failures, 3)
-    if (failures >= 3) isOutdated = true
     saveConfig(config)
   }
 
+  // 📖 Show interactive update prompt if a new version is available (skip in dev mode)
+  if (latestVersion && !isDevMode) {
+    const choice = await promptUpdateNotification(latestVersion)
+    if (choice === 'update') {
+      runUpdate(latestVersion)
+      return // 📖 runUpdate relaunches the process — this line is a safety guard
+    } else if (choice === 'changelogs') {
+      const { execSync: _exec } = await import('child_process')
+      const url = 'https://github.com/vava-nessa/free-coding-models/releases'
+      try {
+        if (process.platform === 'darwin') _exec(`open ${url}`)
+        else if (process.platform === 'linux') _exec(`xdg-open ${url}`)
+        else console.log(chalk.dim(`  📋 ${url}`))
+      } catch { console.log(chalk.dim(`  📋 ${url}`)) }
+      // 📖 After opening changelogs, re-prompt so user can still update or continue
+      const choice2 = await promptUpdateNotification(latestVersion)
+      if (choice2 === 'update') {
+        runUpdate(latestVersion)
+        return
+      }
+    }
+  }
+
   // 📖 Dynamic OpenRouter free model discovery — fetch live free models from API
   // 📖 Replaces static openrouter entries in MODELS with fresh data.
   // 📖 Fallback: if fetch fails, the static list from sources.js stays intact + warning shown.
@@ -446,8 +479,8 @@ async function main() {
     lastPingTime: now,            // 📖 Track when last ping cycle started
     lastUserActivityAt: now,      // 📖 Any keypress refreshes this timer; inactivity can force slow mode.
     resumeSpeedOnActivity: false, // 📖 Set after idle slowdown so the next activity restarts a 60s speed burst.
-    latestVersion,                // 📖 Latest npm version available (null if none or check failed)
-    isOutdated,                   // 📖 Set to true if update check failed 3+ times (show red "OUTDATED" footer)
+    startupLatestVersion: latestVersion, // 📖 Startup auto-check result reused by the footer banner after "skip update".
+    versionAlertsEnabled: !isDevMode, // 📖 Dev checkouts should not tell contributors to upgrade the global npm package.
     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)
@@ -604,11 +637,9 @@ async function main() {
     }
   }
 
-  // 📖 Auto-start proxy on launch if OpenCode config already has an fcm-proxy provider.
+  // 📖 Auto-start proxy on launch when proxy auto-sync is enabled for the current tool.
   // 📖 Fire-and-forget: does not block UI startup. state.proxyStartupStatus is updated async.
-  if (mode === 'opencode' || mode === 'opencode-desktop') {
-    void autoStartProxyIfSynced(config, state)
-  }
+  void autoStartProxyIfSynced(config, state)
 
   // 📖 Load cache if available (for faster startup with cached ping results)
   const cached = loadCache()
@@ -886,7 +917,7 @@ async function main() {
                 ? overlays.renderLog()
               : state.changelogOpen
                 ? overlays.renderChangelog()
-                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion)
+                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.startupLatestVersion, state.versionAlertsEnabled)
     process.stdout.write(ALT_HOME + content)
   }, Math.round(1000 / FPS))
 
@@ -894,7 +925,7 @@ async function main() {
   const initialVisible = state.results.filter(r => !r.hidden)
   state.visibleSorted = sortResultsWithPinnedFavorites(initialVisible, state.sortColumn, state.sortDirection)
 
-  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion))
+  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.startupLatestVersion, state.versionAlertsEnabled))
 
   // 📖 If --recommend was passed, auto-open the Smart Recommend overlay on start
   if (cliArgs.recommendMode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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/anthropic-translator.js

@@ -15,14 +15,51 @@
  *   → translateAnthropicToOpenAI(body) — Convert Anthropic Messages request → OpenAI chat completions
  *   → translateOpenAIToAnthropic(openaiResponse, requestModel) — Convert OpenAI JSON response → Anthropic
  *   → createAnthropicSSETransformer(requestModel) — Create a Transform stream for SSE translation
+ *   → estimateAnthropicTokens(body) — Fast local token estimate for `/v1/messages/count_tokens`
  *
- * @exports translateAnthropicToOpenAI, translateOpenAIToAnthropic, createAnthropicSSETransformer
+ * @exports translateAnthropicToOpenAI, translateOpenAIToAnthropic, createAnthropicSSETransformer, estimateAnthropicTokens
  * @see src/proxy-server.js — routes /v1/messages through this translator
  */
 
 import { Transform } from 'node:stream'
 import { randomUUID } from 'node:crypto'
 
+function normalizeThinkingText(block) {
+  if (!block || typeof block !== 'object') return ''
+  if (typeof block.text === 'string' && block.text) return block.text
+  if (typeof block.thinking === 'string' && block.thinking) return block.thinking
+  if (typeof block.summary === 'string' && block.summary) return block.summary
+  return ''
+}
+
+function contentBlocksToText(blocks, { includeThinking = false } = {}) {
+  return blocks
+    .map((block) => {
+      if (block?.type === 'thinking' && includeThinking) {
+        const thinkingText = normalizeThinkingText(block)
+        return thinkingText ? `<thinking>${thinkingText}</thinking>` : ''
+      }
+      if (block?.type === 'redacted_thinking' && includeThinking) {
+        return '<thinking>[redacted]</thinking>'
+      }
+      return block?.type === 'text' ? block.text : ''
+    })
+    .filter(Boolean)
+}
+
+function extractReasoningBlocks(message = {}) {
+  if (Array.isArray(message.reasoning)) {
+    return message.reasoning
+      .map((entry) => normalizeThinkingText(entry))
+      .filter(Boolean)
+      .map((text) => ({ type: 'thinking', thinking: text }))
+  }
+  if (typeof message.reasoning_content === 'string' && message.reasoning_content.trim()) {
+    return [{ type: 'thinking', thinking: message.reasoning_content.trim() }]
+  }
+  return []
+}
+
 /**
  * 📖 Translate an Anthropic Messages API request body to OpenAI Chat Completions format.
  *
@@ -48,10 +85,7 @@ export function translateAnthropicToOpenAI(body) {
       openaiMessages.push({ role: 'system', content: body.system })
     } else if (Array.isArray(body.system)) {
       // 📖 Anthropic supports system as array of content blocks
-      const text = body.system
-        .filter(b => b.type === 'text')
-        .map(b => b.text)
-        .join('\n\n')
+      const text = contentBlocksToText(body.system, { includeThinking: true }).join('\n\n')
       if (text) openaiMessages.push({ role: 'system', content: text })
     }
   }
@@ -65,9 +99,7 @@ export function translateAnthropicToOpenAI(body) {
         openaiMessages.push({ role, content: msg.content })
       } else if (Array.isArray(msg.content)) {
         // 📖 Anthropic content blocks: [{type: "text", text: "..."}, {type: "tool_result", ...}]
-        const textParts = msg.content
-          .filter(b => b.type === 'text')
-          .map(b => b.text)
+        const textParts = contentBlocksToText(msg.content, { includeThinking: true })
         const toolResults = msg.content.filter(b => b.type === 'tool_result')
         const toolUses = msg.content.filter(b => b.type === 'tool_use')
 
@@ -155,6 +187,10 @@ export function translateOpenAIToAnthropic(openaiResponse, requestModel) {
   const message = choice?.message || {}
   const content = []
 
+  for (const reasoningBlock of extractReasoningBlocks(message)) {
+    content.push(reasoningBlock)
+  }
+
   // 📖 Text content → Anthropic text block
   if (message.content) {
     content.push({ type: 'text', text: message.content })
@@ -368,3 +404,37 @@ export function createAnthropicSSETransformer(requestModel) {
     getUsage: () => ({ input_tokens: inputTokens, output_tokens: outputTokens }),
   }
 }
+
+function estimateTokenCountFromText(text) {
+  const normalized = String(text || '').trim()
+  if (!normalized) return 0
+  return Math.ceil(normalized.length / 4)
+}
+
+export function estimateAnthropicTokens(body) {
+  const openaiBody = translateAnthropicToOpenAI(body)
+  const messageTokens = Array.isArray(openaiBody.messages)
+    ? openaiBody.messages.reduce((total, message) => {
+        let nextTotal = total + 4
+        if (typeof message.content === 'string') {
+          nextTotal += estimateTokenCountFromText(message.content)
+        }
+        if (Array.isArray(message.tool_calls)) {
+          for (const toolCall of message.tool_calls) {
+            nextTotal += estimateTokenCountFromText(toolCall.function?.name || '')
+            nextTotal += estimateTokenCountFromText(toolCall.function?.arguments || '')
+          }
+        }
+        if (typeof message.tool_call_id === 'string') {
+          nextTotal += estimateTokenCountFromText(message.tool_call_id)
+        }
+        return nextTotal
+      }, 2)
+    : 0
+
+  const toolTokens = Array.isArray(body?.tools)
+    ? body.tools.reduce((total, tool) => total + estimateTokenCountFromText(JSON.stringify(tool || {})), 0)
+    : 0
+
+  return messageTokens + toolTokens
+}

package/src/cli-help.js

@@ -0,0 +1,108 @@
+/**
+ * @file src/cli-help.js
+ * @description Shared CLI help builder for the startup `--help` flag and the in-app help overlay.
+ *
+ * @details
+ *   📖 Keeping CLI help text in one module avoids the classic drift where the TUI overlay
+ *   📖 documents one set of flags while `--help` prints another. New flags should be added
+ *   📖 here once, then both entry points stay aligned.
+ *
+ *   📖 The builder accepts an optional `chalk` instance. When omitted, it returns plain text,
+ *   📖 which keeps unit tests simple and makes the function safe for non-TTY contexts.
+ *
+ * @functions
+ *   → `buildCliHelpLines` — build formatted help lines with optional colors and indentation
+ *   → `buildCliHelpText` — join the help lines into one printable string
+ *
+ * @exports buildCliHelpLines, buildCliHelpText
+ * @see ./tool-metadata.js — source of truth for launcher modes and their CLI flags
+ */
+
+import { getToolModeOrder, getToolMeta } from './tool-metadata.js'
+
+const ANALYSIS_FLAGS = [
+  { flag: '--best', description: 'Show only top tiers (A+, S, S+)' },
+  { flag: '--fiable', description: 'Run the 10s reliability analysis mode' },
+  { flag: '--json', description: 'Output results as JSON for scripts/automation' },
+  { flag: '--tier <S|A|B|C>', description: 'Filter models by tier family' },
+  { flag: '--recommend', description: 'Open Smart Recommend immediately on startup' },
+]
+
+const CONFIG_FLAGS = [
+  { flag: '--profile <name>', description: 'Load a saved config profile before startup' },
+  { flag: '--no-telemetry', description: 'Disable anonymous telemetry for this run' },
+  { flag: '--clean-proxy, --proxy-clean', description: 'Remove persisted fcm-proxy config from OpenCode' },
+  { flag: '--help, -h', description: 'Print this help and exit' },
+]
+
+const COMMANDS = [
+  { command: 'daemon status', description: 'Show background FCM Proxy V2 service status' },
+  { command: 'daemon install', description: 'Install and start the background service' },
+  { command: 'daemon uninstall', description: 'Remove the background service' },
+  { command: 'daemon restart', description: 'Restart the background service' },
+  { command: 'daemon logs', description: 'Print the latest daemon log lines' },
+]
+
+const EXAMPLES = [
+  'free-coding-models --help',
+  'free-coding-models --openclaw --tier S',
+  "free-coding-models --json | jq '.[0]'",
+  'free-coding-models daemon status',
+]
+
+function paint(chalk, formatter, text) {
+  if (!chalk || !formatter) return text
+  return formatter(text)
+}
+
+function formatEntry(label, description, { chalk = null, indent = '', labelWidth = 40 } = {}) {
+  const coloredLabel = paint(chalk, chalk?.cyan, label.padEnd(labelWidth))
+  const coloredDescription = paint(chalk, chalk?.dim, description)
+  return `${indent}${coloredLabel} ${coloredDescription}`
+}
+
+export function buildCliHelpLines({ chalk = null, indent = '', title = 'CLI Help' } = {}) {
+  const lines = []
+  const launchFlags = getToolModeOrder()
+    .map((mode) => getToolMeta(mode))
+    .filter((meta) => meta.flag)
+    .map((meta) => ({ flag: meta.flag, description: `${meta.label} mode` }))
+
+  lines.push(`${indent}${paint(chalk, chalk?.bold, title)}`)
+  lines.push(`${indent}${paint(chalk, chalk?.dim, 'Usage: free-coding-models [apiKey] [options]')}`)
+  lines.push(`${indent}${paint(chalk, chalk?.dim, '       free-coding-models daemon [status|install|uninstall|restart|logs]')}`)
+  lines.push('')
+  lines.push(`${indent}${paint(chalk, chalk?.bold, 'Tool Flags')}`)
+  for (const entry of launchFlags) {
+    lines.push(formatEntry(entry.flag, entry.description, { chalk, indent }))
+  }
+  lines.push('')
+  lines.push(`${indent}${paint(chalk, chalk?.bold, 'Analysis Flags')}`)
+  for (const entry of ANALYSIS_FLAGS) {
+    lines.push(formatEntry(entry.flag, entry.description, { chalk, indent }))
+  }
+  lines.push('')
+  lines.push(`${indent}${paint(chalk, chalk?.bold, 'Config & Maintenance')}`)
+  for (const entry of CONFIG_FLAGS) {
+    lines.push(formatEntry(entry.flag, entry.description, { chalk, indent }))
+  }
+  lines.push('')
+  lines.push(`${indent}${paint(chalk, chalk?.bold, 'Commands')}`)
+  for (const entry of COMMANDS) {
+    lines.push(formatEntry(entry.command, entry.description, { chalk, indent }))
+  }
+  lines.push('')
+  lines.push(`${indent}${paint(chalk, chalk?.dim, 'Default launcher with no tool flag: OpenCode CLI')}`)
+  lines.push(`${indent}${paint(chalk, chalk?.dim, 'Flags can be combined: --openclaw --tier S --json')}`)
+  lines.push('')
+  lines.push(`${indent}${paint(chalk, chalk?.bold, 'Examples')}`)
+  for (const example of EXAMPLES) {
+    lines.push(`${indent}${paint(chalk, chalk?.cyan, example)}`)
+  }
+
+  return lines
+}
+
+export function buildCliHelpText(options = {}) {
+  return buildCliHelpLines(options).join('\n')
+}

package/src/config.js

@@ -679,7 +679,8 @@ export function normalizeProxySettings(proxy = null) {
     daemonConsent: (typeof proxy?.daemonConsent === 'string' && proxy.daemonConsent.length > 0)
       ? proxy.daemonConsent
       : null,
-    // 📖 activeTool — which tool the proxy auto-syncs to (defaults to current Z mode)
+    // 📖 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)
       ? proxy.activeTool
       : null,

package/src/endpoint-installer.js

@@ -27,7 +27,7 @@
  *   - Amp gets ~/.config/amp/settings.json
  *   - Gemini gets ~/.gemini/settings.json
  *   - Qwen gets ~/.qwen/settings.json with modelProviders
- *   - Claude Code, Codex, OpenHands get a sourceable env file (~/.fcm-{tool}-env)
+ *   - OpenHands gets a sourceable env file (~/.fcm-openhands-env)
  *
  * @functions
  *   → `getConfiguredInstallableProviders` — list configured providers that support direct endpoint installs
@@ -54,8 +54,9 @@ import { ENV_VAR_NAMES, PROVIDER_METADATA } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
 
 const DIRECT_INSTALL_UNSUPPORTED_PROVIDERS = new Set(['replicate', 'zai'])
-// 📖 All supported install targets — matches TOOL_MODE_ORDER in tool-metadata.js
-const INSTALL_TARGET_MODES = ['opencode', 'opencode-desktop', 'openclaw', 'crush', 'goose', 'pi', 'aider', 'claude-code', 'codex', 'gemini', 'qwen', 'openhands', 'amp']
+// 📖 Install Endpoints only lists tools whose persisted config shape is actually supported here.
+// 📖 Claude Code, Codex, and Gemini stay launcher-only until their proxy/runtime setup is stable.
+const INSTALL_TARGET_MODES = ['opencode', 'opencode-desktop', 'openclaw', 'crush', 'goose', 'pi', 'aider', 'qwen', 'openhands', 'amp']
 
 // 📖 Connection modes: direct (pure provider) vs FCM proxy (rotates keys)
 export const CONNECTION_MODES = [
@@ -528,7 +529,7 @@ function installIntoEnvBasedTool(providerKey, models, apiKey, toolMode, paths, c
     if (connectionMode === 'proxy') {
       // 📖 Point to proxy base (not /v1) — Claude Code adds /v1/messages itself
       const proxyBase = effectiveBaseUrl.replace(/\/v1$/, '')
-      envLines.push(`export ANTHROPIC_API_KEY="${effectiveApiKey}"`)
+      envLines.push(`export ANTHROPIC_AUTH_TOKEN="${effectiveApiKey}"`)
       envLines.push(`export ANTHROPIC_BASE_URL="${proxyBase}"`)
       envLines.push(`export ANTHROPIC_MODEL="${effectiveModelId}"`)
     } else {