free-coding-models 0.3.16 → 0.3.17

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ---
 
+## 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,251 @@
-# 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`**.
 
-```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
+**③ Pick a model and launch your tool:**
+
+```
+↑↓ 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
+> 💡 You can also run `free-coding-models --goose --tier S` to pre-filter to S-tier models for Goose before the TUI even opens.
 
-- `↑↓` 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
 
-## Settings
 
-Press `P` to:
+## 🚀 Usage
 
-- 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
+### Common scenarios
 
-The main TUI also shows a footer notice explaining that the external-tools bridge/proxy is intentionally disabled while it is being rebuilt.
+```bash
+# "I want the most reliable model right now"
+free-coding-models --fiable
 
-## Install Endpoints
+# "I want to configure Goose with an S-tier model"
+free-coding-models --goose --tier S
 
-Press `Y` to install one configured provider into supported external tools.
+# "I want NVIDIA's top models only"
+free-coding-models --origin nvidia --tier S
 
-Current install flow:
+# "Show me only elite models that are currently healthy"
+free-coding-models --premium
 
-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
+# "I want to script this — give me JSON"
+free-coding-models --tier S --json | jq -r '.[0].modelId'
 
-This flow is direct-provider only now. The old proxy-backed install path has been removed.
+# "I want to configure OpenClaw with Groq's fastest model"
+free-coding-models --openclaw --origin groq
+```
 
-## Tool Notes
+### Tool launcher flags
 
-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.
+| 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
+Press **`Z`** in the TUI to cycle between tools without restarting.
 
-- `OpenCode CLI` and `OpenCode Desktop` share `~/.config/opencode/opencode.json`
-- Selecting a model and pressing `Enter` updates the config and launches the target mode
+→ **[Full flags reference](./docs/flags.md)**
 
-### OpenClaw
+---
 
-- `free-coding-models` writes the selected provider/model into `~/.openclaw/openclaw.json` as the primary default
-- OpenClaw itself is not launched by FCM
+## ⌨️ TUI Keys
 
-### ZAI with OpenCode
+| 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 |
+| `R/S/C/M/O/L/A/H/V/B/U` | Sort columns |
+| `P` | Settings (API keys, providers, updates) |
+| `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 |
 
-ZAI still needs a small local compatibility bridge for OpenCode only, because ZAI uses `/api/coding/paas/v4/*` instead of standard `/v1/*` paths.
+→ **[Stability score & column reference](./docs/stability.md)**
 
-That bridge is internal to the OpenCode launcher path and is still supported:
+---
 
-- 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
+## ✨ Features
 
-This is separate from the removed global multi-tool proxy system.
+- **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`)
+- **Width guardrail** — shows a warning instead of a broken table in narrow terminals
+- **Auto-retry** — timeout models keep getting retried
 
-## `/testfcm`
+---
 
-There is a repo-local harness for exercising the real TUI and launcher flow.
+## 📋 Contributing
 
-Available scripts:
+We welcome contributions — issues, PRs, new provider integrations.
 
-```bash
-pnpm test:fcm
-pnpm test:fcm:mock
-```
+**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.
 
-`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:** Can I add a new provider?  
+**A:** Yes — see [`sources.js`](./sources.js) for the model catalog format.
 
-## Development
+→ **[Development guide](./docs/development.md)** · **[Config reference](./docs/config.md)** · **[Tool integrations](./docs/integrations.md)**
 
-Run the unit tests:
+---
 
-```bash
-pnpm test
-```
+## 📧 Support
 
-Run the app locally:
+[GitHub Issues](https://github.com/vava-nessa/free-coding-models/issues) · [Discord](https://discord.gg/ZTNFHvvCkU)
 
-```bash
-pnpm start
-```
+---
+
+## 📄 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.17",
   "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

@@ -126,6 +126,7 @@ import { getConfiguredInstallableProviders, installProviderEndpoints, refreshIns
 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 +175,8 @@ const LOCAL_VERSION = pkg.version
 
 export async function runApp(cliArgs, config) {
 
-
+  // 📖 Detect user active terminal theme
+  detectActiveTheme(config.settings?.theme || 'dark')
 
   // 📖 Check config file security — warn and offer auto-fix if permissions are too open
   const securityCheck = checkConfigSecurity()

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 : 'dark',
   }
 }
 
@@ -230,6 +231,7 @@ function normalizeProfileSettings(settings) {
     ..._emptyProfileSettings(),
     ...safeSettings,
     disableWidthsWarning: safeSettings.disableWidthsWarning === true,
+    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'dark',
   }
 }
 
@@ -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: 'dark',        // 📖 'dark', 'light', or 'auto'
   }
 }
 

package/src/key-handler.js

@@ -200,6 +200,7 @@ export function createKeyHandler(ctx) {
     noteUserActivity,
     intervalToPingMode,
     PING_MODE_CYCLE,
+    themeRowIdx,
     setResults,
     readline,
   } = ctx
@@ -926,7 +927,8 @@ export function createKeyHandler(ctx) {
       const providerKeys = Object.keys(sources)
       const updateRowIdx = providerKeys.length
       const widthWarningRowIdx = updateRowIdx + 1
-      const cleanupLegacyProxyRowIdx = widthWarningRowIdx + 1
+      const themeRowIdx = widthWarningRowIdx + 1
+      const cleanupLegacyProxyRowIdx = themeRowIdx + 1
       const changelogViewRowIdx = cleanupLegacyProxyRowIdx + 1
         // 📖 Profile system removed - API keys now persist permanently across all sessions
       const maxRowIdx = changelogViewRowIdx
@@ -1108,6 +1110,19 @@ export function createKeyHandler(ctx) {
           || state.settingsCursor === cleanupLegacyProxyRowIdx
           || state.settingsCursor === changelogViewRowIdx
         ) return
+        // 📖 Theme configuration cycle inside settings
+        if (state.settingsCursor === themeRowIdx) {
+          const themes = ['dark', 'light', 'auto']
+          const currentTheme = state.config.settings?.theme || 'dark'
+          const nextIndex = (themes.indexOf(currentTheme) + 1) % themes.length
+          state.config.settings.theme = themes[nextIndex]
+          saveConfig(state.config)
+          try {
+            const { detectActiveTheme } = await import('../src/theme.js')
+            detectActiveTheme(state.config.settings.theme)
+          } catch {}
+          return
+        }
         // 📖 Widths Warning toggle (disable/enable)
         if (state.settingsCursor === widthWarningRowIdx) {
           toggleWidthsWarningSetting()

package/src/overlays.js

@@ -22,6 +22,7 @@
 
 import { loadChangelog } from './changelog-loader.js'
 import { buildCliHelpLines } from './cli-help.js'
+import { themeColors } from './theme.js'
 
 export function createOverlayRenderers(state, deps) {
   const {
@@ -34,9 +35,6 @@ export function createOverlayRenderers(state, deps) {
     resolveApiKeys,
     isProviderEnabled,
     TIER_CYCLE,
-    SETTINGS_OVERLAY_BG,
-    HELP_OVERLAY_BG,
-    RECOMMEND_OVERLAY_BG,
     OVERLAY_PANEL_WIDTH,
     keepOverlayTargetVisible,
     sliceOverlayLines,
@@ -163,7 +161,7 @@ export function createOverlayRenderers(state, deps) {
 
       const row = `${bullet}[ ${enabledBadge} ] ${providerName}  ${keyDisplay.padEnd(30)}  ${testBadge}  ${rateSummary}`
       cursorLineByRow[i] = lines.length
-      lines.push(isCursor ? chalk.bgRgb(30, 30, 60)(row) : row)
+      lines.push(isCursor ? themeColors.bgCursor(row) : row)
     }
 
     lines.push('')
@@ -216,7 +214,7 @@ export function createOverlayRenderers(state, deps) {
     if (updateState === 'installing') updateStatus = chalk.cyan('Installing update…')
     const updateRow = `${updateBullet}${chalk.bold(updateActionLabel).padEnd(44)} ${updateStatus}`
     cursorLineByRow[updateRowIdx] = lines.length
-    lines.push(updateCursor ? chalk.bgRgb(30, 30, 60)(updateRow) : updateRow)
+    lines.push(updateCursor ? themeColors.bgCursor(updateRow) : updateRow)
     // 📖 Width warning visibility row for the startup narrow-terminal overlay.
     const disableWidthsWarning = Boolean(state.config.settings?.disableWidthsWarning)
     const widthWarningBullet = state.settingsCursor === widthWarningRowIdx ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
@@ -225,7 +223,7 @@ export function createOverlayRenderers(state, deps) {
       : chalk.greenBright('👁 Enabled')
     const widthWarningRow = `${widthWarningBullet}${chalk.bold('Small Width Warnings').padEnd(44)} ${widthWarningStatus}`
     cursorLineByRow[widthWarningRowIdx] = lines.length
-    lines.push(state.settingsCursor === widthWarningRowIdx ? chalk.bgRgb(30, 30, 60)(widthWarningRow) : widthWarningRow)
+    lines.push(state.settingsCursor === widthWarningRowIdx ? themeColors.bgCursor(widthWarningRow) : widthWarningRow)
     if (updateState === 'error' && state.settingsUpdateError) {
       lines.push(chalk.red(`      ${state.settingsUpdateError}`))
     }
@@ -234,13 +232,13 @@ export function createOverlayRenderers(state, deps) {
     const cleanupLegacyProxyBullet = state.settingsCursor === cleanupLegacyProxyRowIdx ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
     const cleanupLegacyProxyRow = `${cleanupLegacyProxyBullet}${chalk.bold('Clean Legacy Proxy Config').padEnd(44)} ${chalk.magentaBright('Enter remove discontinued bridge leftovers')}`
     cursorLineByRow[cleanupLegacyProxyRowIdx] = lines.length
-    lines.push(state.settingsCursor === cleanupLegacyProxyRowIdx ? chalk.bgRgb(55, 25, 55)(cleanupLegacyProxyRow) : cleanupLegacyProxyRow)
+    lines.push(state.settingsCursor === cleanupLegacyProxyRowIdx ? themeColors.bgCursorLegacy(cleanupLegacyProxyRow) : cleanupLegacyProxyRow)
 
     // 📖 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)
+    lines.push(state.settingsCursor === changelogViewRowIdx ? themeColors.bgCursorSettingsList(changelogViewRow) : changelogViewRow)
 
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
@@ -280,7 +278,7 @@ export function createOverlayRenderers(state, deps) {
     const { visible, offset } = sliceOverlayLines(lines, state.settingsScrollOffset, state.terminalRows)
     state.settingsScrollOffset = offset
 
-    const tintedLines = tintOverlayLines(visible, SETTINGS_OVERLAY_BG, state.terminalCols)
+    const tintedLines = tintOverlayLines(visible, themeColors.overlayBgSettings, state.terminalCols)
     const cleared = tintedLines.map(l => l + EL)
     return cleared.join('\n')
   }
@@ -347,7 +345,7 @@ export function createOverlayRenderers(state, deps) {
           const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
           const row = `${bullet}${chalk.bold(provider.label.padEnd(24))} ${chalk.dim(`${provider.modelCount} models`)}`
           cursorLineByRow[idx] = lines.length
-          lines.push(isCursor ? chalk.bgRgb(24, 44, 62)(row) : row)
+          lines.push(isCursor ? themeColors.bgCursorInstall(row) : row)
         })
       }
 
@@ -371,7 +369,7 @@ export function createOverlayRenderers(state, deps) {
         const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
         const row = `${bullet}${chalk.bold(label.padEnd(26))} ${note}`
         cursorLineByRow[idx] = lines.length
-        lines.push(isCursor ? chalk.bgRgb(24, 44, 62)(row) : row)
+        lines.push(isCursor ? themeColors.bgCursorInstall(row) : row)
       })
 
       lines.push('')
@@ -386,7 +384,7 @@ export function createOverlayRenderers(state, deps) {
         const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
         const row = `${bullet}${chalk.bold(scope.label)}`
         cursorLineByRow[idx] = lines.length
-        lines.push(isCursor ? chalk.bgRgb(24, 44, 62)(row) : row)
+        lines.push(isCursor ? themeColors.bgCursorInstall(row) : row)
         lines.push(chalk.dim(`      ${scope.hint}`))
         lines.push('')
       })
@@ -409,7 +407,7 @@ export function createOverlayRenderers(state, deps) {
         const tier = chalk.cyan(model.tier.padEnd(2))
         const row = `${bullet}${checkbox} ${chalk.bold(model.label.padEnd(26))} ${tier} ${chalk.dim(model.ctx.padEnd(6))} ${chalk.dim(model.modelId)}`
         cursorLineByRow[idx] = lines.length
-        lines.push(isCursor ? chalk.bgRgb(24, 44, 62)(row) : row)
+        lines.push(isCursor ? themeColors.bgCursorInstall(row) : row)
       })
 
       lines.push('')
@@ -443,7 +441,7 @@ export function createOverlayRenderers(state, deps) {
     const { visible, offset } = sliceOverlayLines(lines, state.installEndpointsScrollOffset, state.terminalRows)
     state.installEndpointsScrollOffset = offset
 
-    const tintedLines = tintOverlayLines(visible, SETTINGS_OVERLAY_BG, state.terminalCols)
+    const tintedLines = tintOverlayLines(visible, themeColors.overlayBgSettings, state.terminalCols)
     const cleared = tintedLines.map((line) => line + EL)
     return cleared.join('\n')
   }
@@ -539,7 +537,7 @@ export function createOverlayRenderers(state, deps) {
     // 📖 Help overlay can be longer than viewport, so keep a dedicated scroll offset.
     const { visible, offset } = sliceOverlayLines(lines, state.helpScrollOffset, state.terminalRows)
     state.helpScrollOffset = offset
-    const tintedLines = tintOverlayLines(visible, HELP_OVERLAY_BG, state.terminalCols)
+    const tintedLines = tintOverlayLines(visible, themeColors.overlayBgHelp, state.terminalCols)
     const cleared = tintedLines.map(l => l + EL)
     return cleared.join('\n')
   }
@@ -605,7 +603,7 @@ export function createOverlayRenderers(state, deps) {
         const opt = q.options[i]
         const isCursor = i === state.recommendCursor
         const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
-        const label = isCursor ? chalk.bold.white(opt.label) : chalk.white(opt.label)
+        const label = isCursor ? themeColors.textBold(opt.label) : themeColors.text(opt.label)
         lines.push(`${bullet}${label}`)
       }
 
@@ -666,9 +664,9 @@ export function createOverlayRenderers(state, deps) {
           const stabStr = stability === -1 ? '—' : String(stability)
 
           const isCursor = i === state.recommendCursor
-          const highlight = isCursor ? chalk.bgRgb(20, 50, 25) : (s => s)
+          const highlight = isCursor ? themeColors.bgCursor : (s => s)
 
-          lines.push(highlight(`  ${medal} ${chalk.bold('#' + (i + 1))}  ${chalk.bold.white(r.label)}  ${chalk.dim('(' + providerName + ')')}`))
+          lines.push(highlight(`  ${medal} ${chalk.bold('#' + (i + 1))}  ${themeColors.textBold(r.label)}  ${chalk.dim('(' + providerName + ')')}`))
           lines.push(highlight(`       Score: ${chalk.bold.greenBright(String(rec.score) + '/100')}  │  Tier: ${tierFn(r.tier)}  │  SWE: ${chalk.cyan(sweStr)}  │  Avg: ${chalk.yellow(avgStr)}  │  CTX: ${chalk.cyan(ctxStr)}  │  Stability: ${chalk.cyan(stabStr)}`))
           lines.push('')
         }
@@ -683,7 +681,7 @@ export function createOverlayRenderers(state, deps) {
     lines.push('')
     const { visible, offset } = sliceOverlayLines(lines, state.recommendScrollOffset, state.terminalRows)
     state.recommendScrollOffset = offset
-    const tintedLines = tintOverlayLines(visible, RECOMMEND_OVERLAY_BG, state.terminalCols)
+    const tintedLines = tintOverlayLines(visible, themeColors.overlayBgRecommend, state.terminalCols)
     const cleared2 = tintedLines.map(l => l + EL)
     return cleared2.join('\n')
   }

package/src/render-table.js

@@ -34,7 +34,16 @@
 import chalk from 'chalk'
 import { createRequire } from 'module'
 import { sources } from '../sources.js'
-import { PING_INTERVAL, FRAMES } from './constants.js'
+import {
+  TABLE_FIXED_LINES,
+  COL_MODEL,
+  TIER_CYCLE,
+  msCell,
+  spinCell,
+  PING_INTERVAL,
+  FRAMES
+} from './constants.js'
+import { themeColors } from './theme.js'
 import { TIER_COLOR } from './tier-colors.js'
 import { getAvg, getVerdict, getUptime, getStabilityScore, getVersionStatusInfo } from './utils.js'
 import { usagePlaceholderForProvider } from './ping.js'
@@ -556,12 +565,12 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     const row = '  ' + num + COL_SEP + tier + COL_SEP + sweCell + COL_SEP + ctxCell + COL_SEP + nameCell + COL_SEP + sourceCell + COL_SEP + pingCell + COL_SEP + avgCell + COL_SEP + status + COL_SEP + speedCell + COL_SEP + stabCell + COL_SEP + uptimeCell + COL_SEP + tokensCell
 
     if (isCursor) {
-      lines.push(chalk.bgRgb(155, 55, 135)(row))
+      lines.push(themeColors.bgModelCursor(row))
     } else if (r.isRecommended) {
       // 📖 Medium green background for recommended models (distinguishable from favorites)
-      lines.push(chalk.bgRgb(15, 40, 15)(row))
+      lines.push(themeColors.bgModelRecommended(row))
     } else if (r.isFavorite) {
-      lines.push(chalk.bgRgb(88, 64, 10)(row))
+      lines.push(themeColors.bgModelFavorite(row))
     } else {
       lines.push(row)
     }

package/src/theme.js

@@ -0,0 +1,67 @@
+/**
+ * @file theme.js
+ * @description Dynamic light/dark theme detector and semantic colour mappings.
+ */
+
+import chalk from 'chalk'
+import { execSync } from 'child_process'
+
+let activeTheme = 'dark'
+
+export function detectActiveTheme(configTheme) {
+  if (configTheme === 'dark' || configTheme === 'light') {
+    activeTheme = configTheme;
+    return activeTheme;
+  }
+  
+  // Auto detect
+  const fgbg = process.env.COLORFGBG || '';
+  if (fgbg.includes(';15') || fgbg.includes(';base03')) {
+    activeTheme = 'light';
+    return activeTheme;
+  } else if (fgbg) {
+    activeTheme = 'dark';
+    return activeTheme;
+  }
+  
+  if (process.platform === 'darwin') {
+    try {
+      const style = execSync('defaults read -g AppleInterfaceStyle 2>/dev/null', { timeout: 100 }).toString().trim();
+      activeTheme = style === 'Dark' ? 'dark' : 'light';
+    } catch {
+      activeTheme = 'light';
+    }
+  } else {
+    activeTheme = 'dark';
+  }
+  
+  return activeTheme;
+}
+
+export function getTheme() {
+  return activeTheme;
+}
+
+// Semantic colors
+export const themeColors = {
+  text: (str) => activeTheme === 'light' ? chalk.black(str) : chalk.white(str),
+  textBold: (str) => activeTheme === 'light' ? chalk.black.bold(str) : chalk.white.bold(str),
+  dim: (str) => activeTheme === 'light' ? chalk.gray(str) : chalk.dim(str),
+  dimYellow: (str) => activeTheme === 'light' ? chalk.rgb(180, 150, 0)(str) : chalk.dim.yellow(str),
+  bgCursor: (str) => activeTheme === 'light' ? chalk.bgRgb(220, 220, 240).black(str) : chalk.bgRgb(30, 30, 60)(str),
+  bgCursorInstall: (str) => activeTheme === 'light' ? chalk.bgRgb(220, 220, 240).black(str) : chalk.bgRgb(24, 44, 62)(str),
+  bgCursorSettingsList: (str) => activeTheme === 'light' ? chalk.bgRgb(220, 240, 220).black(str) : chalk.bgRgb(30, 45, 30)(str),
+  bgCursorLegacy: (str) => activeTheme === 'light' ? chalk.bgRgb(240, 220, 240).black(str) : chalk.bgRgb(55, 25, 55)(str),
+  
+  bgModelCursor: (str) => activeTheme === 'light' ? chalk.bgRgb(230, 210, 230).black(str) : chalk.bgRgb(155, 55, 135)(str),
+  bgModelRecommended: (str) => activeTheme === 'light' ? chalk.bgRgb(200, 240, 200).black(str) : chalk.bgRgb(15, 40, 15)(str),
+  bgModelFavorite: (str) => activeTheme === 'light' ? chalk.bgRgb(250, 230, 190).black(str) : chalk.bgRgb(88, 64, 10)(str),
+  
+  overlayBgSettings: (str) => activeTheme === 'light' ? chalk.bgRgb(245, 245, 250).black(str) : chalk.bgRgb(0, 0, 0).white(str),
+  overlayBgHelp: (str) => activeTheme === 'light' ? chalk.bgRgb(250, 250, 250).black(str) : chalk.bgRgb(0, 0, 0).white(str),
+  overlayBgRecommend: (str) => activeTheme === 'light' ? chalk.bgRgb(240, 250, 245).black(str) : chalk.bgRgb(0, 0, 0).white(str),
+  overlayBgFeedback: (str) => activeTheme === 'light' ? chalk.bgRgb(255, 245, 245).black(str) : chalk.bgRgb(46, 20, 20).white(str),
+
+  // Header badges text color override
+  badgeText: (str) => activeTheme === 'light' ? chalk.rgb(255, 255, 255)(str) : chalk.rgb(0, 0, 0)(str),
+}