free-coding-models 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ---
 
+## 0.3.5
+
+### Fixed
+- **Claude Code beta-route compatibility**: FCM Proxy V2 now matches routes on the URL pathname, so Anthropic requests like `/v1/messages?beta=true` and `/v1/messages/count_tokens?beta=true` resolve correctly instead of failing with a fake “selected model may not exist” error.
+- **Claude proxy parity with `free-claude-code`**: The Claude integration was revalidated against the real `claude` binary, and the proxy-side Claude alias mapping now reaches the upstream provider again in the exact `free-claude-code` style flow.
+
+## 0.3.4
+
+### Added
+- **Proxy root landing JSON**: `GET /` on FCM Proxy V2 now returns a small unauthenticated status payload, so browser checks no longer fail with `{"error":"Unauthorized"}`.
+- **`daemon stop` CLI command**: The public CLI now supports `free-coding-models daemon stop`, matching the existing daemon manager capability and the documented workflow.
+
+### Fixed
+- **README/UI parity restored**: The docs now match the current product surface, including `160` models, the `Used` token-history column, and the current launcher/proxy behavior.
+- **Malformed config sections are normalized on load**: Invalid `apiKeys`, `providers`, or `settings` values are now coerced back to safe empty objects instead of leaking broken runtime shapes into the app.
+
 ## 0.3.3
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
   <img src="https://img.shields.io/npm/v/free-coding-models?color=76b900&label=npm&logo=npm" alt="npm version">
   <img src="https://img.shields.io/node/v/free-coding-models?color=76b900&logo=node.js" alt="node version">
   <img src="https://img.shields.io/npm/l/free-coding-models?color=76b900" alt="license">
-  <img src="https://img.shields.io/badge/models-159-76b900?logo=nvidia" alt="models count">
+  <img src="https://img.shields.io/badge/models-160-76b900?logo=nvidia" alt="models count">
   <img src="https://img.shields.io/badge/providers-20-blue" alt="providers count">
 </p>
 
@@ -81,7 +81,7 @@ By Vanessa Depraute
 - **📈 Rolling averages** — Avg calculated from ALL successful pings since start
 - **📊 Uptime tracking** — Percentage of successful pings shown in real-time
 - **📐 Stability score** — Composite 0–100 score measuring consistency (p95, jitter, spikes, uptime)
-- **📊 Usage tracking** — Monitor remaining quota for each exact provider/model pair when the provider exposes it; otherwise the TUI shows a green dot instead of a misleading percentage.
+- **📊 Token usage tracking** — The proxy logs prompt+completion token usage per exact provider/model pair, and the TUI surfaces that history in the `Used` column and the request log overlay.
 - **📜 Request Log Overlay** — Press `X` to inspect recent proxied requests and token usage for exact provider/model pairs.
 - **📋 Changelog Overlay** — Press `N` to browse all versions in an index, then `Enter` to view details for any version with full scroll support
 - **🛠 MODEL_NOT_FOUND Rotation** — If a specific provider returns a 404 for a model, the TUI intelligently rotates through other available providers for the same model.
@@ -89,7 +89,7 @@ By Vanessa Depraute
 - **🎮 Interactive selection** — Navigate with arrow keys directly in the table, press Enter to act
 - **💻 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.
+- **🧰 Public tool launchers** — `Enter` auto-configures and launches all 13 tool modes: `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 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
@@ -182,13 +182,11 @@ bunx free-coding-models YOUR_API_KEY
 
 ### 🆕 What's New
 
-**Version 0.3.3 switches Claude Code to the exact `free-claude-code` pattern instead of injecting FCM slugs into Claude itself:**
+**Version 0.3.5 fixes the main Claude Code proxy compatibility bug found in real-world use:**
 
-- **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.
+- **Claude Code beta-route requests now work** — the proxy accepts Anthropic URLs like `/v1/messages?beta=true` and `/v1/messages/count_tokens?beta=true`, which is how recent Claude Code builds really call the API.
+- **Claude proxy flow now behaves like `free-claude-code` on the routing layer** — fake Claude model ids still map proxy-side to the selected free backend model, but the route matcher no longer breaks before that mapping can run.
+- **The fix was validated against the real `claude` binary** — not just unit tests. The exact failure `selected model (claude-sonnet-4-6) may not exist` is now gone in local end-to-end repro.
 
 ---
 
@@ -246,7 +244,7 @@ Running `free-coding-models` with no launcher flag starts in **OpenCode CLI** mo
 - The active target is always visible in the header badge before you press `Enter`
 
 **How it works:**
- 1. **Ping phase** — All enabled models are pinged in parallel (up to 159 across 20 providers)
+ 1. **Ping phase** — All enabled models are pinged in parallel (up to 160 across 20 providers)
  2. **Continuous monitoring** — Models start at 2s re-pings for 60s, then fall back to 10s automatically, and slow to 30s after 5 minutes idle unless you force 4s mode with `W`
 3. **Real-time updates** — Watch "Latest", "Avg", and "Up%" columns update live
 4. **Select anytime** — Use ↑↓ arrows to navigate, press Enter on a model to act
@@ -429,7 +427,7 @@ TOGETHER_API_KEY=together_xxx free-coding-models
 
 ## 🤖 Coding Models
 
-**159 coding models** across 20 providers and 8 tiers, ranked by [SWE-bench Verified](https://www.swebench.com) — the industry-standard benchmark measuring real GitHub issue resolution. Scores are self-reported by providers unless noted.
+**160 coding models** across 20 providers and 8 tiers, ranked by [SWE-bench Verified](https://www.swebench.com) — the industry-standard benchmark measuring real GitHub issue resolution. Scores are self-reported by providers unless noted.
 
 ### Alibaba Cloud (DashScope) (8 models)
 
@@ -513,7 +511,6 @@ The main table displays one row per model with the following columns:
 | **Stability** | `B` | Composite 0–100 consistency score (see [Stability Score](#-stability-score)) |
 | **Up%** | `U` | Uptime — percentage of successful pings |
 | **Used** | — | Total prompt+completion tokens consumed in logs for this exact provider/model pair, shown in `k` or `M` |
-| **Usage** | `G` | Provider-scoped quota remaining when measurable; otherwise a green dot means usage % is not applicable/reliable for that provider |
 
 ### Verdict values
 
@@ -602,6 +599,8 @@ free-coding-models daemon uninstall   # Remove OS service completely
 free-coding-models daemon logs        # Show recent service logs
 ```
 
+For a quick browser sanity-check, open [http://127.0.0.1:18045/](http://127.0.0.1:18045/) or [http://127.0.0.1:18045/v1/health](http://127.0.0.1:18045/v1/health) while the proxy is running.
+
 ### Service management
 
 The dedicated **FCM Proxy V2** overlay (accessible via `J` from main TUI, or Settings → Enter) provides full control:

package/bin/free-coding-models.js

@@ -271,6 +271,18 @@ async function main() {
       console.log()
       process.exit(result.success ? 0 : 1)
     }
+    if (daemonSubcmd === 'stop') {
+      const result = dm.stopDaemon()
+      console.log()
+      if (result.success) {
+        console.log(chalk.greenBright('  ✅ FCM Proxy V2 service stopped.'))
+        console.log(chalk.dim('  The service stays installed and can be restarted later.'))
+      } else {
+        console.log(chalk.red(`  ❌ Stop failed: ${result.error}`))
+      }
+      console.log()
+      process.exit(result.success ? 0 : 1)
+    }
     if (daemonSubcmd === 'logs') {
       const logPath = dm.getDaemonLogPath()
       console.log(chalk.dim(`  Log file: ${logPath}`))
@@ -283,7 +295,7 @@ async function main() {
       process.exit(0)
     }
     console.log(chalk.red(`  Unknown command: ${daemonSubcmd}`))
-    console.log(chalk.dim('  Usage: free-coding-models daemon [status|install|uninstall|restart|logs]'))
+    console.log(chalk.dim('  Usage: free-coding-models daemon [status|install|uninstall|restart|stop|logs]'))
     process.exit(1)
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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

@@ -4,7 +4,7 @@
  * and OpenAI Chat Completions API.
  *
  * 📖 This is the key module that enables Claude Code to work natively through the
- *    FCM proxy without needing the external "free-claude-code" Python proxy.
+ *    FCM proxy without needing the external Claude proxy integration.
  *    Claude Code sends requests in Anthropic format (POST /v1/messages) and this
  *    module translates them to OpenAI format for the upstream providers, then
  *    translates the responses back.

package/src/cli-help.js

@@ -40,6 +40,7 @@ const COMMANDS = [
   { 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 stop', description: 'Gracefully stop the background service without uninstalling it' },
   { command: 'daemon logs', description: 'Print the latest daemon log lines' },
 ]
 
@@ -70,7 +71,7 @@ export function buildCliHelpLines({ chalk = null, indent = '', title = 'CLI Help
 
   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(`${indent}${paint(chalk, chalk?.dim, '       free-coding-models daemon [status|install|uninstall|restart|stop|logs]')}`)
   lines.push('')
   lines.push(`${indent}${paint(chalk, chalk?.bold, 'Tool Flags')}`)
   for (const entry of launchFlags) {

package/src/config.js

@@ -183,10 +183,10 @@ export function loadConfig() {
     try {
       const raw = readFileSync(CONFIG_PATH, 'utf8').trim()
       const parsed = JSON.parse(raw)
-      // 📖 Ensure the shape is always complete — fill missing sections with defaults
-      if (!parsed.apiKeys) parsed.apiKeys = {}
-      if (!parsed.providers) parsed.providers = {}
-      if (!parsed.settings || typeof parsed.settings !== 'object') parsed.settings = {}
+      // 📖 Ensure the shape is always complete — fill missing or corrupted sections with defaults.
+      if (!parsed.apiKeys || typeof parsed.apiKeys !== 'object' || Array.isArray(parsed.apiKeys)) parsed.apiKeys = {}
+      if (!parsed.providers || typeof parsed.providers !== 'object' || Array.isArray(parsed.providers)) parsed.providers = {}
+      if (!parsed.settings || typeof parsed.settings !== 'object' || Array.isArray(parsed.settings)) parsed.settings = {}
       if (typeof parsed.settings.hideUnconfiguredModels !== 'boolean') parsed.settings.hideUnconfiguredModels = true
       parsed.settings.proxy = normalizeProxySettings(parsed.settings.proxy)
       // 📖 Favorites: list of "providerKey/modelId" pinned rows.
@@ -443,9 +443,11 @@ export function validateConfigFile(options = {}) {
       throw new Error('Config is not a valid object')
     }
 
-    // 📖 Check for critical corruption (apiKeys should be an object if it exists)
-    if (parsed.apiKeys !== null && parsed.apiKeys !== undefined && typeof parsed.apiKeys !== 'object') {
-      throw new Error('apiKeys field is corrupted')
+    // 📖 Check for critical corruption (apiKeys should be an object if it exists).
+    // 📖 Treat this as recoverable — loadConfig() will normalize the value safely.
+    if (parsed.apiKeys !== null && parsed.apiKeys !== undefined
+      && (typeof parsed.apiKeys !== 'object' || Array.isArray(parsed.apiKeys))) {
+      console.warn('⚠️  apiKeys field malformed; it will be normalized on load')
     }
 
     return { valid: true }

package/src/opencode.js

@@ -577,7 +577,7 @@ export async function ensureProxyRunning(fcmConfig, { forceRestart = false } = {
 
   // 📖 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.
+  // 📖 Claude proxy model than spinning up tool-specific local proxies.
   try {
     const daemonRunning = await isDaemonRunning()
     if (daemonRunning) {

package/src/proxy-server.js

@@ -108,6 +108,21 @@ function sendJson(res, statusCode, body) {
   res.end(json)
 }
 
+/**
+ * 📖 Match routes on the URL pathname only so Claude Code's `?beta=true`
+ * 📖 Anthropic requests resolve exactly like FastAPI routes do in free-claude-code.
+ *
+ * @param {http.IncomingMessage} req
+ * @returns {string}
+ */
+function getRequestPathname(req) {
+  try {
+    return new URL(req.url || '/', 'http://127.0.0.1').pathname || '/'
+  } catch {
+    return req.url || '/'
+  }
+}
+
 function normalizeRequestedModel(modelId) {
   if (typeof modelId !== 'string') return null
   const trimmed = modelId.trim()
@@ -303,8 +318,16 @@ export class ProxyServer {
   // ── Request routing ────────────────────────────────────────────────────────
 
   _handleRequest(req, res) {
+    const pathname = getRequestPathname(req)
+
+    // 📖 Root endpoint is unauthenticated so a browser hit on http://127.0.0.1:{port}/
+    // 📖 gives a useful status payload instead of a misleading Unauthorized error.
+    if (req.method === 'GET' && pathname === '/') {
+      return this._handleRoot(res)
+    }
+
     // 📖 Health endpoint is unauthenticated so external monitors can probe it
-    if (req.method === 'GET' && req.url === '/v1/health') {
+    if (req.method === 'GET' && pathname === '/v1/health') {
       return this._handleHealth(res)
     }
 
@@ -313,11 +336,11 @@ export class ProxyServer {
       return sendJson(res, 401, { error: 'Unauthorized' })
     }
 
-    if (req.method === 'GET' && req.url === '/v1/models') {
+    if (req.method === 'GET' && pathname === '/v1/models') {
       this._handleModels(res)
-    } else if (req.method === 'GET' && req.url === '/v1/stats') {
+    } else if (req.method === 'GET' && pathname === '/v1/stats') {
       this._handleStats(res)
-    } else if (req.method === 'POST' && req.url === '/v1/chat/completions') {
+    } else if (req.method === 'POST' && pathname === '/v1/chat/completions') {
       this._handleChatCompletions(req, res).catch(err => {
         console.error('[proxy] Internal error:', err)
         // 📖 Return 413 for body-too-large, generic 500 for everything else — never leak stack traces
@@ -325,7 +348,7 @@ export class ProxyServer {
         const msg = err.statusCode === 413 ? 'Request body too large' : 'Internal server error'
         sendJson(res, status, { error: msg })
       })
-    } else if (req.method === 'POST' && req.url === '/v1/messages') {
+    } else if (req.method === 'POST' && pathname === '/v1/messages') {
       // 📖 Anthropic Messages API translation — enables Claude Code compatibility
       this._handleAnthropicMessages(req, res, authContext).catch(err => {
         console.error('[proxy] Internal error:', err)
@@ -333,26 +356,26 @@ export class ProxyServer {
         const msg = err.statusCode === 413 ? 'Request body too large' : 'Internal server error'
         sendJson(res, status, { error: msg })
       })
-    } else if (req.method === 'POST' && req.url === '/v1/messages/count_tokens') {
+    } else if (req.method === 'POST' && pathname === '/v1/messages/count_tokens') {
       this._handleAnthropicCountTokens(req, res).catch(err => {
         console.error('[proxy] Internal error:', err)
         const status = err.statusCode === 413 ? 413 : 500
         const msg = err.statusCode === 413 ? 'Request body too large' : 'Internal server error'
         sendJson(res, status, { error: msg })
       })
-    } else if (req.method === 'POST' && req.url === '/v1/responses') {
+    } else if (req.method === 'POST' && pathname === '/v1/responses') {
       this._handleResponses(req, res).catch(err => {
         console.error('[proxy] Internal error:', err)
         const status = err.statusCode === 413 ? 413 : 500
         const msg = err.statusCode === 413 ? 'Request body too large' : 'Internal server error'
         sendJson(res, status, { error: msg })
       })
-    } else if (req.method === 'POST' && req.url === '/v1/completions') {
+    } else if (req.method === 'POST' && pathname === '/v1/completions') {
       // These legacy/alternative OpenAI endpoints are not supported by the proxy.
       // Return 501 (not 404) so callers get a clear signal instead of silently failing.
       sendJson(res, 501, {
         error: 'Not Implemented',
-        message: `${req.url} is not supported by this proxy. Use POST /v1/chat/completions instead.`,
+        message: `${pathname} is not supported by this proxy. Use POST /v1/chat/completions instead.`,
       })
     } else {
       sendJson(res, 404, { error: 'Not found' })
@@ -780,6 +803,26 @@ export class ProxyServer {
 
   // ── GET /v1/health ──────────────────────────────────────────────────────────
 
+  /**
+   * 📖 Friendly unauthenticated landing endpoint for browsers and quick local checks.
+   */
+  _handleRoot(res) {
+    const status = this.getStatus()
+    const uniqueModels = new Set(this._accounts.map(acct => acct.proxyModelId || acct.modelId)).size
+    sendJson(res, 200, {
+      status: 'ok',
+      service: 'fcm-proxy-v2',
+      running: status.running,
+      accountCount: status.accountCount,
+      modelCount: uniqueModels,
+      endpoints: {
+        health: '/v1/health',
+        models: '/v1/models',
+        stats: '/v1/stats',
+      },
+    })
+  }
+
   /**
    * 📖 Health endpoint for daemon liveness checks. Unauthenticated so external
    * monitors (TUI, launchctl, systemd) can probe without needing the token.

package/src/proxy-sync.js

@@ -34,7 +34,7 @@ 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.
-// 📖 Claude Code is excluded too: its free-claude-code style integration is
+// 📖 Claude proxy 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',

package/src/proxy-topology.js

@@ -67,7 +67,7 @@ export function buildProxyTopologyFromConfig(fcmConfig, mergedModels, sourcesMap
   return {
     accounts,
     proxyModels,
-    // 📖 Mirror free-claude-code: proxy-side Claude family routing is config-driven.
+    // 📖 Mirror Claude proxy: proxy-side Claude family routing is config-driven.
     anthropicRouting: getProxySettings(fcmConfig).anthropicRouting,
   }
 }

package/src/tool-launchers.js

@@ -19,7 +19,7 @@
  *   📖 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: mirrors free-claude-code by keeping fake Claude model ids on the client,
+ *   📖 Claude Code: mirrors Claude proxy 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
@@ -27,7 +27,7 @@
  *
  * @functions
  *   → `resolveLauncherModelId` — choose the provider-specific id or proxy slug for a launch
- *   → `waitForClaudeProxyRouting` — wait until the daemon/proxy has reloaded the free-claude-code style Claude-family mapping
+ *   → `waitForClaudeProxyRouting` — wait until the daemon/proxy has reloaded the Claude proxy 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
@@ -646,7 +646,7 @@ export async function startExternalTool(mode, model, config) {
   }
 
   if (mode === 'claude-code') {
-    // 📖 Mirror free-claude-code exactly on the client side:
+    // 📖 Mirror Claude proxy 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)