free-coding-models 0.3.40 → 0.3.42

package/CHANGELOG.md

@@ -1,21 +1,12 @@
 # Changelog
 ---
 
-## [0.3.40] - 2026-04-09
+## [0.3.42] - 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
+### Added
+- Added a Star History section to the README so users can quickly see project growth and adoption over time.
 
 ### 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
-
-### 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.
+- Xcode Intelligence bootstrap detection now recognizes `xcodebuild`, so the launcher can detect a valid local Xcode install instead of treating the tool as missing.
+- `free-coding-models --web` now checks whether port `3333` already belongs to another app and automatically starts on the next free local port instead of sending users to a misleading `Not Found` page.
+- npm releases now build the web dashboard during `prepack`, so published installs include `web/dist` and the web UI actually loads after install instead of starting a server with no bundled frontend.

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 |
@@ -409,6 +415,18 @@ MIT © [vava](https://github.com/vava-nessa)
 
 ---
 
+## Star History
+
+<a href="https://www.star-history.com/?repos=vava-nessa%2Ffree-coding-models&type=timeline&logscale=&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=vava-nessa/free-coding-models&type=timeline&theme=dark&logscale&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=vava-nessa/free-coding-models&type=timeline&logscale&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=vava-nessa/free-coding-models&type=timeline&logscale&legend=top-left" />
+ </picture>
+</a>
+
+
+
 <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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.40",
+  "version": "0.3.42",
   "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",
@@ -52,6 +52,7 @@
   "scripts": {
     "start": "node bin/free-coding-models.js",
     "test": "node --test test/test.js",
+    "prepack": "npm run build:web",
     "dev:web": "node scripts/dev-web.mjs",
     "build:web": "vite build",
     "preview:web": "vite preview",

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: 'xcodebuild',
+    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',