free-coding-models 0.2.11 → 0.2.13

package/CHANGELOG.md

@@ -2,10 +2,44 @@
 
 ---
 
+## 0.2.13
+
+### Added
+- **Persist UI view settings**: Tier filter (T key), provider filter (D key), and sort order now persist across session restarts — settings are saved to `~/.free-coding-models.json` under `config.settings` and automatically restored on next startup. Settings also mirror into active profiles so profile switching captures live view preferences.
+  - When T cycles tier: S+ tier is now remembered for next session
+  - When D cycles provider: Filtered provider is now remembered
+  - When sort keys (R/O/M/L/A/S/C/H/V/B/U) change order: Sort column and direction are now remembered
+  - Profile loading has priority over global `config.settings` so saved profiles override global defaults
+- **Reset view settings (Shift+R)**: New keyboard shortcut to instantly reset tier filter, provider filter, and sort order to defaults (All tier, no provider filter, avg sort ascending). Also clears persisted settings from `config.settings` so next restart returns to factory defaults.
+  - Useful when you've customized your view but want a fresh start
+  - Does not affect favorites, API keys, or other settings — only view state
+
+### Changed
+- **Help overlay (K key)**: Updated to document new Shift+R keybinding for resetting view settings
+
+---
+
+## 0.2.12
+
+### Added
+- **Auto-select models for all external tools**: All 10 supported tools (Aider, Crush, Goose, Claude Code, Codex, Gemini, Qwen, OpenHands, Amp, Pi) now automatically configure and pre-select the chosen model on launch — no manual model selection needed after pressing Enter.
+- **Changelog loader utility**: New `src/changelog-loader.js` module parses CHANGELOG.md for future TUI integration to display changes directly in the app instead of opening a browser.
+
+### Fixed
+- **Infinite update loop on startup**: Disabled forced auto-update that caused the app to detect the same update repeatedly after restarting. The app now checks for updates in the background without forcing installation.
+- **Removed disruptive browser window**: The auto-update process no longer opens a browser window to show the changelog — it now shows update information in the terminal only.
+- **Update failure tracking**: If update checks fail 3+ times, the app displays a prominent red footer warning: `⚠ OUTDATED version, please update` with manual update instructions instead of crashing.
+
+### Changed
+- **OpenHands integration improved**: Now sets `LLM_MODEL` and `LLM_API_KEY` environment variables for proper model pre-selection on launch.
+- **Amp integration improved**: Now writes `amp.model` to config file with the selected model ID.
+
+---
+
 ## 0.2.11
 
 ### Added
-- **Pi Coding Agent support**: Enabled Pi (pi.dev) as a launchable mode in the Z key cycle. Select a model and press Enter to configure Pi's config file and spawn the PI coding agent CLI with the chosen model and API endpoint.
+- **Pi Coding Agent support**: Enabled Pi (pi.dev) as a launchable mode in the Z key cycle. Select a model and press Enter to auto-configure Pi's model config and settings, then spawn the PI coding agent CLI with the chosen model pre-selected as the default.
 
 ---
 

package/README.md

@@ -80,13 +80,14 @@ By Vanessa Depraute
 - **📐 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.
 - **📜 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.
 - **🔄 Auto-retry** — Timeout models keep getting retried, nothing is ever "given up on"
 - **🎮 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` can auto-configure and launch `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, and `Goose`
-- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider directly into `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, or `Goose`, either with the full provider catalog or a curated subset of models
+- **🧰 Public tool launchers** — `Enter` auto-configures and launches 10+ tools: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Aider`, `Claude Code`, `Codex`, `Gemini`, `Qwen`, `OpenHands`, `Amp`, and `Pi`. All tools auto-select the chosen model on launch.
+- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider directly into `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Aider`, or `Gemini`, either with the full provider catalog or a curated subset of models
 - **📝 Feature Request (J key)** — Send anonymous feedback directly to the project team
 - **🐛 Bug Report (I key)** — Send anonymous bug reports directly to the project team
  - **🎨 Clean output** — Zero scrollback pollution, interface stays open until Ctrl+C
@@ -594,6 +595,30 @@ Use **↑↓** to scroll and **Esc** or **X** to return to the main table.
 
 ---
 
+## 🧰 Supported Tool Launchers
+
+You can use `free-coding-models` with 12+ AI coding tools. When you select a model and press Enter, the tool automatically configures and pre-selects your chosen model:
+
+| Tool | Flag | Auto-Config |
+|------|------|------------|
+| OpenCode CLI | `--opencode` | ~/.config/opencode/opencode.json |
+| OpenCode Desktop | `--opencode-desktop` | Opens Desktop app |
+| OpenClaw | `--openclaw` | ~/.openclaw/openclaw.json |
+| Crush | `--crush` | ~/.config/crush/crush.json |
+| Goose | `--goose` | Environment variables |
+| **Aider** | `--aider` | ~/.aider.conf.yml |
+| **Claude Code** | `--claude-code` | CLI flag |
+| **Codex** | `--codex` | CLI flag |
+| **Gemini** | `--gemini` | ~/.gemini/settings.json |
+| **Qwen** | `--qwen` | ~/.qwen/settings.json |
+| **OpenHands** | `--openhands` | LLM_MODEL env var |
+| **Amp** | `--amp` | ~/.config/amp/settings.json |
+| **Pi** | `--pi` | ~/.pi/agent/settings.json |
+
+Press **Z** to cycle through different tool modes in the TUI, or use flags to start in your preferred mode.
+
+---
+
 ## 🔌 OpenCode Integration
 
 **The easiest way** — let `free-coding-models` do everything:
@@ -604,7 +629,7 @@ Use **↑↓** to scroll and **Esc** or **X** to return to the main table.
 4. **Press Enter** — tool automatically:
    - Detects if NVIDIA NIM is configured in OpenCode
    - Sets your selected model as default in `~/.config/opencode/opencode.json`
-   - Launches OpenCode with the model ready to use
+   - Launches OpenCode with the model pre-selected and ready to use
 
 ### tmux sub-agent panes
 
@@ -907,6 +932,7 @@ This script:
 - **Shift+P** — Cycle through saved profiles (switches live TUI settings)
 - **Shift+S** — Save current TUI settings as a named profile (inline prompt)
 - **Q** — Open Smart Recommend overlay (find the best model for your task)
+- **N** — Open Changelog overlay (browse index of all versions, `Enter` to view details, `B` to go back)
 - **W** — Cycle ping mode (`FAST` 2s → `NORMAL` 10s → `SLOW` 30s → `FORCED` 4s)
 - **J / I** — Request feature / Report bug
 - **K / Esc** — Show help overlay / Close overlay

package/bin/free-coding-models.js

@@ -261,47 +261,26 @@ async function main() {
     ts: new Date().toISOString(),
   })
 
-  // 📖 Check for updates in the background
+  // 📖 Check for updates in the background (non-blocking, non-forced)
+  // 📖 The old auto-update on startup caused infinite loops, so we've moved to:
+  // 📖 1. Optional prompt when a new version is available (user chooses to update or not)
+  // 📖 2. Display "OUTDATED" in TUI footer if update check fails repeatedly
   let latestVersion = null
+  let isOutdated = false
   try {
     latestVersion = await checkForUpdate()
-  } catch {
-    // Silently fail - don't block the app if npm registry is unreachable
-  }
-
-  // 📖 Auto-update system: force updates and handle changelog automatically
-  // 📖 Skip when running from source (dev mode) — .git means we're in a repo checkout,
-  // 📖 not a global npm install. Auto-update would overwrite the global copy but restart
-  // 📖 the local one, causing an infinite update loop since LOCAL_VERSION never changes.
-  const isDevMode = existsSync(join(dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), '..', '.git'))
-  if (latestVersion && !isDevMode) {
-    console.log()
-    console.log(chalk.bold.red('  ⚠ AUTO-UPDATE AVAILABLE'))
-    console.log(chalk.red(`  Version ${latestVersion} will be installed automatically`))
-    console.log(chalk.dim('  Opening changelog in browser...'))
-    console.log()
-    
-    // 📖 Open changelog automatically
-    const { execSync } = require('child_process')
-    const changelogUrl = 'https://github.com/vava-nessa/free-coding-models/releases'
-    try {
-      if (isMac) {
-        execSync(`open "${changelogUrl}"`, { stdio: 'ignore' })
-      } else if (isWindows) {
-        execSync(`start "" "${changelogUrl}"`, { stdio: 'ignore' })
-      } else {
-        execSync(`xdg-open "${changelogUrl}"`, { stdio: 'ignore' })
-      }
-      console.log(chalk.green('  ✅ Changelog opened in browser'))
-    } catch {
-      console.log(chalk.yellow('  ⚠ Could not open browser automatically'))
-      console.log(chalk.dim(`  Visit manually: ${changelogUrl}`))
+    // 📖 Track update check failures - if it fails 3+ times, mark as outdated
+    if (!latestVersion && config.settings?.updateCheckFailures >= 3) {
+      isOutdated = true
     }
-    
-    // 📖 Force update immediately
-    console.log(chalk.cyan('  🚀 Starting auto-update...'))
-    runUpdate(latestVersion)
-    return // runUpdate will restart the process
+  } catch (err) {
+    // 📖 Silently fail - don't block the app if npm registry is unreachable
+    // 📖 But track the failure for outdated detection
+    const failures = (config.settings?.updateCheckFailures || 0) + 1
+    if (!config.settings) config.settings = {}
+    config.settings.updateCheckFailures = Math.min(failures, 3)
+    if (failures >= 3) isOutdated = true
+    saveConfig(config)
   }
 
   // 📖 Dynamic OpenRouter free model discovery — fetch live free models from API
@@ -383,8 +362,8 @@ async function main() {
     frame: 0,
     cursor: 0,
     selectedModel: null,
-    sortColumn: startupProfileSettings?.sortColumn || 'avg',
-    sortDirection: startupProfileSettings?.sortAsc === false ? 'desc' : 'asc',
+    sortColumn: startupProfileSettings?.sortColumn ?? config.settings?.sortColumn ?? 'avg',
+    sortDirection: (startupProfileSettings?.sortAsc ?? config.settings?.sortAsc ?? true) ? 'asc' : 'desc',
     pingInterval: PING_MODE_INTERVALS.speed, // 📖 Effective live interval derived from the active ping mode.
     pingMode: 'speed',            // 📖 Current ping mode: speed | normal | slow | forced.
     pingModeSource: 'startup',    // 📖 Why this mode is active: startup | manual | auto | idle | activity.
@@ -392,6 +371,8 @@ async function main() {
     lastPingTime: now,            // 📖 Track when last ping cycle started
     lastUserActivityAt: now,      // 📖 Any keypress refreshes this timer; inactivity can force slow mode.
     resumeSpeedOnActivity: false, // 📖 Set after idle slowdown so the next activity restarts a 60s speed burst.
+    latestVersion,                // 📖 Latest npm version available (null if none or check failed)
+    isOutdated,                   // 📖 Set to true if update check failed 3+ times (show red "OUTDATED" footer)
     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)
@@ -463,6 +444,12 @@ async function main() {
     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)
+    // 📖 Changelog overlay state (N key opens it)
+    changelogOpen: false,         // 📖 Whether the changelog overlay is active
+    changelogScrollOffset: 0,     // 📖 Vertical scroll offset for changelog overlay viewport
+    changelogPhase: 'index',      // 📖 'index' (all versions) | 'details' (specific version)
+    changelogCursor: 0,           // 📖 Selected row in index phase
+    changelogSelectedVersion: null, // 📖 Which version to show details for
     // 📖 Proxy startup status — set by autoStartProxyIfSynced, consumed by Task 3 indicator
     // 📖 null = not configured/not attempted
     // 📖 { phase: 'starting' } — proxy start in progress
@@ -625,8 +612,10 @@ async function main() {
 
   // 📖 originFilterMode: index into ORIGIN_CYCLE, 0=All, then each provider key in order
   const ORIGIN_CYCLE = [null, ...Object.keys(sources)]
-  state.tierFilterMode = startupProfileSettings?.tierFilter ? Math.max(0, TIER_CYCLE.indexOf(startupProfileSettings.tierFilter)) : 0
-  state.originFilterMode = 0
+  const resolvedTierFilter = startupProfileSettings?.tierFilter ?? config.settings?.tierFilter
+  state.tierFilterMode = resolvedTierFilter ? Math.max(0, TIER_CYCLE.indexOf(resolvedTierFilter)) : 0
+  const resolvedOriginFilter = config.settings?.originFilter
+  state.originFilterMode = resolvedOriginFilter ? Math.max(0, ORIGIN_CYCLE.indexOf(resolvedOriginFilter)) : 0
 
   function applyTierFilter() {
     const activeTier = TIER_CYCLE[state.tierFilterMode]
@@ -790,12 +779,12 @@ async function main() {
   process.stdin.on('keypress', onKeyPress)
   process.on('SIGCONT', noteUserActivity)
 
-  // 📖 Animation loop: render settings overlay, recommend overlay, help overlay, feature request overlay, bug report overlay, OR main table
+  // 📖 Animation loop: render settings overlay, recommend overlay, help overlay, feature request overlay, bug report overlay, changelog overlay, OR main table
   ticker = setInterval(() => {
     refreshAutoPingMode()
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.featureRequestOpen && !state.bugReportOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.featureRequestOpen && !state.bugReportOpen && !state.changelogOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
@@ -813,7 +802,9 @@ async function main() {
                 ? overlays.renderHelp()
               : state.logVisible
                 ? overlays.renderLog()
-                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true)
+              : state.changelogOpen
+                ? overlays.renderChangelog()
+                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion)
     process.stdout.write(ALT_HOME + content)
   }, Math.round(1000 / FPS))
 
@@ -821,7 +812,7 @@ async function main() {
   const initialVisible = state.results.filter(r => !r.hidden)
   state.visibleSorted = sortResultsWithPinnedFavorites(initialVisible, state.sortColumn, state.sortDirection)
 
-  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true))
+  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion))
 
   // 📖 If --recommend was passed, auto-open the Smart Recommend overlay on start
   if (cliArgs.recommendMode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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/changelog-loader.js

@@ -0,0 +1,118 @@
+/**
+ * @file changelog-loader.js
+ * @description Load and parse CHANGELOG.md for display in the TUI
+ *
+ * @functions
+ *   → loadChangelog() — Read and parse CHANGELOG.md into structured format
+ *   → getLatestChanges(version) — Return changelog for a specific version
+ *   → formatChangelogForDisplay(version) — Format for TUI rendering
+ *
+ * @exports loadChangelog, getLatestChanges, formatChangelogForDisplay
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const CHANGELOG_PATH = join(__dirname, '..', 'CHANGELOG.md')
+
+/**
+ * 📖 loadChangelog: Read and parse CHANGELOG.md
+ * @returns {Object} { versions: { '0.2.11': { added: [], fixed: [], changed: [] }, ... } }
+ */
+export function loadChangelog() {
+  if (!existsSync(CHANGELOG_PATH)) return { versions: {} }
+
+  const content = readFileSync(CHANGELOG_PATH, 'utf8')
+  const versions = {}
+  const lines = content.split('\n')
+  let currentVersion = null
+  let currentSection = null
+  let currentItems = []
+
+  for (const line of lines) {
+    // 📖 Match version headers: ## 0.2.11
+    const versionMatch = line.match(/^## ([\d.]+)/)
+    if (versionMatch) {
+      if (currentVersion && currentSection && currentItems.length > 0) {
+        if (!versions[currentVersion]) versions[currentVersion] = {}
+        versions[currentVersion][currentSection] = currentItems
+      }
+      currentVersion = versionMatch[1]
+      currentSection = null
+      currentItems = []
+      continue
+    }
+
+    // 📖 Match section headers: ### Added, ### Fixed, ### Changed
+    const sectionMatch = line.match(/^### (Added|Fixed|Changed|Updated)/)
+    if (sectionMatch) {
+      if (currentVersion && currentSection && currentItems.length > 0) {
+        if (!versions[currentVersion]) versions[currentVersion] = {}
+        versions[currentVersion][currentSection.toLowerCase()] = currentItems
+      }
+      currentSection = sectionMatch[1].toLowerCase()
+      currentItems = []
+      continue
+    }
+
+    // 📖 Match bullet points: - **text**: description
+    if (line.match(/^- /) && currentVersion && currentSection) {
+      currentItems.push(line.replace(/^- /, ''))
+    }
+  }
+
+  // 📖 Save the last section
+  if (currentVersion && currentSection && currentItems.length > 0) {
+    if (!versions[currentVersion]) versions[currentVersion] = {}
+    versions[currentVersion][currentSection] = currentItems
+  }
+
+  return { versions }
+}
+
+/**
+ * 📖 getLatestChanges: Return changelog for a specific version
+ * @param {string} version (e.g. '0.2.11')
+ * @returns {Object|null}
+ */
+export function getLatestChanges(version) {
+  const { versions } = loadChangelog()
+  return versions[version] || null
+}
+
+/**
+ * 📖 formatChangelogForDisplay: Format changelog section as array of strings for TUI
+ * @param {string} version
+ * @returns {string[]} formatted lines
+ */
+export function formatChangelogForDisplay(version) {
+  const changes = getLatestChanges(version)
+  if (!changes) return []
+
+  const lines = [
+    `📋 Changelog for v${version}`,
+    '',
+  ]
+
+  const sections = { added: 'Added', fixed: 'Fixed', changed: 'Changed', updated: 'Updated' }
+  for (const [key, label] of Object.entries(sections)) {
+    if (changes[key] && changes[key].length > 0) {
+      lines.push(`✨ ${label}:`)
+      for (const item of changes[key]) {
+        // 📖 Wrap long lines for display
+        const maxWidth = 70
+        let item_text = item.replace(/\*\*([^*]+)\*\*/g, '$1').replace(/`([^`]+)`/g, '$1')
+        if (item_text.length > maxWidth) {
+          item_text = item_text.substring(0, maxWidth - 3) + '...'
+        }
+        lines.push(`  • ${item_text}`)
+      }
+      lines.push('')
+    }
+  }
+
+  return lines
+}

package/src/key-handler.js

@@ -25,6 +25,8 @@
  * @exports { buildProviderModelsUrl, parseProviderModelIds, listProviderTestModels, classifyProviderTestOutcome, buildProviderTestDetail, createKeyHandler }
  */
 
+import { loadChangelog } from './changelog-loader.js'
+
 // 📖 Some providers need an explicit probe model because the first catalog entry
 // 📖 is not guaranteed to be accepted by their chat endpoint.
 const PROVIDER_TEST_MODEL_OVERRIDES = {
@@ -766,6 +768,70 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Changelog overlay: two-phase (index + details) with keyboard navigation
+    if (state.changelogOpen) {
+      const pageStep = Math.max(1, (state.terminalRows || 1) - 2)
+      const changelogData = loadChangelog()
+      const { versions } = changelogData
+      const versionList = Object.keys(versions).sort((a, b) => {
+        const aParts = a.split('.').map(Number)
+        const bParts = b.split('.').map(Number)
+        for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+          const aVal = aParts[i] || 0
+          const bVal = bParts[i] || 0
+          if (bVal !== aVal) return bVal - aVal
+        }
+        return 0
+      })
+
+      // 📖 Close changelog overlay
+      if (key.name === 'escape' || key.name === 'n') {
+        state.changelogOpen = false
+        state.changelogPhase = 'index'
+        state.changelogCursor = 0
+        state.changelogSelectedVersion = null
+        return
+      }
+
+      if (state.changelogPhase === 'index') {
+        // 📖 INDEX PHASE: Navigate through versions
+        if (key.name === 'up') {
+          state.changelogCursor = Math.max(0, state.changelogCursor - 1)
+          return
+        }
+        if (key.name === 'down') {
+          state.changelogCursor = Math.min(versionList.length - 1, state.changelogCursor + 1)
+          return
+        }
+        if (key.name === 'home') { state.changelogCursor = 0; return }
+        if (key.name === 'end') { state.changelogCursor = versionList.length - 1; return }
+        if (key.name === 'return') {
+          // 📖 Enter details phase for selected version
+          state.changelogPhase = 'details'
+          state.changelogSelectedVersion = versionList[state.changelogCursor]
+          state.changelogScrollOffset = 0
+          return
+        }
+      } else if (state.changelogPhase === 'details') {
+        // 📖 DETAILS PHASE: Scroll through selected version details
+        if (key.name === 'b') {
+          // 📖 B = back to index
+          state.changelogPhase = 'index'
+          state.changelogScrollOffset = 0
+          return
+        }
+        if (key.name === 'up') { state.changelogScrollOffset = Math.max(0, state.changelogScrollOffset - 1); return }
+        if (key.name === 'down') { state.changelogScrollOffset += 1; return }
+        if (key.name === 'pageup') { state.changelogScrollOffset = Math.max(0, state.changelogScrollOffset - pageStep); return }
+        if (key.name === 'pagedown') { state.changelogScrollOffset += pageStep; return }
+        if (key.name === 'home') { state.changelogScrollOffset = 0; return }
+        if (key.name === 'end') { state.changelogScrollOffset = Number.MAX_SAFE_INTEGER; return }
+      }
+
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+      return
+    }
+
     // 📖 Smart Recommend overlay: full keyboard handling while overlay is open.
     if (state.recommendOpen) {
       if (key.ctrl && key.name === 'c') { exit(0); return }
@@ -882,10 +948,11 @@ export function createKeyHandler(ctx) {
       const proxySyncRowIdx = updateRowIdx + 2
       const proxyPortRowIdx = updateRowIdx + 3
       const proxyCleanupRowIdx = updateRowIdx + 4
-      // 📖 Profile rows start after maintenance + proxy rows — one row per saved profile
+      const changelogViewRowIdx = updateRowIdx + 5
+      // 📖 Profile rows start after maintenance + proxy rows + changelog row — one row per saved profile
       const savedProfiles = listProfiles(state.config)
-      const profileStartIdx = updateRowIdx + 5
-      const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : proxyCleanupRowIdx
+      const profileStartIdx = updateRowIdx + 6
+      const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : changelogViewRowIdx
 
       // 📖 Edit/Add-key mode: capture typed characters for the API key
       if (state.settingsEditMode || state.settingsAddKeyMode) {
@@ -1059,6 +1126,17 @@ export function createKeyHandler(ctx) {
           return
         }
 
+        // 📖 Changelog row: Enter → open changelog overlay
+        if (state.settingsCursor === changelogViewRowIdx) {
+          state.settingsOpen = false
+          state.changelogOpen = true
+          state.changelogPhase = 'index'
+          state.changelogCursor = 0
+          state.changelogSelectedVersion = null
+          state.changelogScrollOffset = 0
+          return
+        }
+
         // 📖 Profile row: Enter → load the selected profile (apply its settings live)
         if (state.settingsCursor >= profileStartIdx && savedProfiles.length > 0) {
           const profileIdx = state.settingsCursor - profileStartIdx
@@ -1094,7 +1172,7 @@ export function createKeyHandler(ctx) {
       }
 
       if (key.name === 'space') {
-        if (state.settingsCursor === updateRowIdx || state.settingsCursor === proxyPortRowIdx || state.settingsCursor === proxyCleanupRowIdx) return
+        if (state.settingsCursor === updateRowIdx || state.settingsCursor === proxyPortRowIdx || state.settingsCursor === proxyCleanupRowIdx || state.settingsCursor === changelogViewRowIdx) return
         // 📖 Profile rows don't respond to Space
         if (state.settingsCursor >= profileStartIdx) return
 
@@ -1125,7 +1203,7 @@ export function createKeyHandler(ctx) {
       }
 
       if (key.name === 't') {
-        if (state.settingsCursor === updateRowIdx) return
+        if (state.settingsCursor === updateRowIdx || state.settingsCursor === proxyPortRowIdx || state.settingsCursor === proxyCleanupRowIdx || state.settingsCursor === changelogViewRowIdx) return
         // 📖 Profile rows don't respond to T (test key)
         if (state.settingsCursor >= profileStartIdx) return
 
@@ -1333,9 +1411,60 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 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'
+      // 📖 Mirror into active profile too so profile captures live preferences
+      if (state.activeProfile && state.config.profiles?.[state.activeProfile]) {
+        const profile = state.config.profiles[state.activeProfile]
+        if (!profile.settings || typeof profile.settings !== 'object') profile.settings = {}
+        profile.settings.tierFilter = state.config.settings.tierFilter
+        profile.settings.originFilter = state.config.settings.originFilter
+        profile.settings.sortColumn = state.config.settings.sortColumn
+        profile.settings.sortAsc = state.config.settings.sortAsc
+      }
+      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
+      // 📖 Also clear in active profile if loaded
+      if (state.activeProfile && state.config.profiles?.[state.activeProfile]) {
+        const profile = state.config.profiles[state.activeProfile]
+        if (profile.settings) {
+          delete profile.settings.tierFilter
+          delete profile.settings.originFilter
+          delete profile.settings.sortColumn
+          delete profile.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
+      return
+    }
+
     // 📖 Sorting keys: R=rank, O=origin, M=model, L=latest ping, A=avg ping, S=SWE-bench, C=context, H=health, V=verdict, B=stability, U=uptime, G=usage
     // 📖 T is reserved for tier filter cycling. Y now opens the install-endpoints flow.
     // 📖 D is now reserved for provider filter cycling
+    // 📖 Shift+R is reserved for reset view settings
     const sortKeys = {
       'r': 'rank', 'o': 'origin', 'm': 'model',
       'l': 'ping', 'a': 'avg', 's': 'swe', 'c': 'ctx', 'h': 'condition', 'v': 'verdict', 'b': 'stability', 'u': 'uptime', 'g': 'usage'
@@ -1355,6 +1484,7 @@ export function createKeyHandler(ctx) {
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
+      persistUiSettings()
       return
     }
 
@@ -1440,6 +1570,7 @@ export function createKeyHandler(ctx) {
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
+      persistUiSettings()
       return
     }
 
@@ -1452,6 +1583,7 @@ export function createKeyHandler(ctx) {
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
+      persistUiSettings()
       return
     }
 
@@ -1462,6 +1594,18 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Changelog overlay key: N = toggle changelog overlay
+    if (key.name === 'n') {
+      state.changelogOpen = !state.changelogOpen
+      if (state.changelogOpen) {
+        state.changelogScrollOffset = 0
+        state.changelogPhase = 'index'
+        state.changelogCursor = 0
+        state.changelogSelectedVersion = null
+      }
+      return
+    }
+
     // 📖 Mode toggle key: Z cycles through the supported tool targets.
     if (key.name === 'z') {
       const modeOrder = getToolModeOrder()

package/src/overlays.js

@@ -4,7 +4,7 @@
  *
  * @details
  *   This module centralizes all overlay rendering in one place:
- *   - Settings, Install Endpoints, Help, Log, Smart Recommend, Feature Request, Bug Report
+ *   - Settings, Install Endpoints, Help, Log, Smart Recommend, Feature Request, Bug Report, Changelog
  *   - Settings diagnostics for provider key tests, including wrapped retry/error details
  *   - Recommend analysis timer orchestration and progress updates
  *
@@ -17,6 +17,8 @@
  * @exports { createOverlayRenderers }
  */
 
+import { loadChangelog } from './changelog-loader.js'
+
 export function createOverlayRenderers(state, deps) {
   const {
     chalk,
@@ -138,6 +140,7 @@ export function createOverlayRenderers(state, deps) {
     const proxySyncRowIdx = updateRowIdx + 2
     const proxyPortRowIdx = updateRowIdx + 3
     const proxyCleanupRowIdx = updateRowIdx + 4
+    const changelogViewRowIdx = updateRowIdx + 5
     const proxySettings = getProxySettings(state.config)
     const EL = '\x1b[K'
     const lines = []
@@ -296,9 +299,15 @@ export function createOverlayRenderers(state, deps) {
     cursorLineByRow[proxyCleanupRowIdx] = lines.length
     lines.push(state.settingsCursor === proxyCleanupRowIdx ? chalk.bgRgb(45, 30, 30)(proxyCleanupRow) : proxyCleanupRow)
 
+    // 📖 Changelog viewer row
+    const changelogViewBullet = state.settingsCursor === changelogViewRowIdx ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+    const changelogViewRow = `${changelogViewBullet}${chalk.bold('View Changelog').padEnd(44)} ${chalk.dim('Enter browse version history')}`
+    cursorLineByRow[changelogViewRowIdx] = lines.length
+    lines.push(state.settingsCursor === changelogViewRowIdx ? chalk.bgRgb(30, 45, 30)(changelogViewRow) : changelogViewRow)
+
     // 📖 Profiles section — list saved profiles with active indicator + delete support
     const savedProfiles = listProfiles(state.config)
-    const profileStartIdx = updateRowIdx + 5
+    const profileStartIdx = updateRowIdx + 6
     const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : updateRowIdx
 
     lines.push('')
@@ -610,6 +619,8 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${chalk.yellow('Shift+S')}  Save current config as a named profile  ${chalk.dim('(inline prompt — type name + Enter)')}`)
     lines.push(`             ${chalk.dim('Profiles store: favorites, sort, tier filter, ping interval, configured-only filter, API keys.')}`)
     lines.push(`             ${chalk.dim('Use --profile <name> to load a profile on startup.')}`)
+    lines.push(`  ${chalk.yellow('Shift+R')}  Reset view settings  ${chalk.dim('(tier filter, sort, provider filter → defaults)')}`)
+    lines.push(`  ${chalk.yellow('N')}  Changelog  ${chalk.dim('(📋 browse all versions, Enter to view details)')}`)
     lines.push(`  ${chalk.yellow('K')} / ${chalk.yellow('Esc')}  Show/hide this help`)
     lines.push(`  ${chalk.yellow('Ctrl+C')}  Exit`)
     lines.push('')
@@ -1239,6 +1250,97 @@ export function createOverlayRenderers(state, deps) {
     return cleared.join('\n')
   }
 
+  // ─── Changelog overlay renderer ───────────────────────────────────────────
+  // 📖 renderChangelog: Two-phase overlay — index of all versions or details of one version
+  function renderChangelog() {
+    const EL = '\x1b[K'
+    const lines = []
+    const changelogData = loadChangelog()
+    const { versions } = changelogData
+    const versionList = Object.keys(versions).sort((a, b) => {
+      const aParts = a.split('.').map(Number)
+      const bParts = b.split('.').map(Number)
+      for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const aVal = aParts[i] || 0
+        const bVal = bParts[i] || 0
+        if (bVal !== aVal) return bVal - aVal
+      }
+      return 0
+    })
+
+    // 📖 Branding header
+    lines.push(`  ${chalk.cyanBright('🚀')} ${chalk.bold.cyanBright('free-coding-models')} ${chalk.dim(`v${LOCAL_VERSION}`)}`)
+
+    if (state.changelogPhase === 'index') {
+      // ═══════════════════════════════════════════════════════════════════════
+      // 📖 INDEX PHASE: Show all versions with selection
+      // ═══════════════════════════════════════════════════════════════════════
+      lines.push(`  ${chalk.bold('📋 Changelog - All Versions')}`)
+      lines.push(`  ${chalk.dim('— ↑↓ navigate • Enter select • Esc close')}`)
+      lines.push('')
+
+      for (let i = 0; i < versionList.length; i++) {
+        const version = versionList[i]
+        const changes = versions[version]
+        const isSelected = i === state.changelogCursor
+
+        // 📖 Count items in this version
+        let itemCount = 0
+        for (const key of ['added', 'fixed', 'changed', 'updated']) {
+          if (changes[key]) itemCount += changes[key].length
+        }
+
+        // 📖 Format version line with selection highlight
+        const versionStr = `  v${version.padEnd(8)} — ${itemCount} ${itemCount === 1 ? 'change' : 'changes'}`
+        if (isSelected) {
+          lines.push(chalk.inverse(versionStr))
+        } else {
+          lines.push(versionStr)
+        }
+      }
+
+      lines.push('')
+      lines.push(`  ${chalk.dim(`Total: ${versionList.length} versions`)}`)
+
+    } else if (state.changelogPhase === 'details') {
+      // ═══════════════════════════════════════════════════════════════════════
+      // 📖 DETAILS PHASE: Show detailed changes for selected version
+      // ═══════════════════════════════════════════════════════════════════════
+      lines.push(`  ${chalk.bold(`📋 v${state.changelogSelectedVersion}`)}`)
+      lines.push(`  ${chalk.dim('— ↑↓ / PgUp / PgDn scroll • B back • Esc close')}`)
+      lines.push('')
+
+      const changes = versions[state.changelogSelectedVersion]
+      if (changes) {
+        const sections = { added: '✨ Added', fixed: '🐛 Fixed', changed: '🔄 Changed', updated: '📝 Updated' }
+        for (const [key, label] of Object.entries(sections)) {
+          if (changes[key] && changes[key].length > 0) {
+            lines.push(`  ${chalk.yellow(label)}`)
+            for (const item of changes[key]) {
+              // 📖 Unwrap markdown bold/code markers for display
+              let displayText = item.replace(/\*\*([^*]+)\*\*/g, '$1').replace(/`([^`]+)`/g, '$1')
+              // 📖 Wrap long lines
+              const maxWidth = state.terminalCols - 16
+              if (displayText.length > maxWidth) {
+                displayText = displayText.substring(0, maxWidth - 3) + '…'
+              }
+              lines.push(`    • ${displayText}`)
+            }
+            lines.push('')
+          }
+        }
+      }
+    }
+
+    // 📖 Use scrolling with overlay handler
+    const CHANGELOG_OVERLAY_BG = chalk.bgRgb(10, 40, 80)  // Dark blue background
+    const { visible, offset } = sliceOverlayLines(lines, state.changelogScrollOffset, state.terminalRows)
+    state.changelogScrollOffset = offset
+    const tintedLines = tintOverlayLines(visible, CHANGELOG_OVERLAY_BG, state.terminalCols)
+    const cleared = tintedLines.map(l => l + EL)
+    return cleared.join('\n')
+  }
+
   // 📖 stopRecommendAnalysis: cleanup timers if user cancels during analysis
   function stopRecommendAnalysis() {
     if (state.recommendAnalysisTimer) { clearInterval(state.recommendAnalysisTimer); state.recommendAnalysisTimer = null }
@@ -1253,6 +1355,7 @@ export function createOverlayRenderers(state, deps) {
     renderRecommend,
     renderFeatureRequest,
     renderBugReport,
+    renderChangelog,
     startRecommendAnalysis,
     stopRecommendAnalysis,
   }

package/src/render-table.js

@@ -92,7 +92,7 @@ export function setActiveProxy(proxyInstance) {
 }
 
 // ─── renderTable: mode param controls footer hint text (opencode vs openclaw) ─────────
-export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false) {
+export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false, isOutdated = false, latestVersion = null) {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
 
@@ -648,25 +648,35 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     const latestLabel = chalk.redBright(` local v${LOCAL_VERSION} · latest v${versionStatus.latestVersion}`)
     lines.push(`  ${outdatedBadge}${latestLabel}`)
   }
-  lines.push(
-    chalk.rgb(255, 150, 200)('  Made with 💖 & ☕ by \x1b]8;;https://github.com/vava-nessa\x1b\\vava-nessa\x1b]8;;\x1b\\') +
-    chalk.dim('  •  ') +
-    '⭐ ' +
-    chalk.yellow('\x1b]8;;https://github.com/vava-nessa/free-coding-models\x1b\\Star on GitHub\x1b]8;;\x1b\\') +
-    chalk.dim('  •  ') +
-    '🤝 ' +
-    chalk.rgb(255, 165, 0)('\x1b]8;;https://github.com/vava-nessa/free-coding-models/graphs/contributors\x1b\\Contributors\x1b]8;;\x1b\\') +
-    chalk.dim('  •  ') +
-    '☕ ' +
-    chalk.rgb(255, 200, 100)('\x1b]8;;https://buymeacoffee.com/vavanessadev\x1b\\Buy me a coffee\x1b]8;;\x1b\\') +
-    chalk.dim('  •  ') +
-    '💬 ' +
-    chalk.rgb(200, 150, 255)('\x1b]8;;https://discord.gg/ZTNFHvvCkU\x1b\\Discord\x1b]8;;\x1b\\') +
-    chalk.dim(' → ') +
-    chalk.rgb(200, 150, 255)('https://discord.gg/ZTNFHvvCkU') +
-    chalk.dim('  •  ') +
-    chalk.dim('Ctrl+C Exit')
-  )
+
+  // 📖 Build footer line, with OUTDATED warning if isOutdated is true
+  let footerLine = ''
+  if (isOutdated) {
+    // 📖 Show OUTDATED in red background, high contrast warning
+    footerLine = chalk.bgRed.bold.white('  ⚠ OUTDATED version, please update with "npm i -g free-coding-models@latest"  ')
+  } else {
+    footerLine =
+      chalk.rgb(255, 150, 200)('  Made with 💖 & ☕ by \x1b]8;;https://github.com/vava-nessa\x1b\\vava-nessa\x1b]8;;\x1b\\') +
+      chalk.dim('  •  ') +
+      '⭐ ' +
+      chalk.yellow('\x1b]8;;https://github.com/vava-nessa/free-coding-models\x1b\\Star on GitHub\x1b]8;;\x1b\\') +
+      chalk.dim('  •  ') +
+      '🤝 ' +
+      chalk.rgb(255, 165, 0)('\x1b]8;;https://github.com/vava-nessa/free-coding-models/graphs/contributors\x1b\\Contributors\x1b]8;;\x1b\\') +
+      chalk.dim('  •  ') +
+      '☕ ' +
+      chalk.rgb(255, 200, 100)('\x1b]8;;https://buymeacoffee.com/vavanessadev\x1b\\Buy me a coffee\x1b]8;;\x1b\\') +
+      chalk.dim('  •  ') +
+      '💬 ' +
+      chalk.rgb(200, 150, 255)('\x1b]8;;https://discord.gg/ZTNFHvvCkU\x1b\\Discord\x1b]8;;\x1b\\') +
+      chalk.dim(' → ') +
+      chalk.rgb(200, 150, 255)('https://discord.gg/ZTNFHvvCkU') +
+      chalk.dim('  •  ') +
+      chalk.yellow('N') + chalk.dim(' Changelog') +
+      chalk.dim('  •  ') +
+      chalk.dim('Ctrl+C Exit')
+  }
+  lines.push(footerLine)
 
   // 📖 Append \x1b[K (erase to EOL) to each line so leftover chars from previous
   // 📖 frames are cleared. Then pad with blank cleared lines to fill the terminal,

package/src/tool-launchers.js

@@ -228,25 +228,36 @@ function writeQwenConfig(model, providerKey, apiKey, baseUrl) {
 }
 
 function writePiConfig(model, apiKey, baseUrl) {
-  const filePath = join(homedir(), '.pi', 'agent', 'models.json')
-  const backupPath = backupIfExists(filePath)
-  const config = readJson(filePath, { providers: {} })
-  if (!config.providers || typeof config.providers !== 'object') config.providers = {}
-  config.providers.freeCodingModels = {
+  // 📖 Write models.json with the selected provider config
+  const modelsFilePath = join(homedir(), '.pi', 'agent', 'models.json')
+  const modelsBackupPath = backupIfExists(modelsFilePath)
+  const modelsConfig = readJson(modelsFilePath, { providers: {} })
+  if (!modelsConfig.providers || typeof modelsConfig.providers !== 'object') modelsConfig.providers = {}
+  modelsConfig.providers.freeCodingModels = {
     baseUrl,
     api: 'openai-completions',
     apiKey,
     models: [{ id: model.modelId, name: model.label }],
   }
-  writeJson(filePath, config)
-  return { filePath, backupPath }
+  writeJson(modelsFilePath, modelsConfig)
+
+  // 📖 Write settings.json to set the model as default on next launch
+  const settingsFilePath = join(homedir(), '.pi', 'agent', 'settings.json')
+  const settingsBackupPath = backupIfExists(settingsFilePath)
+  const settingsConfig = readJson(settingsFilePath, {})
+  settingsConfig.defaultProvider = 'freeCodingModels'
+  settingsConfig.defaultModel = model.modelId
+  writeJson(settingsFilePath, settingsConfig)
+
+  return { filePath: modelsFilePath, backupPath: modelsBackupPath, settingsFilePath, settingsBackupPath }
 }
 
-function writeAmpConfig(baseUrl) {
+function writeAmpConfig(model, baseUrl) {
   const filePath = join(homedir(), '.config', 'amp', 'settings.json')
   const backupPath = backupIfExists(filePath)
   const config = readJson(filePath, {})
   config['amp.url'] = baseUrl
+  config['amp.model'] = model.modelId
   writeJson(filePath, config)
   return { filePath, backupPath }
 }
@@ -346,19 +357,24 @@ export async function startExternalTool(mode, model, config) {
   }
 
   if (mode === 'openhands') {
-    console.log(chalk.dim('  📖 OpenHands is launched with --override-with-envs so the selected model applies immediately.'))
+    // 📖 OpenHands supports LLM_MODEL env var to set the default model
+    env.LLM_MODEL = model.modelId
+    env.LLM_API_KEY = apiKey || env.LLM_API_KEY
+    if (baseUrl) env.LLM_BASE_URL = baseUrl
+    console.log(chalk.dim(`  📖 OpenHands launched with model: ${model.modelId}`))
     return spawnCommand('openhands', ['--override-with-envs'], env)
   }
 
   if (mode === 'amp') {
-    printConfigResult(meta.label, writeAmpConfig(baseUrl))
-    console.log(chalk.yellow('  ⚠ Amp does not officially expose arbitrary model switching like the other CLIs.'))
-    console.log(chalk.dim('  The proxy URL is written, then Amp is launched so you can reuse the current endpoint.'))
+    printConfigResult(meta.label, writeAmpConfig(model, baseUrl))
+    console.log(chalk.dim(`  📖 Amp config updated with model: ${model.modelId}`))
     return spawnCommand('amp', [], env)
   }
 
   if (mode === 'pi') {
-    printConfigResult(meta.label, writePiConfig(model, apiKey, baseUrl))
+    const piResult = writePiConfig(model, apiKey, baseUrl)
+    printConfigResult(meta.label, { filePath: piResult.filePath, backupPath: piResult.backupPath })
+    printConfigResult(meta.label, { filePath: piResult.settingsFilePath, backupPath: piResult.settingsBackupPath })
     return spawnCommand('pi', [], env)
   }