free-coding-models 0.1.87 → 0.2.0

package/README.md

@@ -67,7 +67,7 @@
 
 - **🎯 Coding-focused** — Only LLM models optimized for code generation, not chat or vision
 - **🌐 Multi-provider** — Models from NVIDIA NIM, Groq, Cerebras, SambaNova, OpenRouter, Hugging Face Inference, Replicate, DeepInfra, Fireworks AI, Codestral, Hyperbolic, Scaleway, Google AI, SiliconFlow, Together AI, Cloudflare Workers AI, Perplexity API, Alibaba Cloud (DashScope), ZAI, and iFlow
-- **⚙️ Settings screen** — Press `P` to manage provider API keys, enable/disable providers, test keys live, and manually check/install updates
+- **⚙️ Settings screen** — Press `P` to manage provider API keys, enable/disable providers, configure the proxy, clean OpenCode proxy sync, and manually check/install updates
 - **🔀 Multi-account Proxy (`fcm-proxy`)** — Automatically starts a local reverse proxy that groups all your accounts into a single provider in OpenCode; supports multi-account rotation and auto-detects usage limits to swap between providers.
 - **🚀 Parallel pings** — All models tested simultaneously via native `fetch`
 - **📊 Real-time animation** — Watch latency appear live in alternate screen buffer
@@ -77,13 +77,13 @@
 - **📊 Uptime tracking** — Percentage of successful pings shown in real-time
 - **📐 Stability score** — Composite 0–100 score measuring consistency (p95, jitter, spikes, uptime)
 - **📊 Usage tracking** — Monitor remaining quota for each exact provider/model pair when the provider exposes it; otherwise the TUI shows a green dot instead of a misleading percentage.
-- **📜 Live Log Viewer** — Press `X` to view real-time activity and error logs in a focused TUI overlay.
+- **📜 Request Log Overlay** — Press `X` to inspect recent proxied requests and token usage for exact provider/model pairs.
 - **🛠 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
-- **🔀 Startup mode menu** — Choose between OpenCode and OpenClaw before the TUI launches
 - **💻 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`
 - **📝 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
@@ -150,7 +150,7 @@ bunx free-coding-models YOUR_API_KEY
 ## 🚀 Usage
 
 ```bash
-# Just run it — shows a startup menu to pick OpenCode or OpenClaw, prompts for API key if not set
+# Just run it — starts in OpenCode CLI mode, prompts for API key if not set
 free-coding-models
 
 # Explicitly target OpenCode CLI (TUI + Enter launches OpenCode CLI)
@@ -162,6 +162,10 @@ free-coding-models --opencode-desktop
 # Explicitly target OpenClaw (TUI + Enter sets model as default in OpenClaw)
 free-coding-models --openclaw
 
+# Launch other supported public tools with the selected model
+free-coding-models --crush
+free-coding-models --goose
+
 # Show only top-tier models (A+, S, S+)
 free-coding-models --best
 
@@ -179,30 +183,17 @@ free-coding-models --openclaw --tier S
 free-coding-models --opencode --best
 ```
 
-### Startup mode menu
-
-When you run `free-coding-models` without `--opencode` or `--openclaw`, you get an interactive startup menu:
-
-```
-  ⚡ Free Coding Models — Choose your tool
-
-  ❯ 💻 OpenCode CLI
-       Press Enter on a model → launch OpenCode CLI with it as default
+### Choosing the target tool
 
-    🖥 OpenCode Desktop
-       Press Enter on a model → set model & open OpenCode Desktop app
+Running `free-coding-models` with no launcher flag starts in **OpenCode CLI** mode.
 
-    🦞 OpenClaw
-       Press Enter on a model → set it as default in OpenClaw config
-
-  ↑↓ Navigate  •  Enter Select  •  Ctrl+C Exit
-```
-
-Use `↑↓` arrows to select, `Enter` to confirm. Then the TUI launches with your chosen mode shown in the header badge.
+- Press **`Z`** in the TUI to cycle the public launch targets: `OpenCode CLI` → `OpenCode Desktop` → `OpenClaw` → `Crush` → `Goose`
+- Or start directly in the target mode with a CLI flag such as `--opencode-desktop`, `--openclaw`, `--crush`, or `--goose`
+- The active target is always visible in the header badge before you press `Enter`
 
 **How it works:**
- 1. **Ping phase** — All enabled models are pinged in parallel (up to 150 across 20 providers)
- 2. **Continuous monitoring** — Models start at 2s re-pings for 60s, then fall back to 10s automatically
+ 1. **Ping phase** — All enabled models are pinged in parallel (up to 159 across 20 providers)
+ 2. **Continuous monitoring** — Models start at 2s re-pings for 60s, then fall back to 10s automatically, and slow to 30s after 5 minutes idle unless you force 4s mode with `W`
 3. **Real-time updates** — Watch "Latest", "Avg", and "Up%" columns update live
 4. **Select anytime** — Use ↑↓ arrows to navigate, press Enter on a model to act
 5. **Smart detection** — Automatically detects if NVIDIA NIM is configured in OpenCode or OpenClaw
@@ -257,14 +248,18 @@ Press **`P`** to open the Settings screen at any time:
   2) Profile → API Keys → Generate
   3) Press T to test your key
 
-  ↑↓ Navigate  •  Enter Edit key / Check-or-Install update  •  Space Toggle enabled  •  T Test key  •  U Check updates  •  Esc Close
+  ↑↓ Navigate  •  Enter Edit/Run  •  + Add key  •  - Remove key  •  Space Toggle  •  T Test key  •  S Sync→OpenCode  •  R Restore backup  •  U Updates  •  ⌫ Delete profile  •  Esc Close
 ```
 
 - **↑↓** — navigate providers
-- **Enter** — enter inline key edit mode (type your key, Enter to save, Esc to cancel)
+- **Enter** — edit the selected key, run maintenance actions, or load the selected profile
+- **+ / -** — add another key for the selected provider or remove one
 - **Space** — toggle provider enabled/disabled
 - **T** — fire a real test ping to verify the key works (shows ✅/❌)
+- **S** — sync `fcm-proxy` into OpenCode when proxy mode + persistence are enabled
+- **R** — restore the last OpenCode backup created by sync/cleanup flows
 - **U** — manually check npm for a newer version
+- **Backspace** — delete the selected saved profile
 - **Esc** — close settings and reload models list
 
  Keys are saved to `~/.free-coding-models.json` (permissions `0600`).
@@ -364,7 +359,7 @@ TOGETHER_API_KEY=together_xxx free-coding-models
 2. Create API key (`PERPLEXITY_API_KEY`)
 
 **Alibaba Cloud (DashScope)** (8 models, Qwen3-Coder family):
-1. Sign up at [dashscope.console.alibabacloud.com](https://dashscope.console.alibabacloud.com)
+1. Sign up at [modelstudio.console.alibabacloud.com](https://modelstudio.console.alibabacloud.com)
 2. Activate Model Studio (1M free tokens per model, Singapore region, 90 days)
 3. Create API key (`DASHSCOPE_API_KEY`)
 
@@ -513,6 +508,11 @@ Stability = 0.30 × p95_score
 
 `free-coding-models` includes a built-in reverse proxy that can group all your provider accounts into a single virtual provider.
 
+Important:
+- **Disabled by default** — proxy mode is now opt-in from the Settings screen (`P`)
+- **Direct OpenCode launch remains the default** when proxy mode is off
+- **Token/request logs are only populated by proxied requests** today
+
 ### Why use the proxy?
 - **Unified Provider**: Instead of managing 20+ providers in your coding assistant, just use `fcm-proxy`.
 - **Automatic Rotation**: When one account hits its rate limit (429), the proxy automatically swaps to the next available account for that model.
@@ -520,18 +520,26 @@ Stability = 0.30 × p95_score
 - **Transparent Bridging**: Automatically handles non-standard API paths (like ZAI's `/api/coding/paas/v4/`) and converts them to standard OpenAI-compatible `/v1/` calls.
 
 ### How to use it
-The proxy starts automatically when you select a model in OpenCode mode if you have `fcm-proxy` configured. You can see its status (port and active account count) in the TUI footer.
+1. Open **Settings** with `P`
+2. Enable **Proxy mode (opt-in)**
+3. Optionally enable **Persist proxy in OpenCode** if you explicitly want `fcm-proxy` written to `~/.config/opencode/opencode.json`
+4. Optionally set **Preferred proxy port** (`0` = auto)
+5. Use `S` in Settings to sync the proxy catalog into OpenCode only when you actually want that persistent config
+
+Cleanup:
+- Use the Settings action **Clean OpenCode proxy config**
+- Or run `free-coding-models --clean-proxy`
 
 ---
 
-## 📜 Log Viewer
+## 📜 Request Log Overlay
 
-Press **`X`** at any time to open the dedicated Log Viewer overlay.
+Press **`X`** at any time to open the dedicated request-log overlay.
 
-- **Real-time Activity**: See every ping, rotation, and proxy request as it happens.
-- **Error Diagnostics**: View detailed error messages from providers when a ping fails.
-- **Quota Tracking**: Monitor how the tool discovers and updates your remaining quota.
-- **Auto-Pruning**: The log history is automatically managed to stay concise and relevant.
+- **Proxy-only accounting**: Entries are written when requests flow through the multi-account proxy.
+- **Exact token totals**: The overlay aggregates prompt+completion usage per proxied request.
+- **Per-request visibility**: You can inspect provider, model, status, token count, and latency for recent requests.
+- **Startup table reuse**: The `Used` column in the main table is derived from the same request log file.
 
 Use **↑↓** to scroll and **Esc** or **X** to return to the main table.
 
@@ -541,7 +549,7 @@ Use **↑↓** to scroll and **Esc** or **X** to return to the main table.
 
 **The easiest way** — let `free-coding-models` do everything:
 
-1. **Run**: `free-coding-models --opencode` (or choose OpenCode from the startup menu)
+1. **Run**: `free-coding-models --opencode` (or launch with no flag to use the default OpenCode CLI mode)
 2. **Wait** for models to be pinged (green ✅ status)
 3. **Navigate** with ↑↓ arrows to your preferred model
 4. **Press Enter** — tool automatically:
@@ -624,7 +632,7 @@ OpenClaw is an autonomous AI agent daemon. `free-coding-models` can configure it
 free-coding-models --openclaw
 ```
 
-Or run without flags and choose **OpenClaw** from the startup menu.
+Or press **`Z`** in the TUI until the header shows **OpenClaw**, then press **Enter** on a model.
 
 1. **Wait** for models to be pinged
 2. **Navigate** with ↑↓ arrows to your preferred model
@@ -729,6 +737,7 @@ This script:
 │  2. Ping ALL models in parallel                                  │
 │  3. Display real-time table with Latest/Avg/Stability/Up%        │
 │  4. Re-ping ALL models at 2s on startup, then 10s steady-state │
+│     and 30s after 5m idle unless forced back to 4s with W      │
 │  5. Update rolling averages + stability scores per model        │
 │  6. User can navigate with ↑↓ and select with Enter            │
 │  7. On Enter (OpenCode): set model, launch OpenCode             │
@@ -816,29 +825,32 @@ This script:
 
 | Flag | Description |
 |------|-------------|
-| *(none)* | Show startup menu to choose OpenCode or OpenClaw |
+| *(none)* | Start in OpenCode CLI mode |
 | `--opencode` | OpenCode CLI mode — Enter launches OpenCode CLI with selected model |
- | `--opencode-desktop` | OpenCode Desktop mode — Enter sets model & opens OpenCode Desktop app |
- | `--openclaw` | OpenClaw mode — Enter sets selected model as default in OpenClaw |
- | `--best` | Show only top-tier models (A+, S, S+) |
- | `--fiable` | Analyze 10 seconds, output the most reliable model as `provider/model_id` |
- | `--tier S` | Show only S+ and S tier models |
+| `--opencode-desktop` | OpenCode Desktop mode — Enter sets model and opens OpenCode Desktop |
+| `--openclaw` | OpenClaw mode — Enter sets selected model as default in OpenClaw |
+| `--crush` | Crush mode — Enter writes `crush.json` and launches Crush |
+| `--goose` | Goose mode — Enter launches Goose with env-based provider config |
+| `--best` | Show only top-tier models (A+, S, S+) |
+| `--fiable` | Analyze 10 seconds, output the most reliable model as `provider/model_id` |
+| `--tier S` | Show only S+ and S tier models |
 | `--tier A` | Show only A+, A, A- tier models |
 | `--tier B` | Show only B+, B tier models |
 | `--tier C` | Show only C tier models |
 | `--profile <name>` | Load a saved config profile on startup |
 | `--recommend` | Auto-open Smart Recommend overlay on start |
+| `--clean-proxy` | Remove persisted `fcm-proxy` config from OpenCode |
 
 **Keyboard shortcuts (main TUI):**
 - **↑↓** — Navigate models
-- **Enter** — Select model (launches OpenCode or sets OpenClaw default, depending on mode)
+- **Enter** — Select model and launch the current target tool from the header badge
 - **R/Y/S/C/M/O/L/A/H/V/B/U/G** — Sort by Rank/Tier/SWE/Ctx/Model/Provider/Latest/Avg/Health/Verdict/Stability/Up%/Usage
 - **F** — Toggle favorite on selected model (⭐ in Model column, pinned at top)
 - **T** — Cycle tier filter (All → S+ → S → A+ → A → A- → B+ → B → C → All)
 - **D** — Cycle provider filter (All → NIM → Groq → ...)
 - **E** — Toggle configured-only mode (on by default, persisted across sessions and profiles)
-- **Z** — Cycle mode (OpenCode CLI → OpenCode Desktop → OpenClaw)
-- **X** — **Toggle Token Logs** (view recent request/token usage logs)
+- **Z** — Cycle target tool (OpenCode CLI → OpenCode Desktop → OpenClaw → Crush → Goose)
+- **X** — Toggle request logs (recent proxied request/token usage logs)
 - **P** — Open Settings (manage API keys, toggles, updates, profiles)
 - **Shift+P** — Cycle through saved profiles (switches live TUI settings)
 - **Shift+S** — Save current TUI settings as a named profile (inline prompt)
@@ -870,6 +882,7 @@ Profiles let you save and restore different TUI configurations — useful if you
 - Sort column and direction
 - Tier filter
 - Ping mode
+- Configured-only filter
 - API keys
 
 **Saving a profile:**

package/bin/free-coding-models.js

@@ -15,8 +15,8 @@
  *   - Rolling averages calculated from ALL successful pings since start
  *   - Best-per-tier highlighting with medals (🥇🥈🥉)
  *   - Interactive navigation with arrow keys directly in the table
- *   - Instant OpenCode OR OpenClaw action on Enter key press
- *   - Startup mode menu (OpenCode CLI vs OpenCode Desktop vs OpenClaw) when no flag is given
+ *   - Instant OpenCode / OpenClaw / external-tool action on Enter key press
+ *   - Direct mode flags plus an in-app Z-cycle for the public launcher set
  *   - Automatic config detection and model setup for both tools
  *   - JSON config stored in ~/.free-coding-models.json (auto-migrates from old plain-text)
  *   - Multi-provider support via sources.js (NIM/Groq/Cerebras/OpenRouter/Hugging Face/Replicate/DeepInfra/... — extensible)
@@ -34,7 +34,6 @@
  *   - `sendUsageTelemetry`: Fire-and-forget anonymous app-start event
  *   - `ensureFavoritesConfig` / `toggleFavoriteModel`: Persist and toggle pinned favorites
  *   - `promptApiKey`: Interactive wizard for first-time multi-provider API key setup
- *   - `promptModeSelection`: Startup menu to choose OpenCode vs OpenClaw
  *   - `buildPingRequest` / `ping`: Build provider-specific probe requests and measure latency
  *   - `renderTable`: Generate ASCII table with colored latency indicators and status emojis
  *   - `getAvg`: Calculate average latency from all successful pings
@@ -66,14 +65,15 @@
  *   - OpenCode config: ~/.config/opencode/opencode.json
  *   - OpenClaw config: ~/.openclaw/openclaw.json
  *   - Ping timeout: 15s per attempt
- *   - Ping interval: 60 seconds (continuous monitoring mode)
+ *   - Ping cadence: 2s startup burst for 60s, 10s steady state, 30s after 5m idle, forced 4s via `W`
  *   - Animation: 12 FPS with braille spinners
  *
  *   🚀 CLI flags:
- *   - (no flag): Show startup menu → choose OpenCode or OpenClaw
+ *   - (no flag): Start in OpenCode CLI mode
  *   - --opencode: OpenCode CLI mode (launch CLI with selected model)
  *   - --opencode-desktop: OpenCode Desktop mode (set model & open Desktop app)
  *   - --openclaw: OpenClaw mode (set selected model as default in OpenClaw)
+ *   - --crush / --goose: launch the currently selected model in the supported external CLI
  *   - --best: Show only top-tier models (A+, S, S+)
  *   - --fiable: Analyze 10s and output the most reliable model
  *   - --no-telemetry: Disable anonymous usage analytics for this run
@@ -92,10 +92,10 @@ import { homedir } from 'os'
 import { join, dirname } from 'path'
 import { MODELS, sources } from '../sources.js'
 import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS, formatCtxWindow, labelFromId, getProxyStatusInfo } from '../src/utils.js'
-import { loadConfig, saveConfig, getApiKey, resolveApiKeys, addApiKey, removeApiKey, isProviderEnabled, saveAsProfile, loadProfile, listProfiles, deleteProfile, getActiveProfileName, setActiveProfile, _emptyProfileSettings } from '../src/config.js'
+import { loadConfig, saveConfig, getApiKey, getProxySettings, resolveApiKeys, addApiKey, removeApiKey, isProviderEnabled, saveAsProfile, loadProfile, listProfiles, deleteProfile, getActiveProfileName, setActiveProfile, _emptyProfileSettings } from '../src/config.js'
 import { buildMergedModels } from '../src/model-merger.js'
 import { ProxyServer } from '../src/proxy-server.js'
-import { loadOpenCodeConfig, saveOpenCodeConfig, syncToOpenCode, restoreOpenCodeBackup } from '../src/opencode-sync.js'
+import { loadOpenCodeConfig, saveOpenCodeConfig, syncToOpenCode, restoreOpenCodeBackup, cleanupOpenCodeProxyConfig } from '../src/opencode-sync.js'
 import { usageForRow as _usageForRow } from '../src/usage-reader.js'
 import { loadRecentLogs } from '../src/log-reader.js'
 import { buildProviderModelTokenKey, loadTokenUsageByProviderModel } from '../src/token-usage-reader.js'
@@ -112,10 +112,12 @@ import { checkForUpdateDetailed, checkForUpdate, runUpdate, promptUpdateNotifica
 import { promptApiKey } from '../src/setup.js'
 import { stripAnsi, maskApiKey, displayWidth, padEndDisplay, tintOverlayLines, keepOverlayTargetVisible, sliceOverlayLines, calculateViewport, sortResultsWithPinnedFavorites, renderProxyStatusLine, adjustScrollOffset } from '../src/render-helpers.js'
 import { renderTable } from '../src/render-table.js'
-import { setOpenCodeModelData, startOpenCode, startOpenCodeDesktop, startProxyAndLaunch, autoStartProxyIfSynced, ensureProxyRunning, buildProxyTopologyFromConfig } from '../src/opencode.js'
+import { setOpenCodeModelData, startOpenCode, startOpenCodeDesktop, startProxyAndLaunch, autoStartProxyIfSynced, ensureProxyRunning, buildProxyTopologyFromConfig, isProxyEnabledForConfig } from '../src/opencode.js'
 import { startOpenClaw } from '../src/openclaw.js'
 import { createOverlayRenderers } from '../src/overlays.js'
 import { createKeyHandler } from '../src/key-handler.js'
+import { getToolModeOrder } from '../src/tool-metadata.js'
+import { startExternalTool } from '../src/tool-launchers.js'
 
 // 📖 mergedModels: cross-provider grouped model list (one entry per label, N providers each)
 // 📖 mergedModelByLabel: fast lookup map from display label → merged model entry
@@ -176,6 +178,16 @@ async function main() {
   ensureTelemetryConfig(config)
   ensureFavoritesConfig(config)
 
+  if (cliArgs.cleanProxyMode) {
+    const cleaned = cleanupOpenCodeProxyConfig()
+    console.log()
+    console.log(chalk.green('  ✅ OpenCode proxy cleanup complete'))
+    console.log(chalk.dim(`  Config: ${cleaned.path}`))
+    console.log(chalk.dim(`  Removed provider: ${cleaned.removedProvider ? 'yes' : 'no'}  •  Removed default model: ${cleaned.removedModel ? 'yes' : 'no'}`))
+    console.log()
+    process.exit(0)
+  }
+
   // 📖 If --profile <name> was passed, load that profile into the live config
   let startupProfileSettings = null
   if (cliArgs.profileName) {
@@ -204,11 +216,28 @@ async function main() {
   // 📖 Backward-compat: keep apiKey var for startOpenClaw() which still needs it
   let apiKey = getApiKey(config, 'nvidia')
 
-  // 📖 Default mode: OpenCode CLI
+  // 📖 Default mode: OpenCode CLI.
+  // 📖 Additional external tools can now be selected via dedicated flags.
   let mode = 'opencode'
-  if (cliArgs.openClawMode) mode = 'openclaw'
-  else if (cliArgs.openCodeDesktopMode) mode = 'opencode-desktop'
-  else if (cliArgs.openCodeMode) mode = 'opencode'
+  const requestedMode = getToolModeOrder().find((toolMode) => {
+    const flagByMode = {
+      opencode: cliArgs.openCodeMode,
+      'opencode-desktop': cliArgs.openCodeDesktopMode,
+      openclaw: cliArgs.openClawMode,
+      aider: cliArgs.aiderMode,
+      crush: cliArgs.crushMode,
+      goose: cliArgs.gooseMode,
+      'claude-code': cliArgs.claudeCodeMode,
+      codex: cliArgs.codexMode,
+      gemini: cliArgs.geminiMode,
+      qwen: cliArgs.qwenMode,
+      openhands: cliArgs.openHandsMode,
+      amp: cliArgs.ampMode,
+      pi: cliArgs.piMode,
+    }
+    return flagByMode[toolMode] === true
+  })
+  if (requestedMode) mode = requestedMode
 
   // 📖 Track app opening early so fast exits are still counted.
   // 📖 Must run before update checks because npm registry lookups can add startup delay.
@@ -353,6 +382,8 @@ async function main() {
     scrollOffset: 0,              // 📖 First visible model index in viewport
     terminalRows: process.stdout.rows || 24,  // 📖 Current terminal height
     terminalCols: process.stdout.columns || 80, // 📖 Current terminal width
+    widthWarningStartedAt: (process.stdout.columns || 80) < 166 ? now : null, // 📖 Start the narrow-terminal countdown immediately when booting in a small viewport.
+    widthWarningDismissed: false, // 📖 Esc hides the narrow-terminal warning early for the current narrow-width session.
     // 📖 Settings screen state (P key opens it)
     settingsOpen: false,          // 📖 Whether settings overlay is active
     settingsCursor: 0,            // 📖 Which provider row is selected in settings
@@ -364,6 +395,8 @@ async function main() {
     settingsUpdateState: 'idle',  // 📖 'idle'|'checking'|'available'|'up-to-date'|'error'|'installing'
     settingsUpdateLatestVersion: null, // 📖 Latest npm version discovered from manual check
     settingsUpdateError: null,    // 📖 Last update-check error message for maintenance row
+    settingsProxyPortEditMode: false, // 📖 Whether Settings is editing the preferred proxy port field.
+    settingsProxyPortBuffer: '',  // 📖 Inline input buffer for the preferred proxy port (0 = auto).
     config,                       // 📖 Live reference to the config object (updated on save)
     visibleSorted: [],            // 📖 Cached visible+sorted models — shared between render loop and key handlers
     helpVisible: false,           // 📖 Whether the help overlay (K key) is active
@@ -410,8 +443,20 @@ async function main() {
 
   // 📖 Re-clamp viewport on terminal resize
   process.stdout.on('resize', () => {
+    const prevCols = state.terminalCols
     state.terminalRows = process.stdout.rows || 24
     state.terminalCols = process.stdout.columns || 80
+    if (state.terminalCols < 166) {
+      if (prevCols >= 166 || state.widthWarningDismissed) {
+        state.widthWarningStartedAt = Date.now()
+        state.widthWarningDismissed = false
+      } else if (!state.widthWarningStartedAt) {
+        state.widthWarningStartedAt = Date.now()
+      }
+    } else {
+      state.widthWarningStartedAt = null
+      state.widthWarningDismissed = false
+    }
     adjustScrollOffset(state)
   })
 
@@ -524,6 +569,7 @@ async function main() {
     PROVIDER_METADATA,
     LOCAL_VERSION,
     getApiKey,
+    getProxySettings,
     resolveApiKeys,
     isProviderEnabled,
     listProfiles,
@@ -557,6 +603,7 @@ async function main() {
     MODELS,
     sources,
     getApiKey,
+    getProxySettings,
     resolveApiKeys,
     addApiKey,
     removeApiKey,
@@ -578,6 +625,7 @@ async function main() {
     ENV_VAR_NAMES,
     ensureProxyRunning,
     syncToOpenCode,
+    cleanupOpenCodeProxyConfig,
     restoreOpenCodeBackup,
     checkForUpdateDetailed,
     runUpdate,
@@ -585,7 +633,10 @@ async function main() {
     startOpenCodeDesktop,
     startOpenCode,
     startProxyAndLaunch,
+    startExternalTool,
     buildProxyTopologyFromConfig,
+    isProxyEnabledForConfig,
+    getToolModeOrder,
     startRecommendAnalysis: overlays.startRecommendAnalysis,
     stopRecommendAnalysis: overlays.stopRecommendAnalysis,
     sendFeatureRequest,
@@ -652,7 +703,7 @@ 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)
+                : 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)
     process.stdout.write(ALT_HOME + content)
   }, Math.round(1000 / FPS))
 
@@ -660,7 +711,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))
+  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))
 
   // 📖 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.1.87",
+  "version": "0.2.0",
   "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/config.js

@@ -71,7 +71,7 @@
  *   - apiKeys: API keys per provider (can differ between work/personal setups)
  *   - providers: enabled/disabled state per provider
  *   - favorites: list of pinned favorite models
- *   - settings: extra TUI preferences (tierFilter, sortColumn, sortAsc, pingInterval, hideUnconfiguredModels)
+ *   - settings: extra TUI preferences (tierFilter, sortColumn, sortAsc, pingInterval, hideUnconfiguredModels, proxy)
  *
  * 📖 When a profile is loaded via --profile <name> or Shift+P, the main config's
  *    apiKeys/providers/favorites are replaced with the profile's values. The profile
@@ -96,11 +96,12 @@
  *   → getActiveProfileName(config) — Get the currently active profile name (or null)
  *   → setActiveProfile(config, name) — Set which profile is active (null to clear)
  *   → _emptyProfileSettings() — Default TUI settings for a profile
+ *   → getProxySettings(config) — Return normalized proxy settings from config
  *
  * @exports loadConfig, saveConfig, getApiKey, isProviderEnabled
  * @exports addApiKey, removeApiKey, listApiKeys — multi-key management helpers
  * @exports saveAsProfile, loadProfile, listProfiles, deleteProfile
- * @exports getActiveProfileName, setActiveProfile
+ * @exports getActiveProfileName, setActiveProfile, getProxySettings
  * @exports CONFIG_PATH — path to the JSON config file
  *
  * @see bin/free-coding-models.js — main CLI that uses these functions
@@ -166,6 +167,7 @@ export function loadConfig() {
       if (!parsed.providers) parsed.providers = {}
       if (!parsed.settings || typeof parsed.settings !== 'object') parsed.settings = {}
       if (typeof parsed.settings.hideUnconfiguredModels !== 'boolean') parsed.settings.hideUnconfiguredModels = true
+      parsed.settings.proxy = normalizeProxySettings(parsed.settings.proxy)
       // 📖 Favorites: list of "providerKey/modelId" pinned rows.
       if (!Array.isArray(parsed.favorites)) parsed.favorites = []
       parsed.favorites = parsed.favorites.filter((fav) => typeof fav === 'string' && fav.trim().length > 0)
@@ -177,7 +179,9 @@ export function loadConfig() {
       if (!parsed.profiles || typeof parsed.profiles !== 'object') parsed.profiles = {}
       for (const profile of Object.values(parsed.profiles)) {
         if (!profile || typeof profile !== 'object') continue
-        profile.settings = profile.settings ? { ..._emptyProfileSettings(), ...profile.settings } : _emptyProfileSettings()
+        profile.settings = profile.settings
+          ? { ..._emptyProfileSettings(), ...profile.settings, proxy: normalizeProxySettings(profile.settings.proxy) }
+          : _emptyProfileSettings()
       }
       if (parsed.activeProfile && typeof parsed.activeProfile !== 'string') parsed.activeProfile = null
       return parsed
@@ -400,9 +404,40 @@ export function _emptyProfileSettings() {
     sortAsc: true,        // 📖 true = ascending (fastest first for latency)
     pingInterval: 10000,  // 📖 default ms between pings in the steady "normal" mode
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
+    proxy: normalizeProxySettings(),
   }
 }
 
+/**
+ * 📖 normalizeProxySettings: keep proxy-related preferences stable across old configs,
+ * 📖 new installs, and profile switches. Proxy is opt-in by default.
+ *
+ * @param {object|undefined|null} proxy
+ * @returns {{ enabled: boolean, syncToOpenCode: boolean, preferredPort: number }}
+ */
+export function normalizeProxySettings(proxy = null) {
+  const preferredPort = Number.isInteger(proxy?.preferredPort) && proxy.preferredPort >= 0 && proxy.preferredPort <= 65535
+    ? proxy.preferredPort
+    : 0
+
+  return {
+    enabled: proxy?.enabled === true,
+    syncToOpenCode: proxy?.syncToOpenCode === true,
+    preferredPort,
+  }
+}
+
+/**
+ * 📖 getProxySettings: return normalized proxy settings from the live config.
+ * 📖 This centralizes the opt-in default so launchers do not guess.
+ *
+ * @param {object} config
+ * @returns {{ enabled: boolean, syncToOpenCode: boolean, preferredPort: number }}
+ */
+export function getProxySettings(config) {
+  return normalizeProxySettings(config?.settings?.proxy)
+}
+
 /**
  * 📖 saveAsProfile: Snapshot the current config state into a named profile.
  *
@@ -447,14 +482,16 @@ export function saveAsProfile(config, name, settings = null) {
 export function loadProfile(config, name) {
   const profile = config?.profiles?.[name]
   if (!profile) return null
+  const nextSettings = profile.settings ? { ..._emptyProfileSettings(), ...profile.settings, proxy: normalizeProxySettings(profile.settings.proxy) } : _emptyProfileSettings()
 
   // 📖 Deep-copy the profile data into the live config (don't share references)
   config.apiKeys = JSON.parse(JSON.stringify(profile.apiKeys || {}))
   config.providers = JSON.parse(JSON.stringify(profile.providers || {}))
   config.favorites = [...(profile.favorites || [])]
+  config.settings = nextSettings
   config.activeProfile = name
 
-  return profile.settings ? { ..._emptyProfileSettings(), ...profile.settings } : _emptyProfileSettings()
+  return nextSettings
 }
 
 /**
@@ -515,6 +552,7 @@ function _emptyConfig() {
     // 📖 Global TUI preferences that should persist even without a named profile.
     settings: {
       hideUnconfiguredModels: true,
+      proxy: normalizeProxySettings(),
     },
     // 📖 Pinned favorites rendered at top of the table ("providerKey/modelId").
     favorites: [],