free-coding-models 0.3.19 → 0.3.22

package/CHANGELOG.md

@@ -1,7 +1,50 @@
 # Changelog
-
 ---
 
+## 0.3.22
+
+### Added
+- **Hierarchical command palette navigation**: Ctrl+P now opens an improved command palette with expandable/collapsible categories and subcategories for better organization.
+- **Arrow key navigation in command palette**: Use left/right arrows to expand and collapse categories, up/down to navigate, Enter to execute or toggle.
+- **Rich color scheme for command palette**: Categories use bold blue headers, subcategories use bold text, commands show keyboard shortcuts.
+- **Visual expand/collapse indicators**: ▼ shows expanded categories, ▶ shows collapsed, • marks individual commands.
+- **Concise default view**: Categories are collapsed by default (except Filters) showing less detail on first open.
+- **Colored tier filters**: Tier filters (S+, S, A+, A, A-, B+, B, C) now display with their corresponding TUI colors for quick identification.
+- **Specific provider filters**: Added 13 individual provider filters (NVIDIA NIM, Groq, Cerebras, SambaNova, OpenRouter, Together AI, DeepInfra, Fireworks, Hyperbolic, Google AI, Hugging Face) with their signature provider colors.
+- **Filter by model category**: New "Filter by model" category with autocomplete that dynamically shows top 20 visible models, complete with provider icons and colored model names.
+- **Improved search cursor**: Cursor placement fixed to appear right after the `>` prompt instead of after placeholder text for natural typing flow.
+- **Lightning bolt in title**: Command Palette title now shows ⚡ emoji for better visibility and visual appeal.
+
+### Changed
+- **Footer layout cleanup**: Added consistent spacing before `F Toggle Favorite`, moved `N Changelog • Ctrl+C Exit` to a dedicated final footer line for better readability.
+- **Removed Y key binding**: Install Endpoints is no longer a direct hotkey — accessible only via Settings (`P`) or Command Palette (`Ctrl+P`). The `Y` key is now free/unbound.
+- **Removed proxy notice from footer**: The "Proxy is temporarily disabled" banner has been fully retired from the TUI footer and its backing constant removed.
+- **Command palette fuzzy search fix**: `buildCommandPaletteEntries()` now expands all categories so child commands are visible to fuzzy search.
+- **Flat Pages + Actions in ⚡️ Command Palette**: page entries and action entries are now listed directly at root level (no extra submenu depth) for faster access.
+- **Command explanations after shortcuts**: command palette rows now show concise English hints after hotkeys (example: `(Z) — Change target AI Coding CLI Tool.`).
+- **⚡️ emoji consistency**: user-facing Command Palette mentions now consistently render as `⚡️ Command Palette` in TUI and docs.
+- **README Quick Start flow**: install section now explicitly adds “create a free account on one of the providers” with a direct anchor link.
+- **Provider section renamed for clarity**: Quick Start provider table now lives under `List of Free AI Providers`.
+- **Quick Start CTA highlight**: added a large green `USE ⚡️ COMMAND PALETTE / CTRL+P` badge right after the command palette instruction.
+
+### Fixed
+- **Double emoji display bug**: Fixed duplicate emoji icons in command palette entries (was showing `▶ 🔍 🔍 Filters` instead of `▶ 🔍 Filters`).
+- **Provider cycle command behavior**: `Cycle provider` in ⚡️ Command Palette now correctly cycles providers again instead of resetting to `All`.
+
+## 0.3.21
+
+### Changed
+- **Responsive table layout**: the TUI now adapts to narrow terminals by progressively shrinking columns and hiding least-useful ones. Compact mode shortens headers (`Lat. P`, `Avg. P`, `StaB.`, `PrOD…`) and tightens Provider (10 cols), Health (13 cols), Latest Ping (10 cols), and Avg Ping (8 cols). Below compact, Rank → Up% → Tier → Stability are hidden one by one. Minimum usable width: ~116 cols.
+- **SWE% column tightened**: reduced from 9 to 6 columns wide — trims excess right padding without losing data.
+- **Provider truncation in compact mode**: provider names longer than 5 chars are truncated to 4 chars + `…` (e.g. `Cere…`).
+- **Health truncation in compact mode**: status text longer than 6 chars is truncated with `…` (e.g. `🔥 429 TR…`).
+- **Removed "Used" column from TUI**: the token usage column has been removed from the main table as it was outdated.
+- **Width guardrail threshold tightened**: the narrow-terminal warning now triggers only below 80 columns (instead of broader widths) and keeps the same 2-second auto-hide behavior.
+- **Width warning is always enforced in narrow terminals**: removed the `Small Width Warnings` Settings toggle and the `--disable-widths-warning` runtime flag so the startup guardrail stays consistent.
+
+### Fixed
+- **`--premium` filter lock-in**: premium now applies a resettable startup preset (S-tier + verdict sort) instead of hard-locking an extra hidden elite-only filter.
+
 ## 0.3.19
 
 ### Added

package/README.md

@@ -22,12 +22,14 @@ npm install -g free-coding-models
 free-coding-models
 ```
 
+create a free account on one of the [providers](#-list-of-free-ai-providers)
+
 </p>
 
 <p align="center">
   <a href="#-why-this-tool">Why</a> •
   <a href="#-quick-start">Quick Start</a> •
-  <a href="#-providers">Providers</a> •
+  <a href="#-list-of-free-ai-providers">Providers</a> •
   <a href="#-usage">Usage</a> •
   <a href="#-tui-keys">TUI Keys</a> •
   <a href="#-contributing">Contributing</a>
@@ -55,7 +57,9 @@ It then writes the model you pick directly into your coding tool's config — so
 
 ## ⚡ Quick Start
 
-**① Get a free API key** — you only need one to get started:
+### 🟢 List of Free AI Providers
+
+Create a free account on one provider below to get started:
 
 **160 coding models** across 20 providers, ranked by [SWE-bench Verified](https://www.swebench.com).
 
@@ -94,7 +98,7 @@ It then writes the model you pick directly into your coding tool's config — so
 | **A-/B+** | 30–40% | Smaller tasks, constrained infra |
 | **B/C** | < 30% | Code completion, edge/minimal setups |
 
-**② Install and run:**
+**① Install and run:**
 
 ```bash
 npm install -g free-coding-models
@@ -103,9 +107,15 @@ free-coding-models
 
 On first run, you'll be prompted to enter your API key(s). You can skip providers and add more later with **`P`**.
 
+Use ⚡️ Command Palette! with **Ctrl+P**.
+
+<p align="center">
+  <img src="https://img.shields.io/badge/USE_%E2%9A%A1%EF%B8%8F%20COMMAND%20PALETTE-CTRL%2BP-22c55e?style=for-the-badge" alt="Use ⚡️ Command Palette with Ctrl+P">
+</p>
+
 Need to fix contrast because your terminal theme is fighting the TUI? Press **`G`** at any time to cycle **Auto → Dark → Light**. The switch recolors the full interface live: table, Settings, Help, Smart Recommend, Feedback, and Changelog.
 
-**③ Pick a model and launch your tool:**
+**② Pick a model and launch your tool:**
 
 ```
 ↑↓ navigate   →   Enter to launch
@@ -133,7 +143,7 @@ free-coding-models --goose --tier S
 # "I want NVIDIA's top models only"
 free-coding-models --origin nvidia --tier S
 
-# "Show me only elite models that are currently healthy"
+# "Start with an elite-focused preset, then adjust filters live"
 free-coding-models --premium
 
 # "I want to script this — give me JSON"
@@ -176,10 +186,9 @@ Press **`Z`** in the TUI to cycle between tools without restarting.
 | `E` | Toggle configured-only mode |
 | `F` | Favorite / unfavorite model |
 | `G` | Cycle global theme (`Auto → Dark → Light`) |
-| `Ctrl+P` | Open command palette (search + run actions) |
+| `Ctrl+P` | Open ⚡️ command palette (search + run actions) |
 | `R/S/C/M/O/L/A/H/V/B/U` | Sort columns |
 | `P` | Settings (API keys, providers, updates, theme) |
-| `Y` | Install Endpoints (push provider into tool config) |
 | `Q` | Smart Recommend overlay |
 | `N` | Changelog |
 | `W` | Cycle ping cadence |
@@ -201,7 +210,7 @@ Press **`Z`** in the TUI to cycle between tools without restarting.
 - **Configured-only default** — only shows providers you have keys for
 - **Keyless latency** — models ping even without an API key (show 🔑 NO KEY)
 - **Smart Recommend** — questionnaire picks the best model for your task type
-- **Command Palette** — `Ctrl+P` opens a searchable action launcher for filters, sorting, overlays, and quick toggles
+- **⚡️ Command Palette** — `Ctrl+P` opens a searchable action launcher for filters, sorting, overlays, and quick toggles
 - **Install Endpoints** — push a full provider catalog into any tool's config (`Y`)
 - **Missing tool bootstrap** — detect absent CLIs, offer one-click install, then continue the selected launch automatically
 - **Width guardrail** — shows a warning instead of a broken table in narrow terminals

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.19",
+  "version": "0.3.22",
   "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/app.js

@@ -105,7 +105,7 @@ import { usageForRow as _usageForRow } from '../src/usage-reader.js'
 import { buildProviderModelTokenKey, loadTokenUsageByProviderModel } from '../src/token-usage-reader.js'
 import { parseOpenRouterResponse, fetchProviderQuota as _fetchProviderQuotaFromModule } from '../src/provider-quota-fetchers.js'
 import { isKnownQuotaTelemetry } from '../src/quota-capabilities.js'
-import { ALT_ENTER, ALT_LEAVE, ALT_HOME, PING_TIMEOUT, PING_INTERVAL, FPS, COL_MODEL, COL_MS, CELL_W, FRAMES, TIER_CYCLE, SETTINGS_OVERLAY_BG, HELP_OVERLAY_BG, RECOMMEND_OVERLAY_BG, OVERLAY_PANEL_WIDTH, TABLE_HEADER_LINES, TABLE_FOOTER_LINES, TABLE_FIXED_LINES, msCell, spinCell } from '../src/constants.js'
+import { ALT_ENTER, ALT_LEAVE, ALT_HOME, PING_TIMEOUT, PING_INTERVAL, FPS, COL_MODEL, COL_MS, CELL_W, FRAMES, TIER_CYCLE, SETTINGS_OVERLAY_BG, HELP_OVERLAY_BG, RECOMMEND_OVERLAY_BG, OVERLAY_PANEL_WIDTH, TABLE_HEADER_LINES, TABLE_FOOTER_LINES, TABLE_FIXED_LINES, WIDTH_WARNING_MIN_COLS, msCell, spinCell } from '../src/constants.js'
 import { TIER_COLOR } from '../src/tier-colors.js'
 import { resolveCloudflareUrl, buildPingRequest, ping, extractQuotaPercent, getProviderQuotaPercentCached, usagePlaceholderForProvider } from '../src/ping.js'
 import { runFiableMode, filterByTierOrExit, fetchOpenRouterFreeModels } from '../src/analysis.js'
@@ -192,9 +192,8 @@ export async function runApp(cliArgs, config) {
   if (cliArgs.pingInterval) config.settings.pingInterval = cliArgs.pingInterval
   if (cliArgs.hideUnconfigured) config.settings.hideUnconfiguredModels = true
   if (cliArgs.showUnconfigured) config.settings.hideUnconfiguredModels = false
-  if (cliArgs.disableWidthsWarning) config.settings.disableWidthsWarning = true
 
-  // 📖 Apply premium mode: show only S‑tier models sorted by verdict
+  // 📖 Apply premium mode as an initial, user-resettable view preset.
   if (cliArgs.premiumMode) {
     config.settings.tierFilter = 'S'
     config.settings.sortColumn = 'verdict'
@@ -383,13 +382,11 @@ export async function runApp(cliArgs, config) {
     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)
-    premiumMode: cliArgs.premiumMode, // 📖 Special elite-only mode: S/S+ only, Health UP only, Perfect/Normal/Slow verdict only.
     hideUnconfiguredModels: config.settings?.hideUnconfiguredModels === true, // 📖 Hide providers with no configured API key when true.
-    disableWidthsWarning: config.settings?.disableWidthsWarning ?? false, // 📖 Cached for runtime checks; keep it in sync with config.settings.
       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 && !(config.settings?.disableWidthsWarning ?? false) ? now : null, // 📖 Start immediately only when warnings are enabled in a narrow viewport.
+      widthWarningStartedAt: (process.stdout.columns || 80) < WIDTH_WARNING_MIN_COLS ? now : null, // 📖 Start immediately in very narrow viewports.
     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)
@@ -412,6 +409,7 @@ export async function runApp(cliArgs, config) {
     commandPaletteScrollOffset: 0, // 📖 Vertical scroll offset for the command palette result viewport.
     commandPaletteResults: [],    // 📖 Cached fuzzy-filtered command entries for the command palette.
     commandPaletteFrozenTable: null, // 📖 Frozen table snapshot rendered behind the command palette overlay.
+    commandPaletteExpandedIds: new Set(['filters']), // 📖 Set of expanded category/subcategory IDs (filters expanded by default for quick access).
     helpVisible: false,           // 📖 Whether the help overlay (K key) is active
     settingsScrollOffset: 0,      // 📖 Vertical scroll offset for Settings overlay viewport
     helpScrollOffset: 0,          // 📖 Vertical scroll offset for Help overlay viewport
@@ -460,17 +458,17 @@ export async function runApp(cliArgs, config) {
     changelogPhase: 'index',      // 📖 'index' (all versions) | 'details' (specific version)
     changelogCursor: 0,           // 📖 Selected row in index phase
     changelogSelectedVersion: null, // 📖 Which version to show details for
+    // 📖 Custom text filter (Ctrl+P palette → type text → Enter). Ephemeral — not saved to config.
+    customTextFilter: null,       // 📖 Active free-text filter string (null = off). Matches model name, ctx, provider key/name.
   }
 
   // 📖 Re-clamp viewport on terminal resize
   process.stdout.on('resize', () => {
     const prevCols = state.terminalCols
-    const widthsWarningDisabled = state.config.settings?.disableWidthsWarning === true
     state.terminalRows = process.stdout.rows || 24
     state.terminalCols = process.stdout.columns || 80
-    state.disableWidthsWarning = widthsWarningDisabled
-    if (state.terminalCols < 166 && !widthsWarningDisabled) {
-      if (prevCols >= 166 || state.widthWarningDismissed) {
+    if (state.terminalCols < WIDTH_WARNING_MIN_COLS) {
+      if (prevCols >= WIDTH_WARNING_MIN_COLS || state.widthWarningDismissed) {
         state.widthWarningStartedAt = Date.now()
         state.widthWarningDismissed = false
         state.widthWarningShowCount++ // 📖 Increment counter when showing the warning again
@@ -630,15 +628,10 @@ export async function runApp(cliArgs, config) {
       outputResults = outputResults.filter(r => ['S+', 'S', 'A+'].includes(r.tier))
     }
 
-    // 📖 Apply premium mode filter if specified: elite-only (S/S+, UP, Good Verdict)
+    // 📖 Apply premium mode as a preselected tier family in JSON mode as well.
     if (cliArgs.premiumMode) {
-      outputResults = outputResults.filter(r => {
-        const isEliteTier = r.tier === 'S' || r.tier === 'S+'
-        const isHealthUp = r.status === 'up'
-        const verdict = getVerdict(r)
-        const isGoodVerdict = ['Perfect', 'Normal', 'Slow'].includes(verdict)
-        return isEliteTier && isHealthUp && isGoodVerdict
-      })
+      const premiumTiers = TIER_LETTER_MAP.S || ['S+', 'S']
+      outputResults = outputResults.filter(r => premiumTiers.includes(r.tier))
     }
 
     // 📖 Sort by avg ping (ascending)
@@ -700,19 +693,22 @@ export async function runApp(cliArgs, config) {
       const allowedTiers = (activeTier && TIER_LETTER_MAP[activeTier]) ? TIER_LETTER_MAP[activeTier] : [activeTier]
       const tierHide = activeTier !== null && !allowedTiers.includes(r.tier)
       const originHide = activeOrigin !== null && r.providerKey !== activeOrigin
-      r.hidden = tierHide || originHide
-
-      // 📖 Premium Mode: elite-only constraints (Health UP, Good Verdict, S/S+ only)
-      if (state.premiumMode && !r.hidden) {
-        const isEliteTier = r.tier === 'S' || r.tier === 'S+'
-        const isHealthUp = r.status === 'up'
-        const verdict = getVerdict(r)
-        const isGoodVerdict = ['Perfect', 'Normal', 'Slow'].includes(verdict)
-
-        if (!isEliteTier || !isHealthUp || !isGoodVerdict) {
-          r.hidden = true
-        }
+      if (tierHide || originHide) {
+        r.hidden = true
+        return
+      }
+      // 📖 Custom text filter — case-insensitive includes match against model name, ctx, provider key, and provider display name.
+      if (state.customTextFilter) {
+        const q = state.customTextFilter.toLowerCase()
+        const providerName = (sources[r.providerKey]?.name || '').toLowerCase()
+        const match = (r.label || '').toLowerCase().includes(q)
+          || (r.ctx || '').toLowerCase().includes(q)
+          || (r.providerKey || '').toLowerCase().includes(q)
+          || providerName.includes(q)
+        r.hidden = !match
+        return
       }
+      r.hidden = false
     })
     return state.results
   }
@@ -900,8 +896,7 @@ export async function runApp(cliArgs, config) {
           state.settingsUpdateLatestVersion,
           false,
           state.startupLatestVersion,
-          state.versionAlertsEnabled,
-          state.config.settings?.disableWidthsWarning ?? false
+          state.versionAlertsEnabled
         )
       }
       tableContent = state.commandPaletteFrozenTable
@@ -933,8 +928,7 @@ export async function runApp(cliArgs, config) {
         state.settingsUpdateLatestVersion,
         false,
         state.startupLatestVersion,
-        state.versionAlertsEnabled,
-        state.config.settings?.disableWidthsWarning ?? false
+        state.versionAlertsEnabled
       )
     }
 
@@ -972,7 +966,7 @@ export async function runApp(cliArgs, config) {
   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, null, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, false, state.startupLatestVersion, state.versionAlertsEnabled, state.config.settings?.disableWidthsWarning ?? false))
+  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, null, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, false, state.startupLatestVersion, state.versionAlertsEnabled))
   if (process.stdout.isTTY) {
     process.stdout.flush && process.stdout.flush()
   }

package/src/cli-help.js

@@ -26,14 +26,13 @@ const ANALYSIS_FLAGS = [
   { 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' },
-  { flag: '--premium', description: 'Show only S/S+ models with perfect health and good verdict' },
+  { flag: '--premium', description: 'Start with S-tier filter + verdict sort (you can reset it in-app)' },
   { flag: '--sort <column>', description: 'Sort by column (rank, tier, origin, model, ping, avg, swe, ctx, condition, verdict, uptime, stability, usage)' },
   { flag: '--desc | --asc', description: 'Set sort direction (descending or ascending)' },
   { flag: '--origin <provider>', description: 'Filter models by provider origin' },
   { flag: '--ping-interval <ms>', description: 'Override ping interval in milliseconds' },
   { flag: '--hide-unconfigured', description: 'Hide models without configured API keys' },
   { flag: '--show-unconfigured', description: 'Show all models regardless of API key config' },
-  { flag: '--disable-widths-warning', description: 'Disable terminal width warning' },
 ]
 
 const CONFIG_FLAGS = [