free-coding-models 0.2.4 → 0.2.8

package/README.md

@@ -103,15 +103,43 @@ Before using `free-coding-models`, make sure you have:
 
 1. **Node.js 18+** — Required for native `fetch` API
 2. **At least one free API key** — pick any or all of:
-   - **NVIDIA NIM** — [build.nvidia.com](https://build.nvidia.com) → Profile → API Keys → Generate
-   - **Groq** — [console.groq.com/keys](https://console.groq.com/keys) → Create API Key
-   - **Cerebras** — [cloud.cerebras.ai](https://cloud.cerebras.ai) → API Keys → Create
+   - **NVIDIA NIM** — [build.nvidia.com](https://build.nvidia.com) → Profile → API Keys → Generate – free tier: 40 req/min (no credit card)
+   - **Groq** — [console.groq.com/keys](https://console.groq.com/keys) → Create API Key – free tier: 30‑50 RPM per model (varies)
+   - **Cerebras** — [cloud.cerebras.ai](https://cloud.cerebras.ai) → API Keys → Create – free tier: generous (developer tier 10× higher limits)
    - **SambaNova** — [sambanova.ai/developers](https://sambanova.ai/developers) → Developers portal → API key (dev tier generous)
-   - **OpenRouter** — [openrouter.ai/keys](https://openrouter.ai/keys) → Create key (50 req/day, 20/min on `:free`)
+   - **OpenRouter** — [openrouter.ai/keys](https://openrouter.ai/keys) → Create key (free requests on `:free` models, see details below)
+
+### OpenRouter Free Tier Details
+
+OpenRouter provides free requests on free models (`:free`):
+
+```
+──────────────────────────────────────────────────
+  OpenRouter — Free requests on free models (:free)
+──────────────────────────────────────────────────
+
+  No credits (or <$10)   →   50  requests / day   (20 req/min)
+  ≥ $10 in credits      →  1000 requests / day   (20 req/min)
+
+──────────────────────────────────────────────────
+Key things to know:
+
+  • Free models (:free) never consume your credits.
+    Your $10 stays untouched if you only use :free models.
+
+  • Failed requests still count toward your daily quota.
+
+  • Quota resets every day at midnight UTC.
+
+  • Free-tier popular models may be additionally rate-limited
+    by the provider itself during peak hours.
+──────────────────────────────────────────────────
+```
+
    - **Hugging Face Inference** — [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) → Access Tokens (free monthly credits)
-   - **Replicate** — [replicate.com/account/api-tokens](https://replicate.com/account/api-tokens) → Create token (dev quota)
-   - **DeepInfra** — [deepinfra.com/login](https://deepinfra.com/login) → Login → API key (free dev tier)
-   - **Fireworks AI** — [fireworks.ai](https://fireworks.ai) → Settings → Access Tokens ($1 free credits)
+   - **Replicate** — [replicate.com/account/api-tokens](https://replicate.com/account/api-tokens) → Create token – free tier: 6 req/min (no payment) – up to 3,000 RPM (API) / 600 RPM (predictions) with payment
+   - **DeepInfra** — [deepinfra.com/login](https://deepinfra.com/login) → Login → API key – free tier: 200 concurrent requests (default)
+   - **Fireworks AI** — [fireworks.ai](https://fireworks.ai) → Settings → Access Tokens – $1 free credits; 10 req/min without payment (full limits with payment)
    - **Mistral Codestral** — [codestral.mistral.ai](https://codestral.mistral.ai) → API Keys (30 req/min, 2000/day — phone required)
    - **Hyperbolic** — [app.hyperbolic.ai/settings](https://app.hyperbolic.ai/settings) → API Keys ($1 free trial)
    - **Scaleway** — [console.scaleway.com/iam/api-keys](https://console.scaleway.com/iam/api-keys) → IAM → API Keys (1M free tokens)
@@ -146,6 +174,18 @@ pnpx free-coding-models YOUR_API_KEY
 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`
+
+- **Provider colors everywhere** — Provider names are now colored consistently in logs, settings, and the main table for better visual recognition
+
 ---
 
 ## 🚀 Usage
@@ -173,6 +213,11 @@ 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)
+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
+
  # Filter models by tier letter
 free-coding-models --tier S          # S+ and S only
 free-coding-models --tier A          # A+, A, A- only
@@ -182,6 +227,7 @@ free-coding-models --tier C          # C only
 # Combine flags freely
 free-coding-models --openclaw --tier S
 free-coding-models --opencode --best
+free-coding-models --tier S --json
 ```
 
 ### Choosing the target tool
@@ -241,7 +287,7 @@ Press **`P`** to open the Settings screen at any time:
   Providers
 
   ❯ [ ✅ ] NVIDIA NIM              nvapi-••••••••••••3f9a  [Test ✅]  Free tier (provider quota by model)
-    [ ✅ ] OpenRouter              (no key set)            [Test —]   50 req/day, 20/min (:free shared quota)
+    [ ✅ ] OpenRouter              (no key set)            [Test —]   Free on :free (50/day <$10, 1000/day ≥$10)
     [ ✅ ] Hugging Face Inference  (no key set)            [Test —]   Free monthly credits (~$0.10)
 
   Setup Instructions — NVIDIA NIM
@@ -834,6 +880,7 @@ This script:
 | `--goose` | Goose mode — Enter launches Goose with env-based provider config |
 | `--best` | Show only top-tier models (A+, S, S+) |
 | `--fiable` | Analyze 10 seconds, output the most reliable model as `provider/model_id` |
+| `--json` | Output results as JSON (for scripting/automation, CI/CD, dashboards) |
 | `--tier S` | Show only S+ and S tier models |
 | `--tier A` | Show only A+, A, A- tier models |
 | `--tier B` | Show only B+, B tier models |
@@ -851,7 +898,8 @@ This script:
 - **D** — Cycle provider filter (All → NIM → Groq → ...)
 - **E** — Toggle configured-only mode (on by default, persisted across sessions and profiles)
 - **Z** — Cycle target tool (OpenCode CLI → OpenCode Desktop → OpenClaw → Crush → Goose)
-- **X** — Toggle request logs (recent proxied request/token usage logs)
+- **X** — Toggle request logs (recent proxied request/token usage logs, up to 500 entries)
+- **A (in logs)** — Toggle between showing 500 entries or ALL logs
 - **P** — Open Settings (manage API keys, toggles, updates, profiles)
 - **Y** — Open Install Endpoints (`provider → tool → all models` or `selected models only`, no proxy)
 - **Shift+P** — Cycle through saved profiles (switches live TUI settings)

package/bin/free-coding-models.js

@@ -77,6 +77,7 @@
  *   - --crush / --goose: launch the currently selected model in the supported external CLI
  *   - --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)
  *   - --no-telemetry: Disable anonymous usage analytics for this run
  *   - --tier S/A/B/C: Filter models by tier letter (S=S+/S, A=A+/A/A-, B=B+/B, C=C)
  *
@@ -92,7 +93,7 @@ import { randomUUID } from 'crypto'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
 import { MODELS, sources } from '../sources.js'
-import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS, formatCtxWindow, labelFromId, getProxyStatusInfo } from '../src/utils.js'
+import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS, formatCtxWindow, labelFromId, getProxyStatusInfo, formatResultsAsJSON } from '../src/utils.js'
 import { loadConfig, saveConfig, getApiKey, getProxySettings, resolveApiKeys, addApiKey, removeApiKey, isProviderEnabled, saveAsProfile, loadProfile, listProfiles, deleteProfile, getActiveProfileName, setActiveProfile, _emptyProfileSettings } from '../src/config.js'
 import { buildMergedModels } from '../src/model-merger.js'
 import { ProxyServer } from '../src/proxy-server.js'
@@ -112,7 +113,7 @@ import { ensureFavoritesConfig, toFavoriteKey, syncFavoriteFlags, toggleFavorite
 import { checkForUpdateDetailed, checkForUpdate, runUpdate, promptUpdateNotification } from '../src/updater.js'
 import { promptApiKey } from '../src/setup.js'
 import { stripAnsi, maskApiKey, displayWidth, padEndDisplay, tintOverlayLines, keepOverlayTargetVisible, sliceOverlayLines, calculateViewport, sortResultsWithPinnedFavorites, renderProxyStatusLine, adjustScrollOffset } from '../src/render-helpers.js'
-import { renderTable } from '../src/render-table.js'
+import { renderTable, PROVIDER_COLOR } from '../src/render-table.js'
 import { setOpenCodeModelData, startOpenCode, startOpenCodeDesktop, startProxyAndLaunch, autoStartProxyIfSynced, ensureProxyRunning, buildProxyTopologyFromConfig, isProxyEnabledForConfig } from '../src/opencode.js'
 import { startOpenClaw } from '../src/openclaw.js'
 import { createOverlayRenderers } from '../src/overlays.js'
@@ -120,6 +121,8 @@ import { createKeyHandler } from '../src/key-handler.js'
 import { getToolModeOrder } from '../src/tool-metadata.js'
 import { startExternalTool } from '../src/tool-launchers.js'
 import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../src/endpoint-installer.js'
+import { loadCache, saveCache, clearCache, getCacheAge } from '../src/cache.js'
+import { checkConfigSecurity } from '../src/security.js'
 
 // 📖 mergedModels: cross-provider grouped model list (one entry per label, N providers each)
 // 📖 mergedModelByLabel: fast lookup map from display label → merged model entry
@@ -180,6 +183,12 @@ async function main() {
   ensureTelemetryConfig(config)
   ensureFavoritesConfig(config)
 
+  // 📖 Check config file security — warn and offer auto-fix if permissions are too open
+  const securityCheck = checkConfigSecurity()
+  if (!securityCheck.wasSecure && !securityCheck.wasFixed) {
+    // 📖 User declined auto-fix or it failed — continue anyway, just warned
+  }
+
   if (cliArgs.cleanProxyMode) {
     const cleaned = cleanupOpenCodeProxyConfig()
     console.log()
@@ -453,6 +462,7 @@ async function main() {
     // 📖 Log page overlay state (X key opens it)
     logVisible: false,            // 📖 Whether the log page overlay is active
     logScrollOffset: 0,           // 📖 Vertical scroll offset for log overlay viewport
+    logShowAll: false,             // 📖 Show all logs (true) or limited to 500 (false)
     // 📖 Proxy startup status — set by autoStartProxyIfSynced, consumed by Task 3 indicator
     // 📖 null = not configured/not attempted
     // 📖 { phase: 'starting' } — proxy start in progress
@@ -533,11 +543,78 @@ async function main() {
     void autoStartProxyIfSynced(config, state)
   }
 
+  // 📖 Load cache if available (for faster startup with cached ping results)
+  const cached = loadCache()
+  if (cached && cached.models) {
+    // 📖 Apply cached values to results
+    for (const r of state.results) {
+      const cachedModel = cached.models[r.modelId]
+      if (cachedModel) {
+        r.avg = cachedModel.avg
+        r.p95 = cachedModel.p95
+        r.jitter = cachedModel.jitter
+        r.stability = cachedModel.stability
+        r.uptime = cachedModel.uptime
+        r.verdict = cachedModel.verdict
+        r.status = cachedModel.status
+        r.httpCode = cachedModel.httpCode
+        r.pings = cachedModel.pings || []
+      }
+    }
+  }
+
+  // 📖 JSON output mode: skip TUI, output results as JSON after initial pings
+  if (cliArgs.jsonMode) {
+    console.log(chalk.cyan('  ⚡ Pinging models for JSON output...'))
+    console.log()
+
+    // 📖 Run initial pings
+    const initialPing = Promise.all(state.results.map(r => pingModel(r)))
+    await initialPing
+
+    // 📖 Calculate final stats
+    state.results.forEach(r => {
+      r.avg = getAvg(r)
+      r.p95 = getP95(r)
+      r.jitter = getJitter(r)
+      r.stability = getStabilityScore(r)
+      r.uptime = getUptime(r)
+      r.verdict = getVerdict(r)
+    })
+
+    // 📖 Apply tier filter if specified
+    let outputResults = state.results
+    if (cliArgs.tierFilter) {
+      const filteredTier = TIER_LETTER_MAP[cliArgs.tierFilter]
+      if (filteredTier) {
+        outputResults = state.results.filter(r => filteredTier.includes(r.tier))
+      }
+    }
+
+    // 📖 Apply best mode filter if specified
+    if (cliArgs.bestMode) {
+      outputResults = outputResults.filter(r => ['S+', 'S', 'A+'].includes(r.tier))
+    }
+
+    // 📖 Sort by avg ping (ascending)
+    outputResults = sortResults(outputResults, 'avg', 'asc')
+
+    // 📖 Output JSON
+    console.log(formatResultsAsJSON(outputResults))
+
+    // 📖 Save cache before exiting
+    saveCache(state.results, state.pingMode)
+
+    process.exit(0)
+  }
+
   // 📖 Enter alternate screen — animation runs here, zero scrollback pollution
   process.stdout.write(ALT_ENTER)
 
   // 📖 Ensure we always leave alt screen cleanly (Ctrl+C, crash, normal exit)
   const exit = (code = 0) => {
+    // 📖 Save cache before exiting so next run starts faster
+    saveCache(state.results, state.pingMode)
     clearInterval(ticker)
     clearTimeout(state.pingIntervalObj)
     process.stdout.write(ALT_LEAVE)
@@ -590,6 +667,7 @@ async function main() {
     chalk,
     sources,
     PROVIDER_METADATA,
+    PROVIDER_COLOR,
     LOCAL_VERSION,
     getApiKey,
     getProxySettings,
@@ -849,6 +927,9 @@ async function main() {
 
   await initialPing
 
+  // 📖 Save cache after initial pings complete for faster next startup
+  saveCache(state.results, state.pingMode)
+
   // 📖 Keep interface running forever - user can select anytime or Ctrl+C to exit
   // 📖 The pings continue running in background with dynamic interval
   // 📖 User can press W to decrease interval (faster pings) or = to increase (slower)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.2.4",
+  "version": "0.2.8",
   "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",
@@ -45,7 +45,8 @@
     "patch-openclaw.js",
     "patch-openclaw-models.js",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "start": "node bin/free-coding-models.js",
@@ -56,5 +57,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@mariozechner/terminalcp": "^1.3.3"
   }
 }

package/sources.js

@@ -146,7 +146,14 @@ export const sambanova = [
 ]
 
 // 📖 OpenRouter source - https://openrouter.ai
-// 📖 Free :free models with shared quota — 50 free req/day
+// 📖 Free :free models with shared quota — 50 free req/day (20 req/min)
+// 📖 No credits (or < $10) → 50 requests / day (20 req/min)
+// 📖 ≥ $10 in credits → 1000 requests / day (20 req/min)
+// 📖 Key things to know:
+// 📖 • Free models (:free) never consume your credits. Your $10 stays untouched if you only use :free models.
+// 📖 • Failed requests still count toward your daily quota.
+// 📖 • Quota resets every day at midnight UTC.
+// 📖 • Free-tier popular models may be additionally rate-limited by the provider itself during peak hours.
 // 📖 API keys at https://openrouter.ai/keys
 export const openrouter = [
   ['qwen/qwen3-coder:free',                    'Qwen3 Coder 480B',   'S+', '70.6%', '262k'],

package/src/analysis.js

@@ -39,6 +39,7 @@ import { MODELS, sources } from '../sources.js'
 import { findBestModel, filterByTier, formatCtxWindow, labelFromId, TIER_LETTER_MAP } from '../src/utils.js'
 import { isProviderEnabled, getApiKey } from '../src/config.js'
 import { ping } from '../src/ping.js'
+import { PROVIDER_COLOR } from './render-table.js'
 import chalk from 'chalk'
 
 // 📖 runFiableMode: Analyze models for reliability over 10 seconds, output the best one.
@@ -99,7 +100,10 @@ export async function runFiableMode(config) {
   // 📖 Output in format: providerName/modelId
   const providerName = sources[best.providerKey]?.name ?? best.providerKey ?? 'nvidia'
   console.log(chalk.green(`  ✓ Most reliable model:`))
-  console.log(chalk.bold(`    ${providerName}/${best.modelId}`))
+  // 📖 Color provider name the same way as in the main table
+  const providerRgb = PROVIDER_COLOR[best.providerKey] ?? [105, 190, 245]
+  const coloredProviderName = chalk.bold.rgb(...providerRgb)(providerName)
+  console.log(`    ${coloredProviderName}/${best.modelId}`)
   console.log()
   console.log(chalk.dim(`  📊 Stats:`))
   const { getAvg, getUptime } = await import('./utils.js')

package/src/cache.js

@@ -0,0 +1,165 @@
+/**
+ * @file cache.js
+ * @description Persistent cache for ping results to speed up startup.
+ *
+ * 📖 Cache file location: ~/.free-coding-models.cache.json
+ * 📖 File permissions: 0o600 (user read/write only — contains API timing data)
+ *
+ * 📖 Why caching matters:
+ *    - Ping results don't change dramatically within 5 minutes
+ *    - Repeated runs start instantly instead of waiting 10+ seconds
+ *    - Fewer API rate limit hits for providers
+ *
+ * 📖 Cache structure:
+ *   {
+ *     "timestamp": 1712345678901,           // Last cache write time (ms since epoch)
+ *     "models": {
+ *       "nvidia/deepseek-v3.2": {
+ *         "avg": 245,
+ *         "p95": 312,
+ *         "jitter": 45,
+ *         "stability": 87,
+ *         "uptime": 95.5,
+ *         "verdict": "Perfect",
+ *         "status": "up",
+ *         "httpCode": "200",
+ *         "pings": [
+ *           { "ms": 230, "code": "200" },
+ *           { "ms": 260, "code": "200" }
+ *         ]
+ *       }
+ *     },
+ *     "providerTier": "normal"              // Ping cadence: "fast" | "normal" | "slow"
+ *   }
+ *
+ * 📖 Cache TTL (time-to-live):
+ *    - 5 minutes (300,000ms) for normal operations
+ *    - Stale cache is ignored and models are re-pinged
+ *
+ * @functions
+ *   → getCachePath() — Returns the cache file path
+ *   → loadCache() — Reads cache from disk, returns null if missing/stale
+ *   → saveCache(results, providerTier) — Writes current results to cache
+ *   → clearCache() — Deletes cache file (useful for testing)
+ *   → isCacheFresh(cache) — Checks if cache is within TTL
+ *
+ * @exports getCachePath, loadCache, saveCache, clearCache, isCacheFresh
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+// 📖 Cache TTL: 5 minutes in milliseconds
+// 📖 Ping results are considered fresh for this duration
+const CACHE_TTL = 5 * 60 * 1000
+
+// 📖 Get cache file path — platform-aware home directory resolution
+export function getCachePath() {
+  const homeDir = os.homedir()
+  return path.join(homeDir, '.free-coding-models.cache.json')
+}
+
+// 📖 Load cache from disk if it exists and is valid JSON
+// 📖 Returns null if file doesn't exist, is invalid JSON, or is stale
+export function loadCache() {
+  const cachePath = getCachePath()
+
+  try {
+    if (!fs.existsSync(cachePath)) {
+      return null
+    }
+
+    const raw = fs.readFileSync(cachePath, 'utf-8')
+    const cache = JSON.parse(raw)
+
+    // 📖 Validate cache structure — must have timestamp and models object
+    if (!cache || typeof cache !== 'object' || !cache.timestamp || !cache.models) {
+      return null
+    }
+
+    // 📖 Check if cache is stale (older than TTL)
+    if (!isCacheFresh(cache)) {
+      return null
+    }
+
+    return cache
+  } catch (err) {
+    // 📖 Silently fail on parse errors — cache is optional
+    return null
+  }
+}
+
+// 📖 Save current ping results to cache
+// 📖 results: Array of model result objects from the TUI
+// 📖 providerTier: Current ping cadence ("fast" | "normal" | "slow")
+export function saveCache(results, providerTier = 'normal') {
+  const cachePath = getCachePath()
+
+  try {
+    const models = {}
+
+    // 📖 Extract relevant data from each result object
+    for (const result of results) {
+      if (!result.modelId) continue
+
+      models[result.modelId] = {
+        avg: result.avg,
+        p95: result.p95,
+        jitter: result.jitter,
+        stability: result.stability,
+        uptime: result.uptime,
+        verdict: result.verdict,
+        status: result.status,
+        httpCode: result.httpCode,
+        // 📖 Only save last 20 pings to keep cache file small
+        pings: (result.pings || []).slice(-20)
+      }
+    }
+
+    const cache = {
+      timestamp: Date.now(),
+      models,
+      providerTier
+    }
+
+    // 📖 Write with secure permissions (user read/write only)
+    fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2), { mode: 0o600 })
+  } catch (err) {
+    // 📖 Silently fail on write errors — caching is optional
+  }
+}
+
+// 📖 Check if cache is within TTL (fresh) or expired (stale)
+export function isCacheFresh(cache) {
+  if (!cache || typeof cache.timestamp !== 'number') return false
+
+  const age = Date.now() - cache.timestamp
+  return age < CACHE_TTL
+}
+
+// 📖 Clear cache file — useful for testing or forcing fresh pings
+export function clearCache() {
+  const cachePath = getCachePath()
+
+  try {
+    if (fs.existsSync(cachePath)) {
+      fs.unlinkSync(cachePath)
+    }
+  } catch (err) {
+    // 📖 Silently fail — cache is optional
+  }
+}
+
+// 📖 Get cache age in human-readable format (for debugging)
+export function getCacheAge(cache) {
+  if (!cache || typeof cache.timestamp !== 'number') return null
+
+  const ageMs = Date.now() - cache.timestamp
+  const ageSec = Math.floor(ageMs / 1000)
+
+  if (ageSec < 60) return `${ageSec}s`
+  if (ageSec < 3600) return `${Math.floor(ageSec / 60)}m`
+  return `${Math.floor(ageSec / 3600)}h`
+}