free-coding-models 0.3.18 → 0.3.19

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ---
 
+## 0.3.19
+
+### Added
+- **Command palette overlay (`Ctrl+P`)**: Added a searchable floating palette with fuzzy matching so users can quickly run filters, sorts, overlays, and global actions.
+
+### Changed
+- **Main footer and help discoverability**: surfaced `Ctrl+P` in table hints and Help overlay so the new command launcher is visible immediately.
+- **Command palette spacing polish**: added two-character inner padding around the floating palette so the overlay feels less cramped and visually cleaner.
+
+### Fixed
+- **Command palette visual jitter**: background ping cycles now pause while the command palette is open so table rows stop reshuffling during command search.
+- **Command palette background freeze**: while the palette is open, the full table behind it is now frozen (spinner glyphs, ping countdown, and dynamic row updates) and resumes instantly on close.
+
 ## 0.3.18
 
 ### Added

package/README.md

@@ -176,6 +176,7 @@ 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) |
 | `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) |
@@ -200,6 +201,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
 - **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.18",
+  "version": "0.3.19",
   "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

@@ -406,6 +406,12 @@ export async function runApp(cliArgs, config) {
     settingsUpdateError: null,    // 📖 Last update-check error message for maintenance row
     config,                       // 📖 Live reference to the config object (updated on save)
     visibleSorted: [],            // 📖 Cached visible+sorted models — shared between render loop and key handlers
+    commandPaletteOpen: false,    // 📖 Whether the Ctrl+P command palette overlay is active.
+    commandPaletteQuery: '',      // 📖 Current command palette search query.
+    commandPaletteCursor: 0,      // 📖 Selected command index in the filtered command list.
+    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.
     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
@@ -761,6 +767,7 @@ export async function runApp(cliArgs, config) {
     getToolMeta,
     getToolInstallPlan,
     padEndDisplay,
+    displayWidth,
   })
 
   onKeyPress = createKeyHandler({
@@ -858,16 +865,87 @@ export async function runApp(cliArgs, config) {
     refreshAutoPingMode()
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.installEndpointsOpen && !state.toolInstallPromptOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.toolInstallPromptOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen && !state.commandPaletteOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
+    let tableContent = null
+    if (state.commandPaletteOpen) {
+      if (!state.commandPaletteFrozenTable) {
+        // 📖 Freeze the full table (including countdown and spinner glyphs) while
+        // 📖 the command palette is open so the background remains perfectly static.
+        state.commandPaletteFrozenTable = 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
+        )
+      }
+      tableContent = state.commandPaletteFrozenTable
+    } else {
+      state.commandPaletteFrozenTable = null
+      tableContent = 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
+      )
+    }
+
     const content = state.settingsOpen
       ? overlays.renderSettings()
       : state.installEndpointsOpen
         ? overlays.renderInstallEndpoints()
       : state.toolInstallPromptOpen
         ? overlays.renderToolInstallPrompt()
+      : state.commandPaletteOpen
+        ? tableContent + overlays.renderCommandPalette()
       : state.recommendOpen
         ? overlays.renderRecommend()
         : state.feedbackOpen
@@ -876,7 +954,7 @@ export async function runApp(cliArgs, config) {
                 ? overlays.renderHelp()
               : 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, 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)
+                 : tableContent
     process.stdout.write(ALT_HOME + content)
     if (process.stdout.isTTY) {
       process.stdout.flush && process.stdout.flush()
@@ -920,6 +998,15 @@ export async function runApp(cliArgs, config) {
   const runPingCycle = async () => {
     try {
     refreshAutoPingMode()
+
+    // 📖 Command palette intentionally pauses background ping bursts to avoid
+    // 📖 visible row jitter while users type and navigate commands.
+    if (state.commandPaletteOpen) {
+      state.lastPingTime = Date.now()
+      scheduleNextPing()
+      return
+    }
+
     state.lastPingTime = Date.now()
 
     // 📖 Refresh persisted usage snapshots each cycle so background usage data appears live in table.

package/src/command-palette.js

@@ -0,0 +1,170 @@
+/**
+ * @file command-palette.js
+ * @description Command palette registry and fuzzy search helpers for the main TUI.
+ *
+ * @functions
+ *   → `buildCommandPaletteEntries` — builds the current command list with dynamic provider/tier context
+ *   → `fuzzyMatchCommand` — scores a query against one string and returns match positions
+ *   → `filterCommandPaletteEntries` — returns sorted command matches for a query
+ *
+ * @exports { COMMAND_CATEGORY_ORDER, buildCommandPaletteEntries, fuzzyMatchCommand, filterCommandPaletteEntries }
+ *
+ * @see src/key-handler.js
+ * @see src/overlays.js
+ */
+
+export const COMMAND_CATEGORY_ORDER = ['Filters', 'Sort', 'Pages', 'Actions']
+
+const COMMANDS = [
+  // 📖 Filters
+  { id: 'filter-tier-all', category: 'Filters', label: 'Filter tiers: all', shortcut: 'T', keywords: ['filter', 'tier', 'all'] },
+  { id: 'filter-tier-splus', category: 'Filters', label: 'Filter tiers: S+', shortcut: null, keywords: ['filter', 'tier', 's+'] },
+  { id: 'filter-tier-s', category: 'Filters', label: 'Filter tiers: S', shortcut: null, keywords: ['filter', 'tier', 's'] },
+  { id: 'filter-tier-aplus', category: 'Filters', label: 'Filter tiers: A+', shortcut: null, keywords: ['filter', 'tier', 'a+'] },
+  { id: 'filter-tier-a', category: 'Filters', label: 'Filter tiers: A', shortcut: null, keywords: ['filter', 'tier', 'a'] },
+  { id: 'filter-tier-aminus', category: 'Filters', label: 'Filter tiers: A-', shortcut: null, keywords: ['filter', 'tier', 'a-'] },
+  { id: 'filter-tier-bplus', category: 'Filters', label: 'Filter tiers: B+', shortcut: null, keywords: ['filter', 'tier', 'b+'] },
+  { id: 'filter-tier-b', category: 'Filters', label: 'Filter tiers: B', shortcut: null, keywords: ['filter', 'tier', 'b'] },
+  { id: 'filter-tier-c', category: 'Filters', label: 'Filter tiers: C', shortcut: null, keywords: ['filter', 'tier', 'c'] },
+  { id: 'filter-provider-cycle', category: 'Filters', label: 'Filter provider: cycle', shortcut: 'D', keywords: ['filter', 'provider', 'origin'] },
+  { id: 'filter-configured-toggle', category: 'Filters', label: 'Toggle configured-only models', shortcut: 'E', keywords: ['filter', 'configured', 'keys'] },
+
+  // 📖 Sorting
+  { id: 'sort-rank', category: 'Sort', label: 'Sort by rank', shortcut: 'R', keywords: ['sort', 'rank'] },
+  { id: 'sort-tier', category: 'Sort', label: 'Sort by tier', shortcut: null, keywords: ['sort', 'tier'] },
+  { id: 'sort-provider', category: 'Sort', label: 'Sort by provider', shortcut: 'O', keywords: ['sort', 'origin', 'provider'] },
+  { id: 'sort-model', category: 'Sort', label: 'Sort by model name', shortcut: 'M', keywords: ['sort', 'model', 'name'] },
+  { id: 'sort-latest-ping', category: 'Sort', label: 'Sort by latest ping', shortcut: 'L', keywords: ['sort', 'latest', 'ping'] },
+  { id: 'sort-avg-ping', category: 'Sort', label: 'Sort by average ping', shortcut: 'A', keywords: ['sort', 'avg', 'average', 'ping'] },
+  { id: 'sort-swe', category: 'Sort', label: 'Sort by SWE score', shortcut: 'S', keywords: ['sort', 'swe', 'score'] },
+  { id: 'sort-ctx', category: 'Sort', label: 'Sort by context window', shortcut: 'C', keywords: ['sort', 'context', 'ctx'] },
+  { id: 'sort-health', category: 'Sort', label: 'Sort by health', shortcut: 'H', keywords: ['sort', 'health', 'condition'] },
+  { id: 'sort-verdict', category: 'Sort', label: 'Sort by verdict', shortcut: 'V', keywords: ['sort', 'verdict'] },
+  { id: 'sort-stability', category: 'Sort', label: 'Sort by stability', shortcut: 'B', keywords: ['sort', 'stability'] },
+  { id: 'sort-uptime', category: 'Sort', label: 'Sort by uptime', shortcut: 'U', keywords: ['sort', 'uptime'] },
+
+  // 📖 Pages / overlays
+  { id: 'open-settings', category: 'Pages', label: 'Open settings', shortcut: 'P', keywords: ['settings', 'config', 'api key'] },
+  { id: 'open-help', category: 'Pages', label: 'Open help', shortcut: 'K', keywords: ['help', 'shortcuts', 'hotkeys'] },
+  { id: 'open-changelog', category: 'Pages', label: 'Open changelog', shortcut: 'N', keywords: ['changelog', 'release'] },
+  { id: 'open-feedback', category: 'Pages', label: 'Open feedback', shortcut: 'I', keywords: ['feedback', 'bug', 'request'] },
+  { id: 'open-recommend', category: 'Pages', label: 'Open smart recommend', shortcut: 'Q', keywords: ['recommend', 'best model'] },
+  { id: 'open-install-endpoints', category: 'Pages', label: 'Open install endpoints', shortcut: 'Y', keywords: ['install', 'endpoints', 'providers'] },
+
+  // 📖 Actions
+  { id: 'action-cycle-theme', category: 'Actions', label: 'Cycle theme', shortcut: 'G', keywords: ['theme', 'dark', 'light', 'auto'] },
+  { id: 'action-cycle-tool-mode', category: 'Actions', label: 'Cycle tool mode', shortcut: 'Z', keywords: ['tool', 'mode', 'launcher'] },
+  { id: 'action-cycle-ping-mode', category: 'Actions', label: 'Cycle ping mode', shortcut: 'W', keywords: ['ping', 'cadence', 'speed', 'slow'] },
+  { id: 'action-toggle-favorite', category: 'Actions', label: 'Toggle favorite on selected model', shortcut: 'F', keywords: ['favorite', 'star'] },
+  { id: 'action-reset-view', category: 'Actions', label: 'Reset view settings', shortcut: 'Shift+R', keywords: ['reset', 'view', 'sort', 'filters'] },
+]
+
+const ID_TO_TIER = {
+  'filter-tier-all': null,
+  'filter-tier-splus': 'S+',
+  'filter-tier-s': 'S',
+  'filter-tier-aplus': 'A+',
+  'filter-tier-a': 'A',
+  'filter-tier-aminus': 'A-',
+  'filter-tier-bplus': 'B+',
+  'filter-tier-b': 'B',
+  'filter-tier-c': 'C',
+}
+
+export function buildCommandPaletteEntries() {
+  return COMMANDS.map((entry) => ({
+    ...entry,
+    tierValue: Object.prototype.hasOwnProperty.call(ID_TO_TIER, entry.id) ? ID_TO_TIER[entry.id] : undefined,
+  }))
+}
+
+/**
+ * 📖 Fuzzy matching optimized for short command labels and keyboard aliases.
+ * @param {string} query
+ * @param {string} text
+ * @returns {{ matched: boolean, score: number, positions: number[] }}
+ */
+export function fuzzyMatchCommand(query, text) {
+  const q = (query || '').trim().toLowerCase()
+  const t = (text || '').toLowerCase()
+
+  if (!q) return { matched: true, score: 0, positions: [] }
+  if (!t) return { matched: false, score: 0, positions: [] }
+
+  let qIdx = 0
+  const positions = []
+  for (let i = 0; i < t.length && qIdx < q.length; i++) {
+    if (q[qIdx] === t[i]) {
+      positions.push(i)
+      qIdx++
+    }
+  }
+
+  if (qIdx !== q.length) return { matched: false, score: 0, positions: [] }
+
+  let score = q.length * 10
+
+  // 📖 Bonus when matches are contiguous.
+  for (let i = 1; i < positions.length; i++) {
+    if (positions[i] === positions[i - 1] + 1) score += 5
+  }
+
+  // 📖 Bonus for word boundaries and prefix matches.
+  for (const pos of positions) {
+    if (pos === 0) score += 8
+    else {
+      const prev = t[pos - 1]
+      if (prev === ' ' || prev === ':' || prev === '-' || prev === '/') score += 6
+    }
+  }
+
+  // 📖 Small penalty for very long labels so focused labels float up.
+  score -= Math.max(0, t.length - q.length)
+
+  return { matched: true, score, positions }
+}
+
+/**
+ * 📖 Filter and rank command palette entries by fuzzy score.
+ * @param {Array<{ id: string, label: string, category: string, keywords?: string[] }>} entries
+ * @param {string} query
+ * @returns {Array<{ id: string, label: string, category: string, shortcut?: string|null, keywords?: string[], score: number, matchPositions: number[] }>}
+ */
+export function filterCommandPaletteEntries(entries, query) {
+  const normalizedQuery = (query || '').trim()
+
+  const ranked = []
+  for (const entry of entries) {
+    const labelMatch = fuzzyMatchCommand(normalizedQuery, entry.label)
+    let bestScore = labelMatch.score
+    let matchPositions = labelMatch.positions
+    let matched = labelMatch.matched
+
+    if (!matched && Array.isArray(entry.keywords)) {
+      for (const keyword of entry.keywords) {
+        const keywordMatch = fuzzyMatchCommand(normalizedQuery, keyword)
+        if (!keywordMatch.matched) continue
+        matched = true
+        // 📖 Keyword matches should rank below direct label matches.
+        const keywordScore = Math.max(1, keywordMatch.score - 7)
+        if (keywordScore > bestScore) {
+          bestScore = keywordScore
+          matchPositions = []
+        }
+      }
+    }
+
+    if (!matched) continue
+    ranked.push({ ...entry, score: bestScore, matchPositions })
+  }
+
+  ranked.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score
+    const aCat = COMMAND_CATEGORY_ORDER.indexOf(a.category)
+    const bCat = COMMAND_CATEGORY_ORDER.indexOf(b.category)
+    if (aCat !== bCat) return aCat - bCat
+    return a.label.localeCompare(b.label)
+  })
+
+  return ranked
+}

package/src/key-handler.js

@@ -31,6 +31,7 @@ import { loadChangelog } from './changelog-loader.js'
 import { loadConfig, replaceConfigContents } from './config.js'
 import { cleanupLegacyProxyArtifacts } from './legacy-proxy-cleanup.js'
 import { cycleThemeSetting, detectActiveTheme } from './theme.js'
+import { buildCommandPaletteEntries, filterCommandPaletteEntries } from './command-palette.js'
 
 // 📖 Some providers need an explicit probe model because the first catalog entry
 // 📖 is not guaranteed to be accepted by their chat endpoint.
@@ -536,10 +537,315 @@ export function createKeyHandler(ctx) {
     state.installEndpointsErrorMsg = null
   }
 
+  // 📖 Persist current table-view preferences so sort/filter state survives restarts.
+  function persistUiSettings() {
+    if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+    state.config.settings.tierFilter = TIER_CYCLE[state.tierFilterMode]
+    state.config.settings.originFilter = ORIGIN_CYCLE[state.originFilterMode] ?? null
+    state.config.settings.sortColumn = state.sortColumn
+    state.config.settings.sortAsc = state.sortDirection === 'asc'
+    saveConfig(state.config)
+  }
+
+  // 📖 Shared table refresh helper so command-palette and hotkeys keep identical behavior.
+  function refreshVisibleSorted({ resetCursor = true } = {}) {
+    const visible = state.results.filter(r => !r.hidden)
+    state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+    if (resetCursor) {
+      state.cursor = 0
+      state.scrollOffset = 0
+      return
+    }
+    if (state.cursor >= state.visibleSorted.length) state.cursor = Math.max(0, state.visibleSorted.length - 1)
+    adjustScrollOffset(state)
+  }
+
+  function setSortColumnFromCommand(col) {
+    if (state.sortColumn === col) {
+      state.sortDirection = state.sortDirection === 'asc' ? 'desc' : 'asc'
+    } else {
+      state.sortColumn = col
+      state.sortDirection = 'asc'
+    }
+    refreshVisibleSorted({ resetCursor: true })
+    persistUiSettings()
+  }
+
+  function setTierFilterFromCommand(tierLabel) {
+    const nextMode = tierLabel === null ? 0 : TIER_CYCLE.indexOf(tierLabel)
+    state.tierFilterMode = nextMode >= 0 ? nextMode : 0
+    applyTierFilter()
+    refreshVisibleSorted({ resetCursor: true })
+    persistUiSettings()
+  }
+
+  function openSettingsOverlay() {
+    state.settingsOpen = true
+    state.settingsCursor = 0
+    state.settingsEditMode = false
+    state.settingsAddKeyMode = false
+    state.settingsEditBuffer = ''
+    state.settingsScrollOffset = 0
+  }
+
+  function openRecommendOverlay() {
+    state.recommendOpen = true
+    state.recommendPhase = 'questionnaire'
+    state.recommendQuestion = 0
+    state.recommendCursor = 0
+    state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
+    state.recommendResults = []
+    state.recommendScrollOffset = 0
+  }
+
+  function openInstallEndpointsOverlay() {
+    state.installEndpointsOpen = true
+    state.installEndpointsPhase = 'providers'
+    state.installEndpointsCursor = 0
+    state.installEndpointsScrollOffset = 0
+    state.installEndpointsProviderKey = null
+    state.installEndpointsToolMode = null
+    state.installEndpointsConnectionMode = null
+    state.installEndpointsScope = null
+    state.installEndpointsSelectedModelIds = new Set()
+    state.installEndpointsErrorMsg = null
+    state.installEndpointsResult = null
+  }
+
+  function openFeedbackOverlay() {
+    state.feedbackOpen = true
+    state.bugReportBuffer = ''
+    state.bugReportStatus = 'idle'
+    state.bugReportError = null
+  }
+
+  function openChangelogOverlay() {
+    state.changelogOpen = true
+    state.changelogScrollOffset = 0
+    state.changelogPhase = 'index'
+    state.changelogCursor = 0
+    state.changelogSelectedVersion = null
+  }
+
+  function cycleToolMode() {
+    const modeOrder = getToolModeOrder()
+    const currentIndex = modeOrder.indexOf(state.mode)
+    const nextIndex = (currentIndex + 1) % modeOrder.length
+    state.mode = modeOrder[nextIndex]
+    if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+    state.config.settings.preferredToolMode = state.mode
+    saveConfig(state.config)
+  }
+
+  function resetViewSettings() {
+    state.tierFilterMode = 0
+    state.originFilterMode = 0
+    state.sortColumn = 'avg'
+    state.sortDirection = 'asc'
+    if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+    delete state.config.settings.tierFilter
+    delete state.config.settings.originFilter
+    delete state.config.settings.sortColumn
+    delete state.config.settings.sortAsc
+    saveConfig(state.config)
+    applyTierFilter()
+    refreshVisibleSorted({ resetCursor: true })
+  }
+
+  function toggleFavoriteOnSelectedRow() {
+    const selected = state.visibleSorted[state.cursor]
+    if (!selected) return
+    const wasFavorite = selected.isFavorite
+    toggleFavoriteModel(state.config, selected.providerKey, selected.modelId)
+    syncFavoriteFlags(state.results, state.config)
+    applyTierFilter()
+    refreshVisibleSorted({ resetCursor: false })
+
+    if (wasFavorite) {
+      state.cursor = 0
+      state.scrollOffset = 0
+      return
+    }
+
+    const selectedKey = toFavoriteKey(selected.providerKey, selected.modelId)
+    const newCursor = state.visibleSorted.findIndex(r => toFavoriteKey(r.providerKey, r.modelId) === selectedKey)
+    if (newCursor >= 0) state.cursor = newCursor
+    adjustScrollOffset(state)
+  }
+
+  function commandPaletteHasBlockingOverlay() {
+    return state.settingsOpen
+      || state.installEndpointsOpen
+      || state.toolInstallPromptOpen
+      || state.recommendOpen
+      || state.feedbackOpen
+      || state.helpVisible
+      || state.changelogOpen
+  }
+
+  function refreshCommandPaletteResults() {
+    const commands = buildCommandPaletteEntries()
+    state.commandPaletteResults = filterCommandPaletteEntries(commands, state.commandPaletteQuery)
+    if (state.commandPaletteCursor >= state.commandPaletteResults.length) {
+      state.commandPaletteCursor = Math.max(0, state.commandPaletteResults.length - 1)
+    }
+  }
+
+  function openCommandPalette() {
+    state.commandPaletteOpen = true
+    state.commandPaletteFrozenTable = null
+    state.commandPaletteQuery = ''
+    state.commandPaletteCursor = 0
+    state.commandPaletteScrollOffset = 0
+    refreshCommandPaletteResults()
+  }
+
+  function closeCommandPalette() {
+    state.commandPaletteOpen = false
+    state.commandPaletteFrozenTable = null
+    state.commandPaletteQuery = ''
+    state.commandPaletteCursor = 0
+    state.commandPaletteScrollOffset = 0
+    state.commandPaletteResults = []
+  }
+
+  function executeCommandPaletteEntry(entry) {
+    if (!entry?.id) return
+
+    if (entry.id.startsWith('filter-tier-')) {
+      setTierFilterFromCommand(entry.tierValue ?? null)
+      return
+    }
+
+    switch (entry.id) {
+      case 'filter-provider-cycle':
+        state.originFilterMode = (state.originFilterMode + 1) % ORIGIN_CYCLE.length
+        applyTierFilter()
+        refreshVisibleSorted({ resetCursor: true })
+        persistUiSettings()
+        return
+      case 'filter-configured-toggle':
+        state.hideUnconfiguredModels = !state.hideUnconfiguredModels
+        if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+        state.config.settings.hideUnconfiguredModels = state.hideUnconfiguredModels
+        saveConfig(state.config)
+        applyTierFilter()
+        refreshVisibleSorted({ resetCursor: true })
+        return
+      case 'sort-rank': return setSortColumnFromCommand('rank')
+      case 'sort-tier': return setSortColumnFromCommand('tier')
+      case 'sort-provider': return setSortColumnFromCommand('origin')
+      case 'sort-model': return setSortColumnFromCommand('model')
+      case 'sort-latest-ping': return setSortColumnFromCommand('ping')
+      case 'sort-avg-ping': return setSortColumnFromCommand('avg')
+      case 'sort-swe': return setSortColumnFromCommand('swe')
+      case 'sort-ctx': return setSortColumnFromCommand('ctx')
+      case 'sort-health': return setSortColumnFromCommand('condition')
+      case 'sort-verdict': return setSortColumnFromCommand('verdict')
+      case 'sort-stability': return setSortColumnFromCommand('stability')
+      case 'sort-uptime': return setSortColumnFromCommand('uptime')
+      case 'open-settings': return openSettingsOverlay()
+      case 'open-help':
+        state.helpVisible = true
+        state.helpScrollOffset = 0
+        return
+      case 'open-changelog': return openChangelogOverlay()
+      case 'open-feedback': return openFeedbackOverlay()
+      case 'open-recommend': return openRecommendOverlay()
+      case 'open-install-endpoints': return openInstallEndpointsOverlay()
+      case 'action-cycle-theme': return cycleGlobalTheme()
+      case 'action-cycle-tool-mode': return cycleToolMode()
+      case 'action-cycle-ping-mode': {
+        const currentIdx = PING_MODE_CYCLE.indexOf(state.pingMode)
+        const nextIdx = currentIdx >= 0 ? (currentIdx + 1) % PING_MODE_CYCLE.length : 0
+        setPingMode(PING_MODE_CYCLE[nextIdx], 'manual')
+        return
+      }
+      case 'action-toggle-favorite': return toggleFavoriteOnSelectedRow()
+      case 'action-reset-view': return resetViewSettings()
+      default:
+        return
+    }
+  }
+
   return async (str, key) => {
     if (!key) return
     noteUserActivity()
 
+    // 📖 Ctrl+P toggles the command palette from the main table only.
+    if (key.ctrl && key.name === 'p') {
+      if (state.commandPaletteOpen) {
+        closeCommandPalette()
+        return
+      }
+      if (!commandPaletteHasBlockingOverlay()) {
+        openCommandPalette()
+      }
+      return
+    }
+
+    // 📖 Command palette captures the keyboard while active.
+    if (state.commandPaletteOpen) {
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+
+      const pageStep = Math.max(1, (state.terminalRows || 1) - 10)
+
+      if (key.name === 'escape') {
+        closeCommandPalette()
+        return
+      }
+      if (key.name === 'up') {
+        const count = state.commandPaletteResults.length
+        if (count === 0) return
+        state.commandPaletteCursor = state.commandPaletteCursor > 0 ? state.commandPaletteCursor - 1 : count - 1
+        return
+      }
+      if (key.name === 'down') {
+        const count = state.commandPaletteResults.length
+        if (count === 0) return
+        state.commandPaletteCursor = state.commandPaletteCursor < count - 1 ? state.commandPaletteCursor + 1 : 0
+        return
+      }
+      if (key.name === 'pageup') {
+        state.commandPaletteCursor = Math.max(0, state.commandPaletteCursor - pageStep)
+        return
+      }
+      if (key.name === 'pagedown') {
+        const max = Math.max(0, state.commandPaletteResults.length - 1)
+        state.commandPaletteCursor = Math.min(max, state.commandPaletteCursor + pageStep)
+        return
+      }
+      if (key.name === 'home') {
+        state.commandPaletteCursor = 0
+        return
+      }
+      if (key.name === 'end') {
+        state.commandPaletteCursor = Math.max(0, state.commandPaletteResults.length - 1)
+        return
+      }
+      if (key.name === 'backspace') {
+        state.commandPaletteQuery = state.commandPaletteQuery.slice(0, -1)
+        state.commandPaletteCursor = 0
+        state.commandPaletteScrollOffset = 0
+        refreshCommandPaletteResults()
+        return
+      }
+      if (key.name === 'return') {
+        const selectedCommand = state.commandPaletteResults[state.commandPaletteCursor]
+        closeCommandPalette()
+        executeCommandPaletteEntry(selectedCommand)
+        return
+      }
+      if (str && str.length === 1 && !key.ctrl && !key.meta) {
+        state.commandPaletteQuery += str
+        state.commandPaletteCursor = 0
+        state.commandPaletteScrollOffset = 0
+        refreshCommandPaletteResults()
+        return
+      }
+      return
+    }
+
     if (!state.feedbackOpen && !state.settingsEditMode && !state.settingsAddKeyMode && key.name === 'g' && !key.ctrl && !key.meta) {
       cycleGlobalTheme()
       return
@@ -1346,41 +1652,20 @@ export function createKeyHandler(ctx) {
     }
 
     // 📖 P key: open settings screen
-    if (key.name === 'p' && !key.shift) {
-      state.settingsOpen = true
-      state.settingsCursor = 0
-      state.settingsEditMode = false
-      state.settingsAddKeyMode = false
-      state.settingsEditBuffer = ''
-      state.settingsScrollOffset = 0
+    if (key.name === 'p' && !key.shift && !key.ctrl && !key.meta) {
+      openSettingsOverlay()
       return
     }
 
     // 📖 Q key: open Smart Recommend overlay
     if (key.name === 'q') {
-      state.recommendOpen = true
-      state.recommendPhase = 'questionnaire'
-      state.recommendQuestion = 0
-      state.recommendCursor = 0
-      state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
-      state.recommendResults = []
-      state.recommendScrollOffset = 0
+      openRecommendOverlay()
       return
     }
 
     // 📖 Y key: open Install Endpoints flow for configured providers.
     if (key.name === 'y') {
-      state.installEndpointsOpen = true
-      state.installEndpointsPhase = 'providers'
-      state.installEndpointsCursor = 0
-      state.installEndpointsScrollOffset = 0
-      state.installEndpointsProviderKey = null
-      state.installEndpointsToolMode = null
-      state.installEndpointsConnectionMode = null
-      state.installEndpointsScope = null
-      state.installEndpointsSelectedModelIds = new Set()
-      state.installEndpointsErrorMsg = null
-      state.installEndpointsResult = null
+      openInstallEndpointsOverlay()
       return
     }
 
@@ -1388,34 +1673,9 @@ export function createKeyHandler(ctx) {
 
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
-    // 📖 Helper: persist current UI view settings (tier, provider, sort) to config.settings
-    // 📖 Called after every T / D / sort key so preferences survive session restarts.
-    function persistUiSettings() {
-      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
-      state.config.settings.tierFilter = TIER_CYCLE[state.tierFilterMode]
-      state.config.settings.originFilter = ORIGIN_CYCLE[state.originFilterMode] ?? null
-      state.config.settings.sortColumn = state.sortColumn
-      state.config.settings.sortAsc = state.sortDirection === 'asc'
-      saveConfig(state.config)
-    }
-
     // 📖 Shift+R: reset all UI view settings to defaults (tier, sort, provider) and clear persisted config
     if (key.name === 'r' && key.shift) {
-      state.tierFilterMode = 0
-      state.originFilterMode = 0
-      state.sortColumn = 'avg'
-      state.sortDirection = 'asc'
-      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
-      delete state.config.settings.tierFilter
-      delete state.config.settings.originFilter
-      delete state.config.settings.sortColumn
-      delete state.config.settings.sortAsc
-      saveConfig(state.config)
-      applyTierFilter()
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
+      resetViewSettings()
       return
     }
 
@@ -1430,54 +1690,19 @@ export function createKeyHandler(ctx) {
 
     if (sortKeys[key.name] && !key.ctrl && !key.shift) {
       const col = sortKeys[key.name]
-      // 📖 Toggle direction if same column, otherwise reset to asc
-      if (state.sortColumn === col) {
-        state.sortDirection = state.sortDirection === 'asc' ? 'desc' : 'asc'
-      } else {
-        state.sortColumn = col
-        state.sortDirection = 'asc'
-      }
-      // 📖 Recompute visible sorted list and reset cursor to top to avoid stale index
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
-      persistUiSettings()
+      setSortColumnFromCommand(col)
       return
     }
 
     // 📖 F key: toggle favorite on the currently selected row and persist to config.
     if (key.name === 'f') {
-      const selected = state.visibleSorted[state.cursor]
-      if (!selected) return
-      const wasFavorite = selected.isFavorite
-      toggleFavoriteModel(state.config, selected.providerKey, selected.modelId)
-      syncFavoriteFlags(state.results, state.config)
-      applyTierFilter()
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-
-      // 📖 UX rule: when unpinning a favorite, jump back to the top of the list.
-      if (wasFavorite) {
-        state.cursor = 0
-        state.scrollOffset = 0
-        return
-      }
-
-      const selectedKey = toFavoriteKey(selected.providerKey, selected.modelId)
-      const newCursor = state.visibleSorted.findIndex(r => toFavoriteKey(r.providerKey, r.modelId) === selectedKey)
-      if (newCursor >= 0) state.cursor = newCursor
-      else if (state.cursor >= state.visibleSorted.length) state.cursor = Math.max(0, state.visibleSorted.length - 1)
-      adjustScrollOffset(state)
+      toggleFavoriteOnSelectedRow()
       return
     }
 
     // 📖 I key: open Feedback overlay (anonymous Discord feedback)
     if (key.name === 'i') {
-      state.feedbackOpen = true
-      state.bugReportBuffer = ''
-      state.bugReportStatus = 'idle'
-      state.bugReportError = null
+      openFeedbackOverlay()
       return
     }
 
@@ -1552,13 +1777,7 @@ export function createKeyHandler(ctx) {
 
     // 📖 Mode toggle key: Z cycles through the supported tool targets.
     if (key.name === 'z') {
-      const modeOrder = getToolModeOrder()
-      const currentIndex = modeOrder.indexOf(state.mode)
-      const nextIndex = (currentIndex + 1) % modeOrder.length
-      state.mode = modeOrder[nextIndex]
-      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
-      state.config.settings.preferredToolMode = state.mode
-      saveConfig(state.config)
+      cycleToolMode()
       return
     }
 

package/src/overlays.js

@@ -4,7 +4,7 @@
  *
  * @details
  *   This module centralizes all overlay rendering in one place:
- *   - Settings, Install Endpoints, Help, Smart Recommend, Feedback, Changelog
+ *   - Settings, Install Endpoints, Command Palette, Help, Smart Recommend, Feedback, Changelog
  *   - Settings diagnostics for provider key tests, including wrapped retry/error details
  *   - Recommend analysis timer orchestration and progress updates
  *
@@ -56,6 +56,7 @@ export function createOverlayRenderers(state, deps) {
     getToolMeta,
     getToolInstallPlan,
     padEndDisplay,
+    displayWidth,
   } = deps
 
   const bullet = (isCursor) => (isCursor ? themeColors.accentBold('  ❯ ') : themeColors.dim('    '))
@@ -534,6 +535,128 @@ export function createOverlayRenderers(state, deps) {
     return cleared.join('\n')
   }
 
+  // ─── Command palette renderer ──────────────────────────────────────────────
+  // 📖 renderCommandPalette draws a centered floating modal over the live table.
+  // 📖 It returns cursor-positioned ANSI rows instead of replacing the full screen,
+  // 📖 so ping updates continue to animate in the background behind the palette.
+  function renderCommandPalette() {
+    const terminalRows = state.terminalRows || 24
+    const terminalCols = state.terminalCols || 80
+    const panelWidth = Math.max(44, Math.min(96, terminalCols - 8))
+    const panelInnerWidth = Math.max(28, panelWidth - 4)
+    const panelPad = 2
+    const panelOuterWidth = panelWidth + (panelPad * 2)
+    const footerRowCount = 2
+    const headerRowCount = 3
+    const bodyRows = Math.max(6, Math.min(16, terminalRows - 12))
+
+    const truncatePlain = (text, width) => {
+      if (width <= 1) return ''
+      if (displayWidth(text) <= width) return text
+      if (width <= 2) return text.slice(0, width)
+      return text.slice(0, width - 1) + '…'
+    }
+
+    const highlightMatch = (label, positions = []) => {
+      if (!Array.isArray(positions) || positions.length === 0) return label
+      const posSet = new Set(positions)
+      let out = ''
+      for (let i = 0; i < label.length; i++) {
+        out += posSet.has(i) ? themeColors.accentBold(label[i]) : label[i]
+      }
+      return out
+    }
+
+    const allResults = Array.isArray(state.commandPaletteResults) ? state.commandPaletteResults.slice(0, 80) : []
+    const groupedLines = []
+    const cursorLineByRow = {}
+    let category = null
+
+    if (allResults.length === 0) {
+      groupedLines.push(themeColors.dim('  No command found. Try a broader query.'))
+    } else {
+      for (let idx = 0; idx < allResults.length; idx++) {
+        const entry = allResults[idx]
+        if (entry.category !== category) {
+          category = entry.category
+          groupedLines.push(themeColors.textBold(` ${category}`))
+        }
+
+        const isCursor = idx === state.commandPaletteCursor
+        const pointer = isCursor ? themeColors.accentBold('  ❯ ') : themeColors.dim('    ')
+        const shortcutText = entry.shortcut ? themeColors.dim(entry.shortcut) : ''
+        const shortcutWidth = entry.shortcut ? Math.min(16, displayWidth(entry.shortcut)) : 0
+        const labelMax = Math.max(12, panelInnerWidth - 8 - shortcutWidth)
+        const plainLabel = truncatePlain(entry.label, labelMax)
+        const label = highlightMatch(plainLabel, entry.matchPositions)
+        const row = `${pointer}${padEndDisplay(label, labelMax)}${entry.shortcut ? ` ${shortcutText}` : ''}`
+        cursorLineByRow[idx] = groupedLines.length
+        groupedLines.push(isCursor ? themeColors.bgCursor(row) : row)
+      }
+    }
+
+    const targetLine = cursorLineByRow[state.commandPaletteCursor] ?? 0
+    state.commandPaletteScrollOffset = keepOverlayTargetVisible(
+      state.commandPaletteScrollOffset,
+      targetLine,
+      groupedLines.length,
+      bodyRows
+    )
+    const { visible, offset } = sliceOverlayLines(groupedLines, state.commandPaletteScrollOffset, bodyRows)
+    state.commandPaletteScrollOffset = offset
+
+    const query = state.commandPaletteQuery || ''
+    const queryWithCursor = query.length > 0
+      ? themeColors.textBold(`${query}▏`)
+      : themeColors.dim('type a command…') + themeColors.accentBold('▏')
+
+    const panelLines = []
+    const title = themeColors.textBold('Command Palette')
+    const titleLeft = ` ${title}`
+    const titleRight = themeColors.dim('Esc close')
+    const titleWidth = Math.max(1, panelInnerWidth - 1 - displayWidth('Esc close'))
+    panelLines.push(`${padEndDisplay(titleLeft, titleWidth)} ${titleRight}`)
+    panelLines.push(` ${padEndDisplay(`> ${queryWithCursor}`, panelInnerWidth)}`)
+    panelLines.push(themeColors.dim(` ${'-'.repeat(Math.max(1, panelInnerWidth))}`))
+
+    for (const line of visible) {
+      panelLines.push(` ${padEndDisplay(line, panelInnerWidth)}`)
+    }
+
+    // 📖 Keep panel body stable by filling with blank rows when result list is short.
+    while (panelLines.length < bodyRows + headerRowCount) {
+      panelLines.push(` ${' '.repeat(panelInnerWidth)}`)
+    }
+
+    panelLines.push(themeColors.dim(` ${'-'.repeat(Math.max(1, panelInnerWidth))}`))
+    panelLines.push(` ${padEndDisplay(themeColors.dim('↑↓ navigate • Enter run • Type to search'), panelInnerWidth)}`)
+    panelLines.push(` ${padEndDisplay(themeColors.dim('PgUp/PgDn • Home/End'), panelInnerWidth)}`)
+
+    const blankPaddedLine = ' '.repeat(panelOuterWidth)
+    const paddedPanelLines = [
+      blankPaddedLine,
+      blankPaddedLine,
+      ...panelLines.map((line) => `${' '.repeat(panelPad)}${padEndDisplay(line, panelWidth)}${' '.repeat(panelPad)}`),
+      blankPaddedLine,
+      blankPaddedLine,
+    ]
+
+    const panelHeight = paddedPanelLines.length
+    const top = Math.max(1, Math.floor((terminalRows - panelHeight) / 2) + 1)
+    const left = Math.max(1, Math.floor((terminalCols - panelOuterWidth) / 2) + 1)
+
+    const tintedLines = paddedPanelLines.map((line) => {
+      const padded = padEndDisplay(line, panelOuterWidth)
+      return themeColors.overlayBgCommandPalette(padded)
+    })
+
+    // 📖 Absolute cursor positioning overlays the palette on top of the existing table.
+    // 📖 The next frame starts with ALT_HOME, so this remains stable without manual cleanup.
+    return tintedLines
+      .map((line, idx) => `\x1b[${top + idx};${left}H${line}`)
+      .join('')
+  }
+
   // ─── Help overlay renderer ────────────────────────────────────────────────
   // 📖 renderHelp: Draw the help overlay listing all key bindings.
   // 📖 Toggled with K key. Gives users a quick reference without leaving the TUI.
@@ -602,6 +725,7 @@ export function createOverlayRenderers(state, deps) {
     lines.push('')
     lines.push(`  ${heading('Controls')}`)
     lines.push(`  ${key('W')}  Toggle ping mode  ${hint('(speed 2s → normal 10s → slow 30s → forced 4s)')}`)
+    lines.push(`  ${key('Ctrl+P')}  Open command palette  ${hint('(search and run actions quickly)')}`)
     lines.push(`  ${key('E')}  Toggle configured models only  ${hint('(enabled by default)')}`)
     lines.push(`  ${key('Z')}  Cycle tool mode  ${hint('(OpenCode → Desktop → OpenClaw → Crush → Goose → Pi → Aider → Qwen → OpenHands → Amp)')}`)
     lines.push(`  ${key('F')}  Toggle favorite on selected row  ${hint('(⭐ pinned at top, persisted)')}`)
@@ -1058,6 +1182,7 @@ export function createOverlayRenderers(state, deps) {
     renderSettings,
     renderInstallEndpoints,
     renderToolInstallPrompt,
+    renderCommandPalette,
     renderHelp,
     renderRecommend,
     renderFeedback,

package/src/render-table.js

@@ -570,6 +570,7 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
   // 📖 Line 2: install flow, recommend, feedback, and extended hints.
   lines.push(
     themeColors.dim(`  `) +
+    hotkey('Ctrl+P', ' Command palette') + themeColors.dim(`  •  `) +
     hotkey('Y', ' Install endpoints') + themeColors.dim(`  •  `) +
     hotkey('Q', ' Smart Recommend') + themeColors.dim(`  •  `) +
     hotkey('G', ' Theme') + themeColors.dim(`  •  `) +

package/src/theme.js

@@ -52,6 +52,7 @@ const PALETTES = {
       recommend: [8, 21, 20],
       feedback: [31, 13, 20],
       changelog: [12, 24, 44],
+      commandPalette: [14, 20, 36],
     },
     cursor: {
       defaultBg: [39, 55, 90],
@@ -97,6 +98,7 @@ const PALETTES = {
       recommend: [246, 252, 248],
       feedback: [255, 247, 248],
       changelog: [244, 248, 255],
+      commandPalette: [242, 247, 255],
     },
     cursor: {
       defaultBg: [217, 231, 255],
@@ -312,4 +314,5 @@ export const themeColors = {
   overlayBgRecommend: (text) => paintBg(currentPalette().overlayBg.recommend, text, currentPalette().overlayFg),
   overlayBgFeedback: (text) => paintBg(currentPalette().overlayBg.feedback, text, currentPalette().overlayFg),
   overlayBgChangelog: (text) => paintBg(currentPalette().overlayBg.changelog, text, currentPalette().overlayFg),
+  overlayBgCommandPalette: (text) => paintBg(currentPalette().overlayBg.commandPalette, text, currentPalette().overlayFg),
 }