free-coding-models 0.3.16 → 0.3.18

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ---
 
+## 0.3.18
+
+### Added
+- **Missing tool bootstrap flow**: FCM now detects when a target CLI is absent, offers a minimal in-TUI install confirmation, runs the official global install command, then resumes the selected model launch automatically.
+
+### Changed
+- **TUI readability overhaul across every screen**: the main table, Settings, Help, Smart Recommend, Feedback, and Changelog overlays now share a semantic high-contrast theme system instead of a patchwork of hardcoded colors.
+- **Global theme switching now works for real**: press `G` to cycle `auto → dark → light` live, and the Settings screen now exposes a visible `Global Theme` row for the same control.
+- **Launcher binary resolution**: direct tool launches now search PATH plus common user bin directories so a freshly installed CLI can be reused immediately in the same FCM session.
+
+### Fixed
+- **Theme repaint bugs**: provider colors, tier colors, separators, badges, cursor highlights, and overlay backgrounds now update immediately when the theme changes instead of keeping stale import-time colors.
+
+## 0.3.17
+
+### Added
+- **Auto Light/Dark Theme**: Implemented automatic detection of the user's terminal theme (dark or light) so that the TUI is always readable. Added semantic color tokens, and users can override the theme as `dark`, `light`, or `auto` via the Settings interface.
+
+## 0.3.16
+
+### Added
+- **iFlow free coding models**: Added the iFlow provider to the README and TUI, supporting `deepseek-v3`, `mini-max-m2.5`, etc.
+
 ## 0.3.15
 
 ### Added

package/README.md

@@ -1,184 +1,259 @@
-# free-coding-models
+<p align="center">
+  <img src="https://img.shields.io/npm/v/free-coding-models?color=76b900&label=npm&logo=npm" alt="npm version">
+  <img src="https://img.shields.io/node/v/free-coding-models?color=76b900&logo=node.js" alt="node version">
+  <img src="https://img.shields.io/npm/l/free-coding-models?color=76b900" alt="license">
+  <img src="https://img.shields.io/badge/models-160-76b900?logo=nvidia" alt="models count">
+  <img src="https://img.shields.io/badge/providers-20-blue" alt="providers count">
+</p>
 
-`free-coding-models` is a terminal UI to compare free coding models across providers, monitor live health/latency, and launch supported coding tools with the selected model.
+<h1 align="center">free-coding-models</h1>
 
-It is built around direct provider integrations. The old global proxy bridge has been removed from the product and is being rewritten from scratch, so only the stable direct-launch workflow is exposed for now.
+<p align="center">
+  <strong>Find the fastest free coding model in seconds</strong><br>
+  <sub>Ping 160 models across 20 AI Free providers in real-time </sub><br><sub> Install Free API endpoints to your favorite AI coding tool: <br>OpenCode, OpenClaw, Crush, Goose, Aider, Qwen Code, OpenHands, Amp or Pi in one keystroke</sub>
+</p>
 
-## Install
 
-```bash
-pnpm install
-pnpm start
-```
 
-To install globally:
+<p align="center">
 
 ```bash
 npm install -g free-coding-models
 free-coding-models
 ```
 
-## What It Does
+</p>
+
+<p align="center">
+  <a href="#-why-this-tool">Why</a> •
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-providers">Providers</a> •
+  <a href="#-usage">Usage</a> •
+  <a href="#-tui-keys">TUI Keys</a> •
+  <a href="#-contributing">Contributing</a>
+</p>
+
+<p align="center">
+  <img src="demo.gif" alt="free-coding-models demo" width="100%">
+</p>
+
+<p align="center">
+  <sub>Made with ❤️ and ☕ by <a href="https://vanessadepraute.dev">Vanessa Depraute</a> (aka <a href="https://vavanessa.dev">Vava-Nessa</a>)</sub>
+</p>
+
+---
+
+## 💡 Why this tool?
 
-- Lists free coding models from the providers defined in [`sources.js`](./sources.js)
-- Pings models continuously and shows latency, uptime, stability, verdict, and usage snapshots
-- Lets you filter, sort, favorite, and compare models inside a full-screen TUI
-- Launches supported coding tools with the currently selected model, after writing that exact selection as the tool default
-- Installs provider catalogs into compatible external tool configs through the `Y` flow
+There are **160+ free coding models** scattered across 20 providers. Which one is fastest right now? Which one is actually stable versus just lucky on the last ping?
 
-## Stable Product Surface
+This CLI pings them all in parallel, shows live latency, and calculates a **live Stability Score (0-100)**. Average latency alone is misleading if a model randomly spikes to 6 seconds; the stability score measures true reliability by combining **p95 latency** (30%), **jitter/variance** (30%), **spike rate** (20%), and **uptime** (20%). 
 
-The public launcher set is currently:
+It then writes the model you pick directly into your coding tool's config — so you go from "which model?" to "coding" in under 10 seconds.
 
-- `OpenCode CLI`
-- `OpenCode Desktop`
-- `OpenClaw`
-- `Crush`
-- `Goose`
-- `Pi`
-- `Aider`
-- `Qwen Code`
-- `OpenHands`
-- `Amp`
+---
 
-Temporarily removed from the public app while the bridge is being rebuilt:
+## ⚡ Quick Start
 
-- `Claude Code`
-- `Codex`
-- `Gemini`
-- the old FCM global proxy / daemon / log overlay flow
+**① Get a free API key** — you only need one to get started:
 
-## Quick Start
+**160 coding models** across 20 providers, ranked by [SWE-bench Verified](https://www.swebench.com).
+
+| Provider | Models | Tier range | Free tier | Env var |
+|----------|--------|-----------|-----------|--------|
+| [NVIDIA NIM](https://build.nvidia.com) | 44 | S+ → C | 40 req/min (no credit card needed) | `NVIDIA_API_KEY` |
+| [iFlow](https://platform.iflow.cn) | 11 | S+ → A+ | Free for individuals (no req limits, 7-day key expiry) | `IFLOW_API_KEY` |
+| [ZAI](https://z.ai) | 7 | S+ → S | Free tier (generous quota) | `ZAI_API_KEY` |
+| [Alibaba DashScope](https://modelstudio.console.alibabacloud.com) | 8 | S+ → A | 1M free tokens per model (Singapore region, 90 days) | `DASHSCOPE_API_KEY` |
+| [Groq](https://console.groq.com/keys) | 10 | S → B | 30‑50 RPM per model (varies by model) | `GROQ_API_KEY` |
+| [Cerebras](https://cloud.cerebras.ai) | 7 | S+ → B | Generous free tier (developer tier 10× higher limits) | `CEREBRAS_API_KEY` |
+| [SambaNova](https://sambanova.ai/developers) | 12 | S+ → B | Dev tier generous quota | `SAMBANOVA_API_KEY` |
+| [OpenRouter](https://openrouter.ai/keys) | 11 | S+ → C | Free on :free: 50/day <$10, 1000/day ≥$10 (20 req/min) | `OPENROUTER_API_KEY` |
+| [Hugging Face](https://huggingface.co/settings/tokens) | 2 | S → B | Free monthly credits (~$0.10) | `HUGGINGFACE_API_KEY` |
+| [Together AI](https://api.together.ai/settings/api-keys) | 7 | S+ → A- | Credits/promos vary by account (check console) | `TOGETHER_API_KEY` |
+| [DeepInfra](https://deepinfra.com/login) | 2 | A- → B+ | 200 concurrent requests (default) | `DEEPINFRA_API_KEY` |
+| [Fireworks AI](https://fireworks.ai) | 2 | S | $1 credits – 10 req/min without payment | `FIREWORKS_API_KEY` |
+| [Mistral Codestral](https://codestral.mistral.ai) | 1 | B+ | 30 req/min, 2000/day | `CODESTRAL_API_KEY` |
+| [Hyperbolic](https://app.hyperbolic.ai/settings) | 10 | S+ → A- | $1 free trial credits | `HYPERBOLIC_API_KEY` |
+| [Scaleway](https://console.scaleway.com/iam/api-keys) | 7 | S+ → B+ | 1M free tokens | `SCALEWAY_API_KEY` |
+| [Google AI Studio](https://aistudio.google.com/apikey) | 3 | B → C | 14.4K req/day, 30/min | `GOOGLE_API_KEY` |
+| [SiliconFlow](https://cloud.siliconflow.cn/account/ak) | 6 | S+ → A | Free models: usually 100 RPM, varies by model | `SILICONFLOW_API_KEY` |
+| [Cloudflare Workers AI](https://dash.cloudflare.com) | 6 | S → B | Free: 10k neurons/day, text-gen 300 RPM | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` |
+| [Perplexity API](https://www.perplexity.ai/settings/api) | 4 | A+ → B | Tiered limits by spend (default ~50 RPM) | `PERPLEXITY_API_KEY` |
+| [Replicate](https://replicate.com/account/api-tokens) | 1 | A- | 6 req/min (no payment) – up to 3,000 RPM with payment | `REPLICATE_API_TOKEN` |
+
+> 💡 One key is enough. Add more at any time with **`P`** inside the TUI.
+
+### Tier scale
+
+| Tier | SWE-bench | Best for |
+|------|-----------|----------|
+| **S+** | ≥ 70% | Complex refactors, real-world GitHub issues |
+| **S** | 60–70% | Most coding tasks, strong general use |
+| **A+/A** | 40–60% | Solid alternatives, targeted programming |
+| **A-/B+** | 30–40% | Smaller tasks, constrained infra |
+| **B/C** | < 30% | Code completion, edge/minimal setups |
+
+**② Install and run:**
 
 ```bash
+npm install -g free-coding-models
 free-coding-models
 ```
 
-Useful startup flags:
+On first run, you'll be prompted to enter your API key(s). You can skip providers and add more later with **`P`**.
+
+Need to fix contrast because your terminal theme is fighting the TUI? Press **`G`** at any time to cycle **Auto → Dark → Light**. The switch recolors the full interface live: table, Settings, Help, Smart Recommend, Feedback, and Changelog.
+
+**③ Pick a model and launch your tool:**
 
-```bash
-free-coding-models --opencode
-free-coding-models --openclaw --tier S
-free-coding-models --crush
-free-coding-models --json
-free-coding-models --recommend
-free-coding-models --help
+```
+↑↓ navigate   →   Enter to launch
 ```
 
-Default tool mode with no launcher flag: `OpenCode CLI`
+The model you select is automatically written into your tool's config (OpenCode, OpenClaw, Crush, etc.) and the tool opens immediately. Done.
 
-## Main TUI Keys
+If the active CLI tool is missing, FCM now catches it before launch, offers a tiny Yes/No install prompt, installs the tool with its official global command, then resumes the same model launch automatically.
 
-- `↑↓` navigate rows
-- `Enter` launch/select the current model in the active tool mode
-- `Z` cycle tool mode
-- `T` cycle tier filter
-- `D` cycle provider filter
-- `R/O/M/L/A/S/C/H/V/B/U/G` sort columns
-- `E` toggle configured models only
-- `F` favorite/unfavorite the selected model
-- `W` cycle ping cadence
-- `P` open Settings
-- `Y` open Install Endpoints
-- `Q` open Smart Recommend
-- `I` open feedback / bug report form
-- `N` open changelog
-- `K` open help
-- `Ctrl+C` exit
+> 💡 You can also run `free-coding-models --goose --tier S` to pre-filter to S-tier models for Goose before the TUI even opens.
 
-## Settings
 
-Press `P` to:
 
-- add or remove provider API keys
-- enable or disable providers
-- test provider keys
-- check for updates
-- toggle the terminal width warning
-- clean discontinued proxy-era config left behind by older builds
+## 🚀 Usage
 
-The main TUI also shows a footer notice explaining that the external-tools bridge/proxy is intentionally disabled while it is being rebuilt.
+### Common scenarios
 
-## Install Endpoints
+```bash
+# "I want the most reliable model right now"
+free-coding-models --fiable
 
-Press `Y` to install one configured provider into supported external tools.
+# "I want to configure Goose with an S-tier model"
+free-coding-models --goose --tier S
 
-Current install flow:
+# "I want NVIDIA's top models only"
+free-coding-models --origin nvidia --tier S
 
-1. Choose a configured provider
-2. Choose a supported tool
-3. Choose scope: all models or selected models
-4. Write the managed config/env files
+# "Show me only elite models that are currently healthy"
+free-coding-models --premium
 
-This flow is direct-provider only now. The old proxy-backed install path has been removed.
+# "I want to script this — give me JSON"
+free-coding-models --tier S --json | jq -r '.[0].modelId'
 
-## Tool Notes
+# "I want to configure OpenClaw with Groq's fastest model"
+free-coding-models --openclaw --origin groq
+```
 
-When you press `Enter`, FCM now persists the selected model into the target tool before launch so the tool opens on the model you actually picked.
+### Tool launcher flags
 
-### OpenCode
+| Flag | Launches |
+|------|----------|
+| `--opencode` | OpenCode CLI |
+| `--opencode-desktop` | OpenCode Desktop |
+| `--openclaw` | OpenClaw |
+| `--crush` | Crush |
+| `--goose` | Goose |
+| `--aider` | Aider |
+| `--qwen` | Qwen Code |
+| `--openhands` | OpenHands |
+| `--amp` | Amp |
+| `--pi` | Pi |
 
-- `OpenCode CLI` and `OpenCode Desktop` share `~/.config/opencode/opencode.json`
-- Selecting a model and pressing `Enter` updates the config and launches the target mode
+Press **`Z`** in the TUI to cycle between tools without restarting.
 
-### OpenClaw
+→ **[Full flags reference](./docs/flags.md)**
 
-- `free-coding-models` writes the selected provider/model into `~/.openclaw/openclaw.json` as the primary default
-- OpenClaw itself is not launched by FCM
+---
 
-### ZAI with OpenCode
+## ⌨️ TUI Keys
 
-ZAI still needs a small local compatibility bridge for OpenCode only, because ZAI uses `/api/coding/paas/v4/*` instead of standard `/v1/*` paths.
+| Key | Action |
+|-----|--------|
+| `↑↓` | Navigate models |
+| `Enter` | Launch selected model in active tool |
+| `Z` | Cycle target tool |
+| `T` | Cycle tier filter |
+| `D` | Cycle provider filter |
+| `E` | Toggle configured-only mode |
+| `F` | Favorite / unfavorite model |
+| `G` | Cycle global theme (`Auto → Dark → Light`) |
+| `R/S/C/M/O/L/A/H/V/B/U` | Sort columns |
+| `P` | Settings (API keys, providers, updates, theme) |
+| `Y` | Install Endpoints (push provider into tool config) |
+| `Q` | Smart Recommend overlay |
+| `N` | Changelog |
+| `W` | Cycle ping cadence |
+| `I` | Feedback / bug report |
+| `K` | Help overlay |
+| `Ctrl+C` | Exit |
 
-That bridge is internal to the OpenCode launcher path and is still supported:
+→ **[Stability score & column reference](./docs/stability.md)**
 
-- it starts only when launching a ZAI model in OpenCode
-- it binds to localhost on a random port
-- it shuts down automatically when OpenCode exits
+---
 
-This is separate from the removed global multi-tool proxy system.
+## ✨ Features
 
-## `/testfcm`
+- **Parallel pings** — all 160 models tested simultaneously via native `fetch`
+- **Adaptive monitoring** — 2s burst for 60s → 10s normal → 30s idle
+- **Stability score** — composite 0–100 (p95 latency, jitter, spike rate, uptime)
+- **Smart ranking** — top 3 highlighted 🥇🥈🥉
+- **Favorites** — pin models with `F`, persisted across sessions
+- **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
+- **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
+- **Readable everywhere** — semantic theme palette keeps table rows, overlays, badges, and help screens legible in dark and light terminals
+- **Global theme switch** — `G` cycles `auto`, `dark`, and `light` live without restarting
+- **Auto-retry** — timeout models keep getting retried
 
-There is a repo-local harness for exercising the real TUI and launcher flow.
+---
 
-Available scripts:
+## 📋 Contributing
 
-```bash
-pnpm test:fcm
-pnpm test:fcm:mock
-```
+We welcome contributions — issues, PRs, new provider integrations.
 
-`pnpm test:fcm:mock` uses the mock `crush` binary in `test/fixtures/mock-bin` so maintainers can validate the TUI → launcher plumbing without a real external CLI installed.
+**Q:** How accurate are the latency numbers?  
+**A:** Real round-trip times measured by your machine. Results depend on your network and provider load at that moment.
 
-## Development
+**Q:** Can I add a new provider?  
+**A:** Yes — see [`sources.js`](./sources.js) for the model catalog format.
 
-Run the unit tests:
+→ **[Development guide](./docs/development.md)** · **[Config reference](./docs/config.md)** · **[Tool integrations](./docs/integrations.md)**
 
-```bash
-pnpm test
-```
+---
 
-Run the app locally:
+## 📧 Support
 
-```bash
-pnpm start
-```
+[GitHub Issues](https://github.com/vava-nessa/free-coding-models/issues) · [Discord](https://discord.gg/ZTNFHvvCkU)
+
+---
+
+## 📄 License
 
-## Architecture Notes
+MIT © [vava](https://github.com/vava-nessa)
 
-- Main CLI entrypoint: [`bin/free-coding-models.js`](./bin/free-coding-models.js)
-- Pure helpers and sorting logic: [`src/utils.js`](./src/utils.js)
-- OpenCode launch/config helpers: [`src/opencode.js`](./src/opencode.js), [`src/opencode-config.js`](./src/opencode-config.js)
-- External tool launchers: [`src/tool-launchers.js`](./src/tool-launchers.js)
-- Endpoint installer flow: [`src/endpoint-installer.js`](./src/endpoint-installer.js)
+---
 
-## Current Status
+<p align="center">
+  <strong>Contributors</strong><br>
+  <a href="https://github.com/vava-nessa"><img src="https://avatars.githubusercontent.com/u/5466264?v=4&s=60" width="60" height="60" style="border-radius:50%" alt="vava-nessa"></a>
+  <a href="https://github.com/erwinh22"><img src="https://avatars.githubusercontent.com/u/6641858?v=4&s=60" width="60" height="60" style="border-radius:50%" alt="erwinh22"></a>
+  <a href="https://github.com/whit3rabbit"><img src="https://avatars.githubusercontent.com/u/12357518?v=4&s=60" width="60" height="60" style="border-radius:50%" alt="whit3rabbit"></a>
+  <a href="https://github.com/skylaweber"><img src="https://avatars.githubusercontent.com/u/172871734?v=4&s=60" width="60" height="60" style="border-radius:50%" alt="skylaweber"></a>
+  <a href="https://github.com/PhucTruong-ctrl"><img src="https://github.com/PhucTruong-ctrl.png?s=60" width="60" height="60" style="border-radius:50%" alt="PhucTruong-ctrl"></a>
+  <br>
+  <sub>
+    <a href="https://github.com/vava-nessa">vava-nessa</a> &middot;
+    <a href="https://github.com/erwinh22">erwinh22</a> &middot;
+    <a href="https://github.com/whit3rabbit">whit3rabbit</a> &middot;
+    <a href="https://github.com/skylaweber">skylaweber</a> &middot;
+    <a href="https://github.com/PhucTruong-ctrl">PhucTruong-ctrl</a>
+  </sub>
+</p>
 
-The app surface is intentionally narrowed right now to keep releases stable:
 
-- direct provider launches are the supported path
-- the old cross-tool proxy stack has been removed from the app
-- Claude Code, Codex, and Gemini stay hidden until the rewrite is production-ready
 
-When that rewrite lands, it should come back as a separate, cleaner system rather than more patches on the old one.
+<p align="center">
+  <sub>Anonymous usage data collected to improve the tool. No personal information ever.</sub>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "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

@@ -122,10 +122,12 @@ import { createOverlayRenderers } from '../src/overlays.js'
 import { createKeyHandler } from '../src/key-handler.js'
 import { getToolModeOrder, getToolMeta } from '../src/tool-metadata.js'
 import { startExternalTool } from '../src/tool-launchers.js'
+import { getToolInstallPlan, installToolWithPlan, isToolInstalled } from '../src/tool-bootstrap.js'
 import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../src/endpoint-installer.js'
 import { loadCache, saveCache, clearCache, getCacheAge } from '../src/cache.js'
 import { checkConfigSecurity } from '../src/security.js'
 import { buildCliHelpText } from '../src/cli-help.js'
+import { detectActiveTheme } from '../src/theme.js'
 
 // 📖 mergedModels: cross-provider grouped model list (one entry per label, N providers each)
 // 📖 mergedModelByLabel: fast lookup map from display label → merged model entry
@@ -174,7 +176,8 @@ const LOCAL_VERSION = pkg.version
 
 export async function runApp(cliArgs, config) {
 
-
+  // 📖 Detect user active terminal theme
+  detectActiveTheme(config.settings?.theme || 'auto')
 
   // 📖 Check config file security — warn and offer auto-fix if permissions are too open
   const securityCheck = checkConfigSecurity()
@@ -418,6 +421,14 @@ export async function runApp(cliArgs, config) {
     installEndpointsSelectedModelIds: new Set(), // 📖 Multi-select buffer for the selected-models phase
     installEndpointsErrorMsg: null, // 📖 Temporary validation/error message inside the install flow
     installEndpointsResult: null, // 📖 Final install result shown in the result phase
+    // 📖 Missing-tool bootstrap overlay — confirms a one-click install before retrying the launch.
+    toolInstallPromptOpen: false,
+    toolInstallPromptCursor: 0,
+    toolInstallPromptScrollOffset: 0,
+    toolInstallPromptMode: null,
+    toolInstallPromptModel: null,
+    toolInstallPromptPlan: null,
+    toolInstallPromptErrorMsg: null,
     // 📖 Smart Recommend overlay state (Q key opens it)
     recommendOpen: false,         // 📖 Whether the recommend overlay is active
     recommendPhase: 'questionnaire', // 📖 'questionnaire'|'analyzing'|'results' — current phase
@@ -748,6 +759,8 @@ export async function runApp(cliArgs, config) {
     getInstallTargetModes,
     getProviderCatalogModels,
     getToolMeta,
+    getToolInstallPlan,
+    padEndDisplay,
   })
 
   onKeyPress = createKeyHandler({
@@ -783,6 +796,9 @@ export async function runApp(cliArgs, config) {
     startOpenCode,
     startExternalTool,
     getToolModeOrder,
+    getToolInstallPlan,
+    isToolInstalled,
+    installToolWithPlan,
     startRecommendAnalysis: overlays.startRecommendAnalysis,
     stopRecommendAnalysis: overlays.stopRecommendAnalysis,
     sendBugReport,
@@ -842,7 +858,7 @@ 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.recommendOpen && !state.feedbackOpen && !state.changelogOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.toolInstallPromptOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
@@ -850,6 +866,8 @@ export async function runApp(cliArgs, config) {
       ? overlays.renderSettings()
       : state.installEndpointsOpen
         ? overlays.renderInstallEndpoints()
+      : state.toolInstallPromptOpen
+        ? overlays.renderToolInstallPrompt()
       : state.recommendOpen
         ? overlays.renderRecommend()
         : state.feedbackOpen

package/src/config.js

@@ -210,6 +210,7 @@ function normalizeSettingsSection(settings) {
     ...safeSettings,
     hideUnconfiguredModels: typeof safeSettings.hideUnconfiguredModels === 'boolean' ? safeSettings.hideUnconfiguredModels : true,
     disableWidthsWarning: safeSettings.disableWidthsWarning === true,
+    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
 
@@ -230,6 +231,7 @@ function normalizeProfileSettings(settings) {
     ..._emptyProfileSettings(),
     ...safeSettings,
     disableWidthsWarning: safeSettings.disableWidthsWarning === true,
+    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
 
@@ -842,6 +844,7 @@ export function _emptyProfileSettings() {
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
     preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
     disableWidthsWarning: false, // 📖 Disable widths warning (default off)
+    theme: 'auto',        // 📖 'auto' follows the terminal/OS theme, override with 'dark' or 'light' if needed
   }
 }