free-coding-models 0.3.40 → 0.3.41

package/CHANGELOG.md

@@ -1,21 +1,10 @@
 # Changelog
 ---
 
-## [0.3.40] - 2026-04-09
-
-### Fixed
-- **🔧 CI/CD** — Added `packageManager` field to `package.json` so `pnpm/action-setup@v4` can resolve the pnpm version
-
-## [0.3.39] - 2026-04-09
-
-### Fixed
-- **🔧 CI/CD** — Switched GitHub Actions from `npm ci` to `pnpm install --frozen-lockfile` (release + security-audit workflows)
-- Removed obsolete `package-lock.json` that was causing `EUSAGE` sync errors in CI
-
-## [0.3.38] - 2026-04-09
+## [0.3.41] - 2026-04-09
 
 ### Added
-- **🔮 Hermes Agent** — Configures Hermes via `hermes config set`, restarts the gateway, and launches `hermes chat`. Supports all OpenAI-compatible providers.
-- **▶️ Continue CLI** — Writes `~/.continue/config.yaml` with `provider: openai` + `apiBase` and launches `cn`.
-- **🧠 Cline CLI** — Writes `~/.cline/globalState.json` with OpenAI-compatible config and launches `cline`.
-- `--hermes`, `--continue`, `--cline` CLI flags, `Z` cycle entries, command palette actions, and Install Endpoints support for all three tools.
+- Added support for Xcode Intelligence (Xcode 26.3+) via the `--xcode` flag and manual configuration flow. The tool provides clear setup instructions and launches Xcode directly.
+- The `xcode` launcher mode has been registered in the tool metadata, enabling Xcode selection through the command palette, `Z` cycle, and CLI arguments.
+- Users can now use Xcode Intelligence with any of the 230+ supported OpenAI-compatible API endpoints.
+- Compatibility logic ensures Xcode mode accurately highlights supported models (compatible with all standard models).

package/README.md

@@ -14,7 +14,7 @@
 
 <p align="center">
   <strong>Find the fastest free coding model in seconds</strong><br>
-  <sub>Ping 238 models across 25 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, 🔮 Hermes, ▶️ Continue, 🧠 Cline, π Pi, 🦘 Rovo or ♊ Gemini in one keystroke</sub>
+  <sub>Ping 238 models across 25 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, 🔮 Hermes, ▶️ Continue, 🧠 Cline, 🛠️ Xcode, π Pi, 🦘 Rovo or ♊ Gemini in one keystroke</sub>
 </p>
 
 
@@ -159,6 +159,9 @@ free-coding-models --goose --tier S
 # "I want NVIDIA's top models only"
 free-coding-models --origin nvidia --tier S
 
+# "I want the local web dashboard"
+free-coding-models --web
+
 # "Start with an elite-focused preset, then adjust filters live"
 free-coding-models --premium
 
@@ -169,6 +172,8 @@ free-coding-models --tier S --json | jq -r '.[0].modelId'
 free-coding-models --openclaw --origin groq
 ```
 
+When launching the web dashboard, `free-coding-models` prefers `http://localhost:3333`. If that port is already used by another app, it now auto-picks the next free local port and prints the exact URL to open.
+
 ### Tool launcher flags
 
 | Flag | Launches |
@@ -185,6 +190,7 @@ free-coding-models --openclaw --origin groq
 | `--hermes` | 🔮 Hermes |
 | `--continue` | ▶️ Continue CLI |
 | `--cline` | 🧠 Cline |
+| `--xcode` | 🛠️ Xcode Intelligence |
 | `--pi` | π Pi |
 | `--rovo` | 🦘 Rovo Dev CLI |
 | `--gemini` | ♊ Gemini CLI |

package/package.json

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

@@ -114,6 +114,7 @@ import { parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelem
 import { ensureFavoritesConfig, toFavoriteKey, syncFavoriteFlags, toggleFavoriteModel } from '../src/favorites.js'
 import { checkForUpdateDetailed, checkForUpdate, runUpdate, promptUpdateNotification, fetchLastReleaseDate } from './updater.js'
 import { promptApiKey } from '../src/setup.js'
+import { syncShellEnv, ensureShellRcSource, promptShellEnvMigration, removeShellEnv } from '../src/shell-env.js'
 import { stripAnsi, maskApiKey, displayWidth, padEndDisplay, tintOverlayLines, keepOverlayTargetVisible, sliceOverlayLines, calculateViewport, sortResultsWithPinnedFavorites, adjustScrollOffset } from '../src/render-helpers.js'
 import { renderTable, PROVIDER_COLOR } from '../src/render-table.js'
 import { setOpenCodeModelData, startOpenCode, startOpenCodeDesktop } from '../src/opencode.js'
@@ -215,6 +216,31 @@ export async function runApp(cliArgs, config) {
       console.log()
       process.exit(1)
     }
+    // 📖 New users get shell env enabled by default
+    if (config.settings.shellEnvEnabled === undefined) {
+      config.settings.shellEnvEnabled = true
+      saveConfig(config)
+      syncShellEnv(config)
+      ensureShellRcSource()
+    }
+  }
+
+  // 📖 Shell env migration popup for existing users who haven't been asked yet
+  // 📖 Only show when user has keys but shellEnvEnabled is still undefined (never prompted)
+  if (hasAnyKey && config.settings.shellEnvEnabled === undefined) {
+    const choice = await promptShellEnvMigration(config)
+    if (choice === 'enable') {
+      if (!config.settings) config.settings = {}
+      config.settings.shellEnvEnabled = true
+      saveConfig(config)
+      syncShellEnv(config)
+      ensureShellRcSource()
+    } else if (choice === 'never') {
+      if (!config.settings) config.settings = {}
+      config.settings.shellEnvEnabled = false
+      saveConfig(config)
+    }
+    // 📖 'skip' leaves shellEnvEnabled undefined — will prompt again next launch
   }
 
   // 📖 Default mode: use the last persisted launcher choice when valid,
@@ -236,6 +262,7 @@ export async function runApp(cliArgs, config) {
       hermes: cliArgs.hermesMode,
       'continue': cliArgs.continueMode,
       cline: cliArgs.clineMode,
+      xcode: cliArgs.xcodeMode,
       pi: cliArgs.piMode,
       rovo: cliArgs.rovoMode,
       gemini: cliArgs.geminiMode,

package/src/config.js

@@ -102,6 +102,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, renameSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import { syncShellEnv } from './shell-env.js'
 
 // 📖 New JSON config path — stores all providers' API keys + enabled state
 export const CONFIG_PATH = join(homedir(), '.free-coding-models.json')
@@ -484,6 +485,12 @@ export function saveConfig(config, options = {}) {
       }
 
       replaceConfigContents(config, persistedConfig)
+
+      // 📖 Keep shell env file in sync when enabled
+      if (persistedConfig.settings?.shellEnvEnabled) {
+        try { syncShellEnv(persistedConfig) } catch { /* non-critical */ }
+      }
+
       return { success: true, backupCreated }
     } catch (verifyError) {
       // 📖 Verification failed - this is critical!

package/src/key-handler.js

@@ -33,6 +33,7 @@ import { loadConfig, replaceConfigContents } from './config.js'
 import { cleanupLegacyProxyArtifacts } from './legacy-proxy-cleanup.js'
 import { getLastLayout, COLUMN_SORT_MAP } from './render-table.js'
 import { cycleThemeSetting, detectActiveTheme } from './theme.js'
+import { syncShellEnv, ensureShellRcSource, removeShellEnv } from './shell-env.js'
 import { buildCommandPaletteTree, flattenCommandTree, filterCommandPaletteEntries } from './command-palette.js'
 import { WIDTH_WARNING_MIN_COLS } from './constants.js'
 import { scanAllToolConfigs, softDeleteModel } from './installed-models-manager.js'
@@ -553,6 +554,19 @@ export function createKeyHandler(ctx) {
     applyThemeSetting(cycleThemeSetting(currentTheme))
   }
 
+  function toggleShellEnv() {
+    if (!state.config.settings) state.config.settings = {}
+    const currentlyEnabled = state.config.settings.shellEnvEnabled === true
+    state.config.settings.shellEnvEnabled = !currentlyEnabled
+    saveConfig(state.config)
+    if (!currentlyEnabled) {
+      syncShellEnv(state.config)
+      ensureShellRcSource()
+    } else {
+      removeShellEnv()
+    }
+  }
+
   function resetInstallEndpointsOverlay() {
     state.installEndpointsOpen = false
     state.installEndpointsPhase = 'providers'
@@ -1828,8 +1842,9 @@ export function createKeyHandler(ctx) {
       const favoritesModeRowIdx = themeRowIdx + 1
       const cleanupLegacyProxyRowIdx = favoritesModeRowIdx + 1
       const changelogViewRowIdx = cleanupLegacyProxyRowIdx + 1
+      const shellEnvRowIdx = changelogViewRowIdx + 1
         // 📖 Profile system removed - API keys now persist permanently across all sessions
-      const maxRowIdx = changelogViewRowIdx
+      const maxRowIdx = shellEnvRowIdx
 
       // 📖 Edit/Add-key mode: capture typed characters for the API key
       if (state.settingsEditMode || state.settingsAddKeyMode) {
@@ -1993,6 +2008,12 @@ export function createKeyHandler(ctx) {
           return
         }
 
+        // 📖 Shell env row: Enter → toggle shell env export
+        if (state.settingsCursor === shellEnvRowIdx) {
+          toggleShellEnv()
+          return
+        }
+
         // 📖 Profile system removed - API keys now persist permanently across all sessions
 
         // 📖 Enter edit mode for the selected provider's key
@@ -2010,6 +2031,11 @@ export function createKeyHandler(ctx) {
           || state.settingsCursor === cleanupLegacyProxyRowIdx
           || state.settingsCursor === changelogViewRowIdx
         ) return
+        // 📖 Shell env toggle
+        if (state.settingsCursor === shellEnvRowIdx) {
+          toggleShellEnv()
+          return
+        }
         // 📖 Theme configuration cycle inside settings
         if (state.settingsCursor === themeRowIdx) {
           cycleGlobalTheme()

package/src/overlays.js

@@ -120,6 +120,7 @@ export function createOverlayRenderers(state, deps) {
     const favoritesModeRowIdx = themeRowIdx + 1
     const cleanupLegacyProxyRowIdx = favoritesModeRowIdx + 1
     const changelogViewRowIdx = cleanupLegacyProxyRowIdx + 1
+    const shellEnvRowIdx = changelogViewRowIdx + 1
     const EL = '\x1b[K'
     const lines = []
     const cursorLineByRow = {}
@@ -272,6 +273,15 @@ export function createOverlayRenderers(state, deps) {
     cursorLineByRow[changelogViewRowIdx] = lines.length
     lines.push(state.settingsCursor === changelogViewRowIdx ? themeColors.bgCursorSettingsList(changelogViewRow) : changelogViewRow)
 
+    // 📖 Shell env toggle — expose API keys as shell environment variables
+    const shellEnvEnabled = state.config.settings?.shellEnvEnabled === true
+    const shellEnvStatus = shellEnvEnabled
+      ? themeColors.successBold('✅ Enabled — keys available in shell')
+      : themeColors.dim('❌ Disabled')
+    const shellEnvRow = `${bullet(state.settingsCursor === shellEnvRowIdx)}${themeColors.textBold('Shell Env Export').padEnd(44)} ${shellEnvStatus}`
+    cursorLineByRow[shellEnvRowIdx] = lines.length
+    lines.push(state.settingsCursor === shellEnvRowIdx ? themeColors.bgCursorSettingsList(shellEnvRow) : shellEnvRow)
+
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
     lines.push('')
@@ -313,7 +323,7 @@ export function createOverlayRenderers(state, deps) {
     // 📖 Mouse support: record layout so click handler can map Y → settingsCursor
     overlayLayout.settingsCursorToLine = { ...cursorLineByRow }
     overlayLayout.settingsScrollOffset = offset
-    overlayLayout.settingsMaxRow = changelogViewRowIdx
+    overlayLayout.settingsMaxRow = shellEnvRowIdx
 
     const tintedLines = tintOverlayLines(visible, themeColors.overlayBgSettings, state.terminalCols)
     const cleared = tintedLines.map(l => l + EL)

package/src/shell-env.js

@@ -0,0 +1,393 @@
+/**
+ * @file shell-env.js
+ * @description Exposes API keys as shell environment variables via a sourced dotfile.
+ *
+ * @details
+ *   Creates `~/.free-coding-models.env` containing `export VAR="value"` lines for every
+ *   configured provider, and injects a single `[ -f ~/.free-coding-models.env ] && source ...`
+ *   line into the user's shell rc file (`.zshrc`, `.bashrc`, or fish `config.fish`).
+ *
+ *   The env file is kept in sync automatically: every time `saveConfig()` or
+ *   `persistApiKeysForProvider()` writes a new config to disk, `syncShellEnv()` is called
+ *   to regenerate the `.env` if `settings.shellEnvEnabled === true`.
+ *
+ *   Shell detection uses `$SHELL` with a fallback chain: zsh → bash → fish.
+ *   Each shell's rc path is resolved relative to `$HOME`. Fish uses `set -gx` syntax
+ *   instead of `export`, which is handled transparently.
+ *
+ *   The env file is written with mode `0600` (owner read/write only) to protect API keys.
+ *   The source line in the rc file is idempotent — calling `ensureShellRcSource()` multiple
+ *   times will never add a duplicate line.
+ *
+ * @functions
+ *   → `syncShellEnv(config)` — regenerate the .env file from current apiKeys
+ *   → `ensureShellRcSource()` — add the source line to the detected shell rc (idempotent)
+ *   → `removeShellEnv()` — delete the .env file and remove the source line from rc
+ *   → `detectShellInfo()` — return { shell, rcPath } for the current user
+ *   → `getEnvFilePath()` — return the absolute path to ~/.free-coding-models.env
+ *   → `buildEnvContent(config, shell)` — build the env file body (pure function, testable)
+ *   → `buildRcSourceLine(envFilePath, shell)` — build the rc source line for a given shell
+ *
+ * @exports syncShellEnv, ensureShellRcSource, removeShellEnv, detectShellInfo,
+ *          getEnvFilePath, buildEnvContent, buildRcSourceLine, ENV_FILE_MARKER
+ *
+ * @see src/config.js — calls syncShellEnv() after saveConfig()
+ * @see src/provider-metadata.js — ENV_VAR_NAMES maps provider → env var name
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import * as readline from 'node:readline'
+import chalk from 'chalk'
+import { ENV_VAR_NAMES } from './provider-metadata.js'
+
+// 📖 Unique marker used to identify the source line we inject into shell rc files.
+// 📖 This allows idempotent add/remove without relying on exact path matching.
+export const ENV_FILE_MARKER = '# free-coding-models-env'
+
+// 📖 The env dotfile path — always next to the JSON config in $HOME.
+const ENV_FILE_NAME = '.free-coding-models.env'
+
+/**
+ * 📖 Returns the absolute path to the env dotfile.
+ * @returns {string}
+ */
+export function getEnvFilePath() {
+  return join(homedir(), ENV_FILE_NAME)
+}
+
+/**
+ * 📖 Detect the user's shell and return its rc file path.
+ *
+ * Detection order: $SHELL env var → fallback to zsh → bash → fish.
+ * Returns the shell type ('zsh'|'bash'|'fish') and the absolute rc path.
+ *
+ * @returns {{ shell: 'zsh'|'bash'|'fish', rcPath: string }}
+ */
+export function detectShellInfo() {
+  const shellEnv = (process.env.SHELL || '').toLowerCase()
+  const home = homedir()
+
+  if (shellEnv.includes('zsh')) {
+    return { shell: 'zsh', rcPath: join(home, '.zshrc') }
+  }
+  if (shellEnv.includes('bash')) {
+    return { shell: 'bash', rcPath: join(home, '.bashrc') }
+  }
+  if (shellEnv.includes('fish')) {
+    return { shell: 'fish', rcPath: join(home, '.config', 'fish', 'config.fish') }
+  }
+
+  // 📖 Fallback: try to detect which rc files exist
+  if (existsSync(join(home, '.zshrc'))) {
+    return { shell: 'zsh', rcPath: join(home, '.zshrc') }
+  }
+  if (existsSync(join(home, '.bashrc'))) {
+    return { shell: 'bash', rcPath: join(home, '.bashrc') }
+  }
+  const fishConfig = join(home, '.config', 'fish', 'config.fish')
+  if (existsSync(fishConfig)) {
+    return { shell: 'fish', rcPath: fishConfig }
+  }
+
+  // 📖 Last resort: assume zsh (most common on macOS/Linux)
+  return { shell: 'zsh', rcPath: join(home, '.zshrc') }
+}
+
+/**
+ * 📖 Build the env file content for a given shell type.
+ *
+ * Pure function — no I/O. Iterates over config.apiKeys and generates
+ * the appropriate `export` (bash/zsh) or `set -gx` (fish) lines.
+ *
+ * @param {{ apiKeys: Record<string, string|string[]> }} config
+ * @param {'zsh'|'bash'|'fish'} shell
+ * @returns {string} The complete file content to write
+ */
+export function buildEnvContent(config, shell) {
+  const apiKeys = config?.apiKeys || {}
+  const lines = [
+    '#!/bin/env sh',
+    `# ${ENV_FILE_MARKER}`,
+    '# Auto-generated by free-coding-models — do not edit manually.',
+    '# Changes to API keys are synced automatically from the TUI.',
+    '',
+  ]
+
+  const isFish = shell === 'fish'
+
+  for (const [providerKey, envName] of Object.entries(ENV_VAR_NAMES)) {
+    const rawValue = apiKeys[providerKey]
+    if (!rawValue) continue
+
+    // 📖 Support multi-key arrays — use the first key for shell env
+    const value = Array.isArray(rawValue) ? rawValue[0] : rawValue
+    if (!value || typeof value !== 'string') continue
+
+    const safeValue = value.replace(/'/g, "'\\''")
+
+    if (isFish) {
+      lines.push(`set -gx ${envName} '${safeValue}'`)
+    } else {
+      lines.push(`export ${envName}='${safeValue}'`)
+    }
+  }
+
+  lines.push('')
+  return lines.join('\n')
+}
+
+/**
+ * 📖 Build the rc source line that loads the env file.
+ *
+ * For bash/zsh: `[ -f ~/.free-coding-models.env ] && . ~/.free-coding-models.env  # free-coding-models-env`
+ * For fish:     `test -f ~/.free-coding-models.env; and source ~/.free-coding-models.env  # free-coding-models-env`
+ *
+ * @param {string} envFilePath — absolute path to the .env file
+ * @param {'zsh'|'bash'|'fish'} shell
+ * @returns {string} A single line to append to the rc file
+ */
+export function buildRcSourceLine(envFilePath, shell) {
+  const home = homedir()
+  // 📖 Use ~/ relative path in rc for portability
+  const relativePath = envFilePath.startsWith(home)
+    ? '~/' + envFilePath.slice(home.length + 1)
+    : envFilePath
+
+  if (shell === 'fish') {
+    return `test -f ${relativePath}; and source ${relativePath}  ${ENV_FILE_MARKER}`
+  }
+  return `[ -f ${relativePath} ] && . ${relativePath}  ${ENV_FILE_MARKER}`
+}
+
+/**
+ * 📖 Regenerate the env file from the current config.
+ *
+ * Called after every saveConfig() when shellEnvEnabled is true.
+ * Writes with mode 0600 for security. Skips if there are no keys.
+ *
+ * @param {{ apiKeys: Record<string, string|string[]>, settings?: { shellEnvEnabled?: boolean } }} config
+ * @returns {{ success: boolean, envPath: string, error?: string }}
+ */
+export function syncShellEnv(config) {
+  const { shell } = detectShellInfo()
+  const envPath = getEnvFilePath()
+  const apiKeys = config?.apiKeys || {}
+  const hasKeys = Object.values(apiKeys).some(v => {
+    if (Array.isArray(v)) return v.length > 0
+    return !!v
+  })
+
+  if (!hasKeys) {
+    // 📖 No keys — remove stale env file if it exists
+    if (existsSync(envPath)) {
+      try { unlinkSync(envPath) } catch { /* best effort */ }
+    }
+    return { success: true, envPath }
+  }
+
+  try {
+    const content = buildEnvContent(config, shell)
+    writeFileSync(envPath, content, { mode: 0o600 })
+    return { success: true, envPath }
+  } catch (err) {
+    return { success: false, envPath, error: err.message }
+  }
+}
+
+/**
+ * 📖 Add the source line to the user's shell rc file (idempotent).
+ *
+ * Creates the rc file if it doesn't exist. Skips if the marker is already present.
+ *
+ * @returns {{ success: boolean, rcPath: string, wasAdded: boolean, error?: string }}
+ */
+export function ensureShellRcSource() {
+  const { shell, rcPath } = detectShellInfo()
+  const envPath = getEnvFilePath()
+  const sourceLine = buildRcSourceLine(envPath, shell)
+
+  let existingContent = ''
+  if (existsSync(rcPath)) {
+    try {
+      existingContent = readFileSync(rcPath, 'utf8')
+    } catch (err) {
+      return { success: false, rcPath, wasAdded: false, error: `Cannot read ${rcPath}: ${err.message}` }
+    }
+  }
+
+  // 📖 Idempotent: skip if our marker is already in the file
+  if (existingContent.includes(ENV_FILE_MARKER)) {
+    return { success: true, rcPath, wasAdded: false }
+  }
+
+  try {
+    // 📖 Ensure parent directory exists (e.g. ~/.config/fish/)
+    const dir = join(rcPath, '..')
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+    const newContent = existingContent
+      ? existingContent.trimEnd() + '\n\n' + sourceLine + '\n'
+      : sourceLine + '\n'
+    writeFileSync(rcPath, newContent)
+    return { success: true, rcPath, wasAdded: true }
+  } catch (err) {
+    return { success: false, rcPath, wasAdded: false, error: `Cannot write ${rcPath}: ${err.message}` }
+  }
+}
+
+/**
+ * 📖 Remove the env file and the source line from the shell rc.
+ *
+ * @returns {{ success: boolean, envRemoved: boolean, rcCleaned: boolean, error?: string }}
+ */
+export function removeShellEnv() {
+  const { shell, rcPath } = detectShellInfo()
+  const envPath = getEnvFilePath()
+  let envRemoved = false
+  let rcCleaned = false
+
+  // 📖 Remove the env file
+  if (existsSync(envPath)) {
+    try {
+      unlinkSync(envPath)
+      envRemoved = true
+    } catch (err) {
+      return { success: false, envRemoved: false, rcCleaned: false, error: `Cannot delete ${envPath}: ${err.message}` }
+    }
+  }
+
+  // 📖 Remove the source line from rc
+  if (existsSync(rcPath)) {
+    try {
+      const content = readFileSync(rcPath, 'utf8')
+      if (content.includes(ENV_FILE_MARKER)) {
+        const cleaned = content
+          .split('\n')
+          .filter(line => !line.includes(ENV_FILE_MARKER))
+          .join('\n')
+          .replace(/\n{3,}/g, '\n\n')
+        writeFileSync(rcPath, cleaned)
+        rcCleaned = true
+      }
+    } catch {
+      // 📖 Non-critical — env file is already removed
+    }
+  }
+
+  return { success: true, envRemoved, rcCleaned }
+}
+
+/**
+ * 📖 Pre-TUI popup asking the user whether to enable shell env exposure.
+ *
+ * Follows the same pattern as `promptUpdateNotification()` in updater.js.
+ * Shows three options: Enable (recommended, green), Skip for now, Don't ask again.
+ * Runs BEFORE entering the alt-screen buffer so it renders in the normal terminal.
+ *
+ * @param {{ apiKeys: Record<string, string|string[]>, settings: object }} config
+ * @returns {Promise<'enable'|'skip'|'never'>} The user's choice
+ */
+export async function promptShellEnvMigration(config) {
+  const { shell, rcPath } = detectShellInfo()
+  const rcName = rcPath.split('/').pop()
+  const keyCount = Object.keys(config.apiKeys || {}).filter(pk => {
+    const v = config.apiKeys[pk]
+    return Array.isArray(v) ? v.length > 0 : !!v
+  }).length
+
+  return new Promise((resolve) => {
+    let selected = 0
+    const options = [
+      {
+        label: 'Yes, enable (recommended)',
+        icon: '✅',
+        description: `Export ${keyCount} API key${keyCount > 1 ? 's' : ''} to shell via ${rcName}`,
+      },
+      {
+        label: 'Skip for now',
+        icon: '⏭',
+        description: 'You can enable it later in Settings (P)',
+      },
+      {
+        label: "Don't ask again",
+        icon: '🔇',
+        description: 'Disable this prompt permanently',
+      },
+    ]
+
+    const render = () => {
+      process.stdout.write('\x1b[2J\x1b[H')
+
+      const terminalWidth = process.stdout.columns || 80
+      const maxWidth = Math.min(terminalWidth - 4, 70)
+      const centerPad = ' '.repeat(Math.max(0, Math.floor((terminalWidth - maxWidth) / 2)))
+
+      console.log()
+      console.log(centerPad + chalk.bold.rgb(110, 214, 255)('  🐚 Shell Environment Setup'))
+      console.log()
+      console.log(centerPad + chalk.white('  Expose your API keys as environment variables'))
+      console.log(centerPad + chalk.white('  so they are available globally in your shell.'))
+      console.log()
+      console.log(centerPad + chalk.dim(`  Detected shell: ${shell} (${rcName})`))
+      console.log(centerPad + chalk.dim(`  This adds a single source line to ${rcName}`))
+      console.log(centerPad + chalk.dim('  and creates ~/.free-coding-models.env (0600)'))
+      console.log()
+
+      for (let i = 0; i < options.length; i++) {
+        const isSelected = i === selected
+        const bullet = isSelected ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+        let label
+        if (i === 0) {
+          label = isSelected
+            ? chalk.bold.rgb(112, 231, 181)(options[i].icon + ' ' + options[i].label + ' ★')
+            : chalk.rgb(112, 231, 181)(options[i].icon + ' ' + options[i].label)
+        } else {
+          label = isSelected
+            ? chalk.bold.white(options[i].icon + ' ' + options[i].label)
+            : chalk.dim(options[i].icon + ' ' + options[i].label)
+        }
+
+        console.log(centerPad + bullet + label)
+        console.log(centerPad + chalk.dim('       ' + options[i].description))
+        console.log()
+      }
+
+      console.log(centerPad + chalk.dim('  ↑↓ Navigate  •  Enter Select  •  Ctrl+C Skip'))
+      console.log()
+    }
+
+    render()
+
+    readline.emitKeypressEvents(process.stdin)
+    if (process.stdin.isTTY) process.stdin.setRawMode(true)
+
+    const onKey = (_str, key) => {
+      if (!key) return
+      if (key.ctrl && key.name === 'c') {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false)
+        process.stdin.removeListener('keypress', onKey)
+        resolve('skip')
+        return
+      }
+      if (key.name === 'up' && selected > 0) {
+        selected--
+        render()
+      } else if (key.name === 'down' && selected < options.length - 1) {
+        selected++
+        render()
+      } else if (key.name === 'return') {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false)
+        process.stdin.removeListener('keypress', onKey)
+        process.stdin.pause()
+
+        if (selected === 0) resolve('enable')
+        else if (selected === 1) resolve('skip')
+        else resolve('never')
+      }
+    }
+
+    process.stdin.on('keypress', onKey)
+  })
+}

package/src/tool-bootstrap.js

@@ -248,6 +248,13 @@ export const TOOL_BOOTSTRAP_METADATA = {
       },
     },
   },
+  xcode: {
+    binary: null,
+    docsUrl: 'https://developer.apple.com/documentation/Xcode/setting-up-coding-intelligence',
+    installUnsupported: {
+      default: 'Xcode Intelligence requires manual setup. Go to Xcode > Settings > Intelligence > Add a Chat Provider.',
+    },
+  },
   hermes: {
     binary: 'hermes',
     docsUrl: 'https://github.com/NousResearch/hermes-agent',

package/src/tool-launchers.js

@@ -462,7 +462,9 @@ function writeHermesConfig(model, apiKey, baseUrl, paths = getDefaultToolPaths()
   const hermesBin = resolveToolBinaryPath('hermes') || 'hermes'
 
   // 📖 Use `hermes config set` for each field — robust and dependency-free
-  spawnSync(hermesBin, ['config', 'set', 'model', model.modelId], { stdio: 'ignore' })
+  // 📖 Must use 'model.default' not 'model', otherwise it replaces the entire model: dict with a string
+  // 📖 and subsequent model.provider / model.base_url / model.api_key calls silently fail
+  spawnSync(hermesBin, ['config', 'set', 'model.default', model.modelId], { stdio: 'ignore' })
   spawnSync(hermesBin, ['config', 'set', 'model.provider', 'custom'], { stdio: 'ignore' })
   if (baseUrl) {
     spawnSync(hermesBin, ['config', 'set', 'model.base_url', baseUrl], { stdio: 'ignore' })
@@ -716,6 +718,18 @@ export function prepareExternalToolLaunch(mode, model, config, options = {}) {
     }
   }
 
+  if (mode === 'xcode') {
+    return {
+      command: 'open',
+      args: ['-a', 'Xcode'],
+      env,
+      apiKey,
+      baseUrl,
+      meta,
+      configArtifacts: [],
+    }
+  }
+
   if (mode === 'rovo') {
     const result = writeRovoConfig(model, join(homedir(), '.rovodev', 'config.yml'), paths)
     console.log(chalk.dim(`  📖 Rovo Dev CLI configured with model: ${model.modelId}`))
@@ -815,6 +829,21 @@ export async function startExternalTool(mode, model, config) {
     return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
   }
 
+  if (mode === 'xcode') {
+    const xcodeUrl = baseUrl ? baseUrl.replace(/\/v1$/, '').replace(/\/v1\/chat\/completions$/, '') : ''
+    console.log(chalk.bold.cyan('\n  🛠️  Xcode Intelligence Setup Instructions:'))
+    console.log(chalk.white('  1. Open Xcode and go to ') + chalk.bold('Xcode > Settings > Intelligence'))
+    console.log(chalk.white('  2. Click ') + chalk.bold('Add a Chat Provider') + chalk.white(' and select ') + chalk.bold('Internet Hosted'))
+    console.log(chalk.white('  3. Enter the following details:'))
+    console.log(chalk.dim('     URL: ') + chalk.green(xcodeUrl))
+    console.log(chalk.dim('     API Key: ') + chalk.green(apiKey || '<your_api_key>'))
+    console.log(chalk.dim('     API Key Header: ') + chalk.green('Authorization') + chalk.dim(' (or x-api-key)'))
+    console.log(chalk.dim('     Description: ') + chalk.green(`FCM - ${sources[model.providerKey]?.name || model.providerKey}`))
+    console.log(chalk.white(`  4. Click Add, then select `) + chalk.bold(model.modelId) + chalk.white(` from the list.\n`))
+    console.log(chalk.dim(`  📖 Attempting to launch Xcode...`))
+    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
+  }
+
   if (mode === 'rovo') {
     console.log(chalk.dim(`  📖 Launching Rovo Dev CLI in interactive mode...`))
     return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)

package/src/tool-metadata.js

@@ -41,6 +41,7 @@ export const TOOL_METADATA = {
   cline:             { label: 'Cline',             emoji: '🧠', flag: '--cline',            color: [100, 220, 180] },
   rovo:              { label: 'Rovo Dev CLI',      emoji: '🦘', flag: '--rovo',             color: [148, 163, 184], cliOnly: true },
   gemini:            { label: 'Gemini CLI',        emoji: '♊', flag: '--gemini',           color: [66, 165, 245],  cliOnly: true },
+  xcode:             { label: 'Xcode Intelligence',emoji: '🛠️', flag: '--xcode',            color: [20, 126, 251] },
 }
 
 // 📖 Deduplicated emoji order for the "Compatible with" column.
@@ -61,6 +62,7 @@ export const COMPAT_COLUMN_SLOTS = [
   { emoji: '🧠', toolKeys: ['cline'],                        color: [100, 220, 180] },
   { emoji: '🦘', toolKeys: ['rovo'],                         color: [148, 163, 184] },
   { emoji: '♊', toolKeys: ['gemini'],                       color: [66, 165, 245] },
+  { emoji: '🛠️', toolKeys: ['xcode'],                        color: [20, 126, 251] },
 ]
 
 export const TOOL_MODE_ORDER = [
@@ -77,6 +79,7 @@ export const TOOL_MODE_ORDER = [
   'hermes',
   'continue',
   'cline',
+  'xcode',
   'rovo',
   'gemini',
 ]

package/src/utils.js

@@ -458,6 +458,7 @@ export function parseArgs(argv) {
   const hermesMode = flags.includes('--hermes')
   const continueMode = flags.includes('--continue')
   const clineMode = flags.includes('--cline')
+  const xcodeMode = flags.includes('--xcode')
   const geminiMode = flags.includes('--gemini')
   const noTelemetry = flags.includes('--no-telemetry')
   const jsonMode = flags.includes('--json')
@@ -501,6 +502,7 @@ export function parseArgs(argv) {
     hermesMode,
     continueMode,
     clineMode,
+    xcodeMode,
     rovoMode,
     geminiMode,
     noTelemetry,

package/web/server.js

@@ -11,6 +11,7 @@
  *   GET /styles.css    → Dashboard styles
  *   GET /app.js        → Dashboard client JS
  *   GET /api/models    → All model metadata (JSON)
+ *   GET /api/health    → Lightweight dashboard health probe
  *   GET /api/config    → Current config (sanitized — masked keys)
  *   GET /api/key/:prov → Reveal a provider's full API key
  *   GET /api/events    → SSE stream of live ping results
@@ -32,6 +33,7 @@ import {
 } from '../src/utils.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
+const SERVER_SIGNATURE = 'free-coding-models-web'
 
 // ─── State ───────────────────────────────────────────────────────────────────
 
@@ -215,6 +217,8 @@ function serveDistFile(res, pathname) {
 }
 
 function handleRequest(req, res) {
+  res.setHeader('X-FCM-Server', SERVER_SIGNATURE)
+
   // CORS for local dev
   res.setHeader('Access-Control-Allow-Origin', '*')
   res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
@@ -265,6 +269,11 @@ function handleRequest(req, res) {
       res.end(JSON.stringify(getModelsPayload()))
       break
 
+    case '/api/health':
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ ok: true, app: SERVER_SIGNATURE }))
+      break
+
     case '/api/config':
       res.writeHead(200, { 'Content-Type': 'application/json' })
       res.end(JSON.stringify(getConfigPayload()))
@@ -335,6 +344,40 @@ function checkPortInUse(port) {
   })
 }
 
+export async function inspectExistingWebServer(port) {
+  const inUse = await checkPortInUse(port)
+  if (!inUse) return { inUse: false, isFcm: false }
+
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 750)
+
+  try {
+    // 📖 Probe a tiny health route so we only reuse a port when the running
+    // 📖 process is actually the free-coding-models dashboard, not any random app.
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    })
+    const payload = await response.json().catch(() => null)
+    const signature = response.headers.get('x-fcm-server')
+    return {
+      inUse: true,
+      isFcm: signature === SERVER_SIGNATURE || payload?.app === SERVER_SIGNATURE,
+    }
+  } catch {
+    return { inUse: true, isFcm: false }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export async function findAvailablePort(startPort, maxAttempts = 20) {
+  for (let port = startPort; port < startPort + maxAttempts; port++) {
+    if (!(await checkPortInUse(port))) return port
+  }
+  throw new Error(`No free local port found between ${startPort} and ${startPort + maxAttempts - 1}`)
+}
+
 function openBrowser(url) {
   const cmd = process.platform === 'darwin' ? 'open'
     : process.platform === 'win32' ? 'start'
@@ -346,11 +389,12 @@ function openBrowser(url) {
 
 // ─── Exports ─────────────────────────────────────────────────────────────────
 
-export async function startWebServer(port = 3333, { open = true } = {}) {
-  const alreadyRunning = await checkPortInUse(port)
-  const url = `http://localhost:${port}`
+export async function startWebServer(port = 3333, { open = true, startPingLoop = true } = {}) {
+  const portStatus = await inspectExistingWebServer(port)
+
+  if (portStatus.inUse && portStatus.isFcm) {
+    const url = `http://localhost:${port}`
 
-  if (alreadyRunning) {
     console.log()
     console.log(`  ⚡ free-coding-models Web Dashboard already running`)
     console.log(`  🌐 ${url}`)
@@ -359,9 +403,21 @@ export async function startWebServer(port = 3333, { open = true } = {}) {
     return null
   }
 
+  let resolvedPort = port
+  if (portStatus.inUse && !portStatus.isFcm) {
+    resolvedPort = await findAvailablePort(port + 1)
+    console.log()
+    console.log(`  ⚠️ Port ${port} is already in use by another local app`)
+    console.log(`  ↪ Starting free-coding-models Web Dashboard on port ${resolvedPort} instead`)
+    console.log()
+  }
+
+  const url = `http://localhost:${resolvedPort}`
+
   const server = createServer(handleRequest)
+  let pingLoopTimer = null
 
-  server.listen(port, () => {
+  server.listen(resolvedPort, () => {
     console.log()
     console.log(`  ⚡ free-coding-models Web Dashboard`)
     console.log(`  🌐 ${url}`)
@@ -373,10 +429,15 @@ export async function startWebServer(port = 3333, { open = true } = {}) {
   })
 
   async function schedulePingLoop() {
+    if (!server.listening) return
     await pingAllModels()
-    setTimeout(schedulePingLoop, 10_000)
+    pingLoopTimer = setTimeout(schedulePingLoop, 10_000)
   }
-  schedulePingLoop()
+
+  if (startPingLoop) schedulePingLoop()
+  server.on('close', () => {
+    if (pingLoopTimer) clearTimeout(pingLoopTimer)
+  })
 
   return server
 }