free-coding-models 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ---
 
+## 0.2.17
+
+### Added
+- **All coding tools re-enabled in Z-cycle**: Aider, Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenHands, and Amp are now back in the public tool mode cycle alongside OpenCode, OpenClaw, Crush, Goose, and Pi — 13 tools total.
+- **All coding tools available in Install Endpoints (Y key)**: The endpoint installer now supports all 13 tools as install targets, not just the original 5. Each tool gets its proper config format (JSON, YAML, or env file).
+- **Connection mode choice in Install flow**: When installing endpoints (Y key), users now choose between **Direct Provider** (pure API connection) or **FCM Proxy** (local proxy with key rotation and usage tracking) — new Step 3 in the 5-step flow.
+- **Install support for new tools**: Pi (models.json + settings.json), Aider (.aider.conf.yml), Amp (settings.json), Gemini (settings.json), Qwen (modelProviders config), Claude Code/Codex/OpenHands (sourceable env files at ~/.fcm-*-env).
+
+### Changed
+- **Install Endpoints flow is now 5 steps**: Provider → Tool → Connection Mode → Scope → Models (was 4 steps without connection mode choice).
+- **Tool labels in install overlay use metadata**: Tool names and emojis in the Y overlay now come from `tool-metadata.js` instead of hard-coded ternary chains — easier to maintain and always in sync.
+- **Help overlay updated**: Z-cycle hint and CLI flag examples now list all 13 tools.
+
+---
+
+## 0.2.16
+
+### Fixed
+- **Changelog index viewport scrolling**: Cursor in changelog version list (N key) now scrolls the viewport to follow selection — previously scrolling past the last visible row would move the cursor off-screen into empty space.
+
+### Added
+- **Changelog version summaries**: Each version in the changelog index now shows a short summary (first change title, ~15 words) after the change count, displayed in dim for readability.
+
+---
+
 ## 0.2.15
 
 ### Changed

package/README.md

@@ -87,7 +87,7 @@ By Vanessa Depraute
 - **💻 OpenCode integration** — Auto-detects NIM setup, sets model as default, launches OpenCode
 - **🦞 OpenClaw integration** — Sets selected model as default provider in `~/.openclaw/openclaw.json`
 - **🧰 Public tool launchers** — `Enter` auto-configures and launches 10+ tools: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Aider`, `Claude Code`, `Codex`, `Gemini`, `Qwen`, `OpenHands`, `Amp`, and `Pi`. All tools auto-select the chosen model on launch.
-- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider directly into `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Aider`, or `Gemini`, either with the full provider catalog or a curated subset of models
+- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider into any of the 13 supported tools, with a choice between **Direct Provider** (pure API) or **FCM Proxy** (key rotation + usage tracking), then pick all models or a curated subset
 - **📝 Feature Request (J key)** — Send anonymous feedback directly to the project team
 - **🐛 Bug Report (I key)** — Send anonymous bug reports directly to the project team
  - **🎨 Clean output** — Zero scrollback pollution, interface stays open until Ctrl+C
@@ -237,8 +237,8 @@ free-coding-models --tier S --json
 
 Running `free-coding-models` with no launcher flag starts in **OpenCode CLI** mode.
 
-- Press **`Z`** in the TUI to cycle the public launch targets: `OpenCode CLI` → `OpenCode Desktop` → `OpenClaw` → `Crush` → `Goose`
-- Or start directly in the target mode with a CLI flag such as `--opencode-desktop`, `--openclaw`, `--crush`, or `--goose`
+- Press **`Z`** in the TUI to cycle the public launch targets: `OpenCode CLI` → `OpenCode Desktop` → `OpenClaw` → `Crush` → `Goose` → `Pi` → `Aider` → `Claude Code` → `Codex` → `Gemini` → `Qwen` → `OpenHands` → `Amp`
+- Or start directly in the target mode with a CLI flag such as `--opencode-desktop`, `--openclaw`, `--crush`, `--goose`, `--pi`, `--aider`, `--claude-code`, `--codex`, `--gemini`, `--qwen`, `--openhands`, or `--amp`
 - The active target is always visible in the header badge before you press `Enter`
 
 **How it works:**
@@ -615,7 +615,9 @@ You can use `free-coding-models` with 12+ AI coding tools. When you select a mod
 | **Amp** | `--amp` | ~/.config/amp/settings.json |
 | **Pi** | `--pi` | ~/.pi/agent/settings.json |
 
-Press **Z** to cycle through different tool modes in the TUI, or use flags to start in your preferred mode.
+Press **Z** to cycle through all 13 tool modes in the TUI, or use flags to start in your preferred mode.
+
+All tools are also available as install targets in the **Install Endpoints** flow (`Y` key) — install an entire provider catalog into any tool with one flow, choosing between Direct Provider or FCM Proxy connection.
 
 ---
 
@@ -924,11 +926,11 @@ This script:
 - **T** — Cycle tier filter (All → S+ → S → A+ → A → A- → B+ → B → C → All)
 - **D** — Cycle provider filter (All → NIM → Groq → ...)
 - **E** — Toggle configured-only mode (on by default, persisted across sessions and profiles)
-- **Z** — Cycle target tool (OpenCode CLI → OpenCode Desktop → OpenClaw → Crush → Goose)
+- **Z** — Cycle target tool (OpenCode CLI → Desktop → OpenClaw → Crush → Goose → Pi → Aider → Claude Code → Codex → Gemini → Qwen → OpenHands → Amp)
 - **X** — Toggle request logs (recent proxied request/token usage logs, up to 500 entries)
 - **A (in logs)** — Toggle between showing 500 entries or ALL logs
 - **P** — Open Settings (manage API keys, toggles, updates, profiles)
-- **Y** — Open Install Endpoints (`provider → tool → all models` or `selected models only`, no proxy)
+- **Y** — Open Install Endpoints (`provider → tool → connection mode → scope → models`, Direct or FCM Proxy)
 - **Shift+P** — Cycle through saved profiles (switches live TUI settings)
 - **Shift+S** — Save current TUI settings as a named profile (inline prompt)
 - **Q** — Open Smart Recommend overlay (find the best model for your task)
@@ -942,18 +944,25 @@ Pressing **K** now shows a full in-app reference: main hotkeys, settings hotkeys
 
 ### 🔌 Install Endpoints (`Y`)
 
-`Y` opens a dedicated install flow for configured providers. The flow is:
+`Y` opens a dedicated install flow for configured providers. The 5-step flow is:
 
-1. Pick one provider that already has an API key in Settings
-2. Pick the target tool: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, or `Goose`
-3. Choose either `Install all models` or `Install selected models only`
+1. **Provider** — Pick one provider that already has an API key in Settings
+2. **Tool** — Pick the target tool from all 13 supported tools:
+   - Config-based: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Pi`, `Aider`, `Amp`, `Gemini`, `Qwen`
+   - Env-file based: `Claude Code`, `Codex CLI`, `OpenHands` (writes `~/.fcm-{tool}-env` — source it before launching)
+3. **Connection Mode** — Choose how the tool connects to the provider:
+   - **⚡ Direct Provider** — pure API connection, no proxy involved
+   - **🔄 FCM Proxy** — route through the local FCM proxy with key rotation and usage tracking
+4. **Scope** — Choose `Install all models` or `Install selected models only`
+5. **Models** (if scope = selected) — Multi-select individual models from the provider catalog
 
 Important behavior:
 
-- Installs are written directly into the target tool config as FCM-managed entries, without going through `fcm-proxy`
+- Installs are written into the target tool config as FCM-managed entries (namespaced under `fcm-*`)
 - `Install all models` is the recommended path because FCM can refresh that catalog automatically on later launches when the provider model list changes
 - `Install selected models only` is useful when you want a smaller curated picker inside the target tool
 - `OpenCode CLI` and `OpenCode Desktop` share the same `opencode.json`, so the managed provider appears in both
+- For env-based tools (Claude Code, Codex, OpenHands), FCM writes a sourceable file at `~/.fcm-{tool}-env` — run `source ~/.fcm-claude-code-env` before launching
 
  **Keyboard shortcuts (Settings screen — `P` key):**
  - **↑↓** — Navigate providers, maintenance row, and profile rows

package/bin/free-coding-models.js

@@ -118,9 +118,9 @@ import { setOpenCodeModelData, startOpenCode, startOpenCodeDesktop, startProxyAn
 import { startOpenClaw } from '../src/openclaw.js'
 import { createOverlayRenderers } from '../src/overlays.js'
 import { createKeyHandler } from '../src/key-handler.js'
-import { getToolModeOrder } from '../src/tool-metadata.js'
+import { getToolModeOrder, getToolMeta } from '../src/tool-metadata.js'
 import { startExternalTool } from '../src/tool-launchers.js'
-import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../src/endpoint-installer.js'
+import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels, CONNECTION_MODES } from '../src/endpoint-installer.js'
 import { loadCache, saveCache, clearCache, getCacheAge } from '../src/cache.js'
 import { checkConfigSecurity } from '../src/security.js'
 
@@ -403,11 +403,12 @@ async function main() {
     helpScrollOffset: 0,          // 📖 Vertical scroll offset for Help overlay viewport
     // 📖 Install Endpoints overlay state (Y key opens it)
     installEndpointsOpen: false,  // 📖 Whether the install-endpoints overlay is active
-    installEndpointsPhase: 'providers', // 📖 providers | tools | scope | models | result
+    installEndpointsPhase: 'providers', // 📖 providers | tools | connection | scope | models | result
     installEndpointsCursor: 0,    // 📖 Selected row within the current install phase
     installEndpointsScrollOffset: 0, // 📖 Vertical scroll offset for the install overlay viewport
     installEndpointsProviderKey: null, // 📖 Selected provider for endpoint installation
     installEndpointsToolMode: null, // 📖 Selected target tool mode
+    installEndpointsConnectionMode: null, // 📖 'direct' | 'proxy' — how the tool connects to the provider
     installEndpointsScope: null,  // 📖 all | selected
     installEndpointsSelectedModelIds: new Set(), // 📖 Multi-select buffer for the selected-models phase
     installEndpointsErrorMsg: null, // 📖 Temporary validation/error message inside the install flow
@@ -687,6 +688,8 @@ async function main() {
     getConfiguredInstallableProviders,
     getInstallTargetModes,
     getProviderCatalogModels,
+    CONNECTION_MODES,
+    getToolMeta,
   })
 
   onKeyPress = createKeyHandler({
@@ -711,6 +714,7 @@ async function main() {
     getInstallTargetModes,
     getProviderCatalogModels,
     installProviderEndpoints,
+    CONNECTION_MODES,
     syncFavoriteFlags,
     toggleFavoriteModel,
     sortResultsWithPinnedFavorites,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.2.15",
+  "version": "0.2.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/endpoint-installer.js

@@ -13,11 +13,21 @@
  *   - it merges into existing config files instead of replacing them
  *   - it records successful installs in `~/.free-coding-models.json` so catalogs can be refreshed automatically later
  *
+ *   📖 Connection modes:
+ *   - `direct` — connect the tool straight to the provider API endpoint (no proxy)
+ *   - `proxy` — route through the local FCM proxy (key rotation + usage tracking)
+ *
  *   📖 Tool-specific notes:
  *   - OpenCode CLI and OpenCode Desktop share the same `opencode.json`
  *   - Crush gets a managed provider block in `crush.json`
  *   - Goose gets a declarative custom provider JSON + a matching secret in `secrets.yaml`
  *   - OpenClaw gets a managed `models.providers` entry plus matching allowlist rows
+ *   - Pi gets models.json + settings.json under ~/.pi/agent/
+ *   - Aider gets ~/.aider.conf.yml with OpenAI-compatible config
+ *   - Amp gets ~/.config/amp/settings.json
+ *   - Gemini gets ~/.gemini/settings.json
+ *   - Qwen gets ~/.qwen/settings.json with modelProviders
+ *   - Claude Code, Codex, OpenHands get a sourceable env file (~/.fcm-{tool}-env)
  *
  * @functions
  *   → `getConfiguredInstallableProviders` — list configured providers that support direct endpoint installs
@@ -44,7 +54,14 @@ import { ENV_VAR_NAMES, PROVIDER_METADATA } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
 
 const DIRECT_INSTALL_UNSUPPORTED_PROVIDERS = new Set(['replicate', 'zai'])
-const INSTALL_TARGET_MODES = ['opencode', 'opencode-desktop', 'openclaw', 'crush', 'goose']
+// 📖 All supported install targets — matches TOOL_MODE_ORDER in tool-metadata.js
+const INSTALL_TARGET_MODES = ['opencode', 'opencode-desktop', 'openclaw', 'crush', 'goose', 'pi', 'aider', 'claude-code', 'codex', 'gemini', 'qwen', 'openhands', 'amp']
+
+// 📖 Connection modes: direct (pure provider) vs FCM proxy (rotates keys)
+export const CONNECTION_MODES = [
+  { key: 'direct', label: 'Direct Provider', hint: 'Connect the tool straight to the provider API — no proxy involved.' },
+  { key: 'proxy', label: 'FCM Proxy', hint: 'Route through the local FCM proxy with key rotation and usage tracking.' },
+]
 
 function getDefaultPaths() {
   const home = homedir()
@@ -54,6 +71,12 @@ function getDefaultPaths() {
     crushConfigPath: join(home, '.config', 'crush', 'crush.json'),
     gooseProvidersDir: join(home, '.config', 'goose', 'custom_providers'),
     gooseSecretsPath: join(home, '.config', 'goose', 'secrets.yaml'),
+    piModelsPath: join(home, '.pi', 'agent', 'models.json'),
+    piSettingsPath: join(home, '.pi', 'agent', 'settings.json'),
+    aiderConfigPath: join(home, '.aider.conf.yml'),
+    ampConfigPath: join(home, '.config', 'amp', 'settings.json'),
+    geminiConfigPath: join(home, '.gemini', 'settings.json'),
+    qwenConfigPath: join(home, '.qwen', 'settings.json'),
   }
 }
 
@@ -374,8 +397,131 @@ function installIntoOpenClaw(providerKey, models, apiKey, paths) {
   return { path: filePath, backupPath, providerId, modelCount: models.length }
 }
 
+// 📖 installIntoPi writes models.json + settings.json under ~/.pi/agent/
+function installIntoPi(providerKey, models, apiKey, paths) {
+  const providerId = getManagedProviderId(providerKey)
+  const baseUrl = resolveProviderBaseUrl(providerKey)
+
+  // 📖 Write models.json with provider config
+  const modelsConfig = readJson(paths.piModelsPath, { providers: {} })
+  if (!modelsConfig.providers || typeof modelsConfig.providers !== 'object') modelsConfig.providers = {}
+  modelsConfig.providers[providerId] = {
+    baseUrl,
+    api: 'openai-completions',
+    apiKey,
+    models: models.map((model) => ({ id: model.modelId, name: model.label })),
+  }
+  const modelsBackupPath = writeJson(paths.piModelsPath, modelsConfig)
+
+  // 📖 Write settings.json to set default provider
+  const settingsConfig = readJson(paths.piSettingsPath, {})
+  settingsConfig.defaultProvider = providerId
+  settingsConfig.defaultModel = models[0]?.modelId ?? ''
+  writeJson(paths.piSettingsPath, settingsConfig, { backup: true })
+
+  return { path: paths.piModelsPath, backupPath: modelsBackupPath, providerId, modelCount: models.length }
+}
+
+// 📖 installIntoAider writes ~/.aider.conf.yml with OpenAI-compatible config
+function installIntoAider(providerKey, models, apiKey, paths) {
+  const providerId = getManagedProviderId(providerKey)
+  const baseUrl = resolveProviderBaseUrl(providerKey)
+  const backupPath = backupIfExists(paths.aiderConfigPath)
+  // 📖 Aider YAML config — one model at a time, uses first selected model
+  const primaryModel = models[0]
+  const lines = [
+    '# 📖 Managed by free-coding-models',
+    `openai-api-base: ${baseUrl}`,
+    `openai-api-key: ${apiKey}`,
+    `model: openai/${primaryModel.modelId}`,
+    '',
+  ]
+  ensureDirFor(paths.aiderConfigPath)
+  writeFileSync(paths.aiderConfigPath, lines.join('\n'))
+  return { path: paths.aiderConfigPath, backupPath, providerId, modelCount: models.length }
+}
+
+// 📖 installIntoAmp writes ~/.config/amp/settings.json with model+URL
+function installIntoAmp(providerKey, models, apiKey, paths) {
+  const providerId = getManagedProviderId(providerKey)
+  const baseUrl = resolveProviderBaseUrl(providerKey)
+  const config = readJson(paths.ampConfigPath, {})
+  config['amp.url'] = baseUrl
+  config['amp.model'] = models[0]?.modelId ?? ''
+  const backupPath = writeJson(paths.ampConfigPath, config)
+  return { path: paths.ampConfigPath, backupPath, providerId, modelCount: models.length }
+}
+
+// 📖 installIntoGemini writes ~/.gemini/settings.json with model ID
+function installIntoGemini(providerKey, models, apiKey, paths) {
+  const providerId = getManagedProviderId(providerKey)
+  const config = readJson(paths.geminiConfigPath, {})
+  config.model = models[0]?.modelId ?? ''
+  const backupPath = writeJson(paths.geminiConfigPath, config)
+  return { path: paths.geminiConfigPath, backupPath, providerId, modelCount: models.length }
+}
+
+// 📖 installIntoQwen writes ~/.qwen/settings.json with modelProviders config
+function installIntoQwen(providerKey, models, apiKey, paths) {
+  const providerId = getManagedProviderId(providerKey)
+  const baseUrl = resolveProviderBaseUrl(providerKey)
+  const config = readJson(paths.qwenConfigPath, {})
+  if (!config.modelProviders || typeof config.modelProviders !== 'object') config.modelProviders = {}
+  if (!Array.isArray(config.modelProviders.openai)) config.modelProviders.openai = []
+
+  // 📖 Remove existing FCM-managed entries, then prepend all selected models
+  const filtered = config.modelProviders.openai.filter(
+    (entry) => !models.some((m) => m.modelId === entry?.id)
+  )
+  const newEntries = models.map((model) => ({
+    id: model.modelId,
+    name: model.label,
+    envKey: ENV_VAR_NAMES[providerKey] || 'OPENAI_API_KEY',
+    baseUrl,
+  }))
+  config.modelProviders.openai = [...newEntries, ...filtered]
+  config.model = models[0]?.modelId ?? ''
+  const backupPath = writeJson(paths.qwenConfigPath, config)
+  return { path: paths.qwenConfigPath, backupPath, providerId, modelCount: models.length }
+}
+
+// 📖 installIntoEnvBasedTool handles tools that rely on env vars only (claude-code, codex, openhands).
+// 📖 We write a small .env-style helper file so users can source it before launching.
+function installIntoEnvBasedTool(providerKey, models, apiKey, toolMode, paths) {
+  const providerId = getManagedProviderId(providerKey)
+  const baseUrl = resolveProviderBaseUrl(providerKey)
+  const home = homedir()
+  const envFileName = `.fcm-${toolMode}-env`
+  const envFilePath = join(home, envFileName)
+
+  const primaryModel = models[0]
+  const envLines = [
+    '# 📖 Managed by free-coding-models — source this file before launching the tool',
+    `# 📖 Provider: ${getProviderLabel(providerKey)} (${models.length} models)`,
+    `export OPENAI_API_KEY="${apiKey}"`,
+    `export OPENAI_BASE_URL="${baseUrl}"`,
+    `export OPENAI_MODEL="${primaryModel.modelId}"`,
+    `export LLM_API_KEY="${apiKey}"`,
+    `export LLM_BASE_URL="${baseUrl}"`,
+    `export LLM_MODEL="openai/${primaryModel.modelId}"`,
+  ]
+
+  // 📖 Tool-specific extra env vars
+  if (toolMode === 'claude-code') {
+    envLines.push(`export ANTHROPIC_AUTH_TOKEN="${apiKey}"`)
+    envLines.push(`export ANTHROPIC_BASE_URL="${baseUrl}"`)
+    envLines.push(`export ANTHROPIC_MODEL="${primaryModel.modelId}"`)
+  }
+
+  ensureDirFor(envFilePath)
+  const backupPath = backupIfExists(envFilePath)
+  writeFileSync(envFilePath, envLines.join('\n') + '\n')
+  return { path: envFilePath, backupPath, providerId, modelCount: models.length }
+}
+
 export function installProviderEndpoints(config, providerKey, toolMode, options = {}) {
   const canonicalToolMode = canonicalizeToolMode(toolMode)
+  const connectionMode = options.connectionMode || 'direct'
   const support = getDirectInstallSupport(providerKey)
   if (!support.supported) {
     throw new Error(support.reason || 'Direct install is not supported for this provider')
@@ -389,6 +535,7 @@ export function installProviderEndpoints(config, providerKey, toolMode, options
   }
 
   const paths = { ...getDefaultPaths(), ...(options.paths || {}) }
+  // 📖 Dispatch to the right installer based on canonical tool mode
   let installResult
   if (canonicalToolMode === 'opencode') {
     installResult = installIntoOpenCode(providerKey, models, apiKey, paths)
@@ -398,6 +545,18 @@ export function installProviderEndpoints(config, providerKey, toolMode, options
     installResult = installIntoCrush(providerKey, models, apiKey, paths)
   } else if (canonicalToolMode === 'goose') {
     installResult = installIntoGoose(providerKey, models, apiKey, paths)
+  } else if (canonicalToolMode === 'pi') {
+    installResult = installIntoPi(providerKey, models, apiKey, paths)
+  } else if (canonicalToolMode === 'aider') {
+    installResult = installIntoAider(providerKey, models, apiKey, paths)
+  } else if (canonicalToolMode === 'amp') {
+    installResult = installIntoAmp(providerKey, models, apiKey, paths)
+  } else if (canonicalToolMode === 'gemini') {
+    installResult = installIntoGemini(providerKey, models, apiKey, paths)
+  } else if (canonicalToolMode === 'qwen') {
+    installResult = installIntoQwen(providerKey, models, apiKey, paths)
+  } else if (canonicalToolMode === 'claude-code' || canonicalToolMode === 'codex' || canonicalToolMode === 'openhands') {
+    installResult = installIntoEnvBasedTool(providerKey, models, apiKey, canonicalToolMode, paths)
   } else {
     throw new Error(`Unsupported install target: ${toolMode}`)
   }
@@ -414,6 +573,7 @@ export function installProviderEndpoints(config, providerKey, toolMode, options
     providerKey,
     providerLabel: getProviderLabel(providerKey),
     scope,
+    connectionMode,
     autoRefreshEnabled: true,
     models,
   }

package/src/key-handler.js

@@ -169,6 +169,7 @@ export function createKeyHandler(ctx) {
     getInstallTargetModes,
     getProviderCatalogModels,
     installProviderEndpoints,
+    CONNECTION_MODES,
     syncFavoriteFlags,
     toggleFavoriteModel,
     sortResultsWithPinnedFavorites,
@@ -334,6 +335,7 @@ export function createKeyHandler(ctx) {
     state.installEndpointsScrollOffset = 0
     state.installEndpointsProviderKey = null
     state.installEndpointsToolMode = null
+    state.installEndpointsConnectionMode = null
     state.installEndpointsScope = null
     state.installEndpointsSelectedModelIds = new Set()
     state.installEndpointsErrorMsg = null
@@ -349,6 +351,7 @@ export function createKeyHandler(ctx) {
       {
         scope: state.installEndpointsScope,
         modelIds: selectedModelIds,
+        connectionMode: state.installEndpointsConnectionMode || 'direct',
       }
     )
 
@@ -414,12 +417,13 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    // 📖 Install Endpoints overlay: provider → tool → scope → optional model subset.
+    // 📖 Install Endpoints overlay: provider → tool → connection → scope → optional model subset.
     if (state.installEndpointsOpen) {
       if (key.ctrl && key.name === 'c') { exit(0); return }
 
       const providerChoices = getConfiguredInstallableProviders(state.config)
       const toolChoices = getInstallTargetModes()
+      const connectionChoices = CONNECTION_MODES || []
       const modelChoices = state.installEndpointsProviderKey
         ? getProviderCatalogModels(state.installEndpointsProviderKey)
         : []
@@ -428,6 +432,7 @@ export function createKeyHandler(ctx) {
       const maxIndexByPhase = () => {
         if (state.installEndpointsPhase === 'providers') return Math.max(0, providerChoices.length - 1)
         if (state.installEndpointsPhase === 'tools') return Math.max(0, toolChoices.length - 1)
+        if (state.installEndpointsPhase === 'connection') return Math.max(0, connectionChoices.length - 1)
         if (state.installEndpointsPhase === 'scope') return 1
         if (state.installEndpointsPhase === 'models') return Math.max(0, modelChoices.length - 1)
         return 0
@@ -470,12 +475,18 @@ export function createKeyHandler(ctx) {
           state.installEndpointsScrollOffset = 0
           return
         }
-        if (state.installEndpointsPhase === 'scope') {
+        if (state.installEndpointsPhase === 'connection') {
           state.installEndpointsPhase = 'tools'
           state.installEndpointsCursor = 0
           state.installEndpointsScrollOffset = 0
           return
         }
+        if (state.installEndpointsPhase === 'scope') {
+          state.installEndpointsPhase = 'connection'
+          state.installEndpointsCursor = state.installEndpointsConnectionMode === 'proxy' ? 1 : 0
+          state.installEndpointsScrollOffset = 0
+          return
+        }
         if (state.installEndpointsPhase === 'models') {
           state.installEndpointsPhase = 'scope'
           state.installEndpointsCursor = state.installEndpointsScope === 'selected' ? 1 : 0
@@ -508,6 +519,20 @@ export function createKeyHandler(ctx) {
           const selectedToolMode = toolChoices[state.installEndpointsCursor]
           if (!selectedToolMode) return
           state.installEndpointsToolMode = selectedToolMode
+          state.installEndpointsPhase = 'connection'
+          state.installEndpointsCursor = 0
+          state.installEndpointsScrollOffset = 0
+          state.installEndpointsErrorMsg = null
+        }
+        return
+      }
+
+      // 📖 Connection mode phase: Direct Provider vs FCM Proxy
+      if (state.installEndpointsPhase === 'connection') {
+        if (key.name === 'return') {
+          const selected = connectionChoices[state.installEndpointsCursor]
+          if (!selected) return
+          state.installEndpointsConnectionMode = selected.key
           state.installEndpointsPhase = 'scope'
           state.installEndpointsCursor = 0
           state.installEndpointsScrollOffset = 0
@@ -1395,6 +1420,7 @@ export function createKeyHandler(ctx) {
       state.installEndpointsScrollOffset = 0
       state.installEndpointsProviderKey = null
       state.installEndpointsToolMode = null
+      state.installEndpointsConnectionMode = null
       state.installEndpointsScope = null
       state.installEndpointsSelectedModelIds = new Set()
       state.installEndpointsErrorMsg = null

package/src/overlays.js

@@ -55,6 +55,8 @@ export function createOverlayRenderers(state, deps) {
     getConfiguredInstallableProviders,
     getInstallTargetModes,
     getProviderCatalogModels,
+    CONNECTION_MODES,
+    getToolMeta,
   } = deps
 
   // 📖 Wrap plain diagnostic text so long Settings messages stay readable inside
@@ -377,7 +379,7 @@ export function createOverlayRenderers(state, deps) {
   }
 
   // ─── Install Endpoints overlay renderer ───────────────────────────────────
-  // 📖 renderInstallEndpoints drives the provider → tool → scope → model flow
+  // 📖 renderInstallEndpoints drives the provider → tool → connection → scope → model flow
   // 📖 behind the `Y` hotkey. It deliberately reuses the same overlay viewport
   // 📖 helpers as Settings so long provider/model lists stay navigable.
   function renderInstallEndpoints() {
@@ -386,6 +388,8 @@ export function createOverlayRenderers(state, deps) {
     const cursorLineByRow = {}
     const providerChoices = getConfiguredInstallableProviders(state.config)
     const toolChoices = getInstallTargetModes()
+    const connectionChoices = CONNECTION_MODES || []
+    const totalSteps = 5
     const scopeChoices = [
       {
         key: 'all',
@@ -401,18 +405,22 @@ export function createOverlayRenderers(state, deps) {
     const selectedProviderLabel = state.installEndpointsProviderKey
       ? (sources[state.installEndpointsProviderKey]?.name || state.installEndpointsProviderKey)
       : '—'
+
+    // 📖 Resolve tool label from metadata instead of hard-coded switch
     const selectedToolLabel = state.installEndpointsToolMode
-      ? (state.installEndpointsToolMode === 'opencode-desktop'
-          ? 'OpenCode Desktop (shared opencode.json)'
-          : (state.installEndpointsToolMode === 'opencode'
-              ? 'OpenCode CLI (shared opencode.json)'
-              : state.installEndpointsToolMode === 'openclaw'
-                ? 'OpenClaw'
-                : state.installEndpointsToolMode === 'crush'
-                  ? 'Crush'
-                  : 'Goose'))
+      ? (() => {
+          const meta = getToolMeta(state.installEndpointsToolMode)
+          const suffix = state.installEndpointsToolMode.startsWith('opencode') ? ' (shared opencode.json)' : ''
+          return `${meta.label}${suffix}`
+        })()
       : '—'
 
+    const selectedConnectionLabel = state.installEndpointsConnectionMode === 'proxy'
+      ? 'FCM Proxy'
+      : state.installEndpointsConnectionMode === 'direct'
+        ? 'Direct Provider'
+        : '—'
+
     lines.push('')
     // 📖 Branding header
     lines.push(`  ${chalk.cyanBright('🚀')} ${chalk.bold.cyanBright('free-coding-models')} ${chalk.dim(`v${LOCAL_VERSION}`)}`)
@@ -425,7 +433,7 @@ export function createOverlayRenderers(state, deps) {
     lines.push('')
 
     if (state.installEndpointsPhase === 'providers') {
-      lines.push(`  ${chalk.bold('Step 1/4')}  ${chalk.cyan('Choose a configured provider')}`)
+      lines.push(`  ${chalk.bold(`Step 1/${totalSteps}`)}  ${chalk.cyan('Choose a configured provider')}`)
       lines.push('')
 
       if (providerChoices.length === 0) {
@@ -435,7 +443,7 @@ export function createOverlayRenderers(state, deps) {
         providerChoices.forEach((provider, idx) => {
           const isCursor = idx === state.installEndpointsCursor
           const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
-          const row = `${bullet}${chalk.bold(provider.label.padEnd(24))} ${chalk.dim(`${provider.modelCount} models`)}` 
+          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)
         })
@@ -444,37 +452,51 @@ export function createOverlayRenderers(state, deps) {
       lines.push('')
       lines.push(chalk.dim('  ↑↓ Navigate  •  Enter Choose provider  •  Esc Close'))
     } else if (state.installEndpointsPhase === 'tools') {
-      lines.push(`  ${chalk.bold('Step 2/4')}  ${chalk.cyan('Choose the target tool')}`)
+      lines.push(`  ${chalk.bold(`Step 2/${totalSteps}`)}  ${chalk.cyan('Choose the target tool')}`)
       lines.push(chalk.dim(`  Provider: ${selectedProviderLabel}`))
       lines.push('')
 
+      // 📖 Use getToolMeta for labels instead of hard-coded ternary chains
       toolChoices.forEach((toolMode, idx) => {
         const isCursor = idx === state.installEndpointsCursor
-        const label = toolMode === 'opencode-desktop'
-          ? 'OpenCode Desktop'
-          : toolMode === 'opencode'
-            ? 'OpenCode CLI'
-            : toolMode === 'openclaw'
-              ? 'OpenClaw'
-              : toolMode === 'crush'
-                ? 'Crush'
-                : 'Goose'
+        const meta = getToolMeta(toolMode)
+        const label = `${meta.emoji} ${meta.label}`
         const note = toolMode.startsWith('opencode')
           ? chalk.dim('shared config file')
-          : chalk.dim('managed provider install')
+          : ['claude-code', 'codex', 'openhands'].includes(toolMode)
+            ? chalk.dim('env file (~/.fcm-*-env)')
+            : chalk.dim('managed config install')
         const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
-        const row = `${bullet}${chalk.bold(label.padEnd(22))} ${note}`
+        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('')
       lines.push(chalk.dim('  ↑↓ Navigate  •  Enter Choose tool  •  Esc Back'))
-    } else if (state.installEndpointsPhase === 'scope') {
-      lines.push(`  ${chalk.bold('Step 3/4')}  ${chalk.cyan('Choose the install scope')}`)
+    } else if (state.installEndpointsPhase === 'connection') {
+      // 📖 Step 3: Choose connection mode — Direct Provider vs FCM Proxy
+      lines.push(`  ${chalk.bold(`Step 3/${totalSteps}`)}  ${chalk.cyan('Choose connection mode')}`)
       lines.push(chalk.dim(`  Provider: ${selectedProviderLabel}  •  Tool: ${selectedToolLabel}`))
       lines.push('')
 
+      connectionChoices.forEach((mode, idx) => {
+        const isCursor = idx === state.installEndpointsCursor
+        const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+        const icon = mode.key === 'proxy' ? '🔄' : '⚡'
+        const row = `${bullet}${icon} ${chalk.bold(mode.label)}`
+        cursorLineByRow[idx] = lines.length
+        lines.push(isCursor ? chalk.bgRgb(24, 44, 62)(row) : row)
+        lines.push(chalk.dim(`      ${mode.hint}`))
+        lines.push('')
+      })
+
+      lines.push(chalk.dim('  Enter Continue  •  Esc Back'))
+    } else if (state.installEndpointsPhase === 'scope') {
+      lines.push(`  ${chalk.bold(`Step 4/${totalSteps}`)}  ${chalk.cyan('Choose the install scope')}`)
+      lines.push(chalk.dim(`  Provider: ${selectedProviderLabel}  •  Tool: ${selectedToolLabel}  •  ${selectedConnectionLabel}`))
+      lines.push('')
+
       scopeChoices.forEach((scope, idx) => {
         const isCursor = idx === state.installEndpointsCursor
         const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
@@ -490,8 +512,8 @@ export function createOverlayRenderers(state, deps) {
       const models = getProviderCatalogModels(state.installEndpointsProviderKey)
       const selectedCount = state.installEndpointsSelectedModelIds.size
 
-      lines.push(`  ${chalk.bold('Step 4/4')}  ${chalk.cyan('Choose which models to install')}`)
-      lines.push(chalk.dim(`  Provider: ${selectedProviderLabel}  •  Tool: ${selectedToolLabel}`))
+      lines.push(`  ${chalk.bold(`Step 5/${totalSteps}`)}  ${chalk.cyan('Choose which models to install')}`)
+      lines.push(chalk.dim(`  Provider: ${selectedProviderLabel}  •  Tool: ${selectedToolLabel}  •  ${selectedConnectionLabel}`))
       lines.push(chalk.dim(`  Selected: ${selectedCount}/${models.length}`))
       lines.push('')
 
@@ -608,9 +630,9 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${chalk.yellow('W')}  Toggle ping mode  ${chalk.dim('(speed 2s → normal 10s → slow 30s → forced 4s)')}`)
     lines.push(`  ${chalk.yellow('E')}  Toggle configured models only  ${chalk.dim('(enabled by default, persisted globally + in profiles)')}`)
     lines.push(`  ${chalk.yellow('X')}  Toggle token log page  ${chalk.dim('(shows recent request usage from request-log.jsonl)')}`)
-    lines.push(`  ${chalk.yellow('Z')}  Cycle tool mode  ${chalk.dim('(OpenCode → Desktop → OpenClaw → Crush → Goose)')}`)
+    lines.push(`  ${chalk.yellow('Z')}  Cycle tool mode  ${chalk.dim('(OpenCode → Desktop → OpenClaw → Crush → Goose → Pi → Aider → Claude Code → Codex → Gemini → Qwen → OpenHands → Amp)')}`)
     lines.push(`  ${chalk.yellow('F')}  Toggle favorite on selected row  ${chalk.dim('(⭐ pinned at top, persisted)')}`)
-    lines.push(`  ${chalk.yellow('Y')}  Install endpoints  ${chalk.dim('(provider catalog → OpenCode/OpenClaw/Crush/Goose, no proxy)')}`)
+    lines.push(`  ${chalk.yellow('Y')}  Install endpoints  ${chalk.dim('(provider catalog → all tools, Direct or FCM Proxy)')}`)
     lines.push(`  ${chalk.yellow('Q')}  Smart Recommend  ${chalk.dim('(🎯 find the best model for your task — questionnaire + live analysis)')}`)
     lines.push(`  ${chalk.rgb(57, 255, 20).bold('J')}  Request Feature  ${chalk.dim('(📝 send anonymous feedback to the project team)')}`)
     lines.push(`  ${chalk.rgb(255, 87, 51).bold('I')}  Report Bug  ${chalk.dim('(🐛 send anonymous bug report to the project team)')}`)
@@ -641,15 +663,14 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${chalk.cyan('free-coding-models --openclaw')}           ${chalk.dim('OpenClaw mode')}`)
     lines.push(`  ${chalk.cyan('free-coding-models --crush')}              ${chalk.dim('Crush mode')}`)
     lines.push(`  ${chalk.cyan('free-coding-models --goose')}              ${chalk.dim('Goose mode')}`)
-    // 📖 Temporarily disabled launchers kept out of the public help until their flows are hardened.
-    // lines.push(`  ${chalk.cyan('free-coding-models --aider')}              ${chalk.dim('Aider mode')}`)
-    // lines.push(`  ${chalk.cyan('free-coding-models --claude-code')}        ${chalk.dim('Claude Code proxy mode')}`)
-    // lines.push(`  ${chalk.cyan('free-coding-models --codex')}              ${chalk.dim('Codex CLI proxy mode')}`)
-    // lines.push(`  ${chalk.cyan('free-coding-models --gemini')}             ${chalk.dim('Gemini CLI proxy mode')}`)
-    // lines.push(`  ${chalk.cyan('free-coding-models --qwen')}               ${chalk.dim('Qwen Code mode')}`)
-    // lines.push(`  ${chalk.cyan('free-coding-models --openhands')}          ${chalk.dim('OpenHands mode')}`)
-    // lines.push(`  ${chalk.cyan('free-coding-models --amp')}                ${chalk.dim('Amp mode')}`)
-    // lines.push(`  ${chalk.cyan('free-coding-models --pi')}                 ${chalk.dim('Pi mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --pi')}                 ${chalk.dim('Pi mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --aider')}              ${chalk.dim('Aider mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --claude-code')}        ${chalk.dim('Claude Code mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --codex')}              ${chalk.dim('Codex CLI mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --gemini')}             ${chalk.dim('Gemini CLI mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --qwen')}               ${chalk.dim('Qwen Code mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --openhands')}          ${chalk.dim('OpenHands mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --amp')}                ${chalk.dim('Amp mode')}`)
     lines.push(`  ${chalk.cyan('free-coding-models --best')}               ${chalk.dim('Only top tiers (A+, S, S+)')}`)
     lines.push(`  ${chalk.cyan('free-coding-models --fiable')}             ${chalk.dim('10s reliability analysis')}`)
     lines.push(`  ${chalk.cyan('free-coding-models --tier S|A|B|C')}       ${chalk.dim('Filter by tier letter')}`)
@@ -1290,12 +1311,32 @@ export function createOverlayRenderers(state, deps) {
           if (changes[key]) itemCount += changes[key].length
         }
 
-        // 📖 Format version line with selection highlight
-        const versionStr = `  v${version.padEnd(8)} — ${itemCount} ${itemCount === 1 ? 'change' : 'changes'}`
+        // 📖 Build a short summary from the first few items (max ~15 words, stripped of markdown)
+        const allItems = []
+        for (const k of ['added', 'fixed', 'changed', 'updated']) {
+          if (changes[k]) for (const item of changes[k]) allItems.push(item)
+        }
+        let summary = ''
+        if (allItems.length > 0) {
+          // 📖 Extract the bold title part if present, otherwise use the raw text
+          const firstItem = allItems[0]
+          const boldMatch = firstItem.match(/\*\*([^*]+)\*\*/)
+          const rawText = boldMatch ? boldMatch[1] : firstItem.replace(/\*\*([^*]+)\*\*/g, '$1').replace(/`([^`]+)`/g, '$1')
+          // 📖 Truncate to ~15 words max
+          const words = rawText.split(/\s+/).slice(0, 15)
+          summary = words.join(' ')
+          if (rawText.split(/\s+/).length > 15) summary += '…'
+        }
+
+        // 📖 Format version line with selection highlight + dim summary
+        const countStr = `${itemCount} ${itemCount === 1 ? 'change' : 'changes'}`
+        const prefix = `  v${version.padEnd(8)} — ${countStr}`
         if (isSelected) {
-          lines.push(chalk.inverse(versionStr))
+          const full = summary ? `${prefix} · ${summary}` : prefix
+          lines.push(chalk.inverse(full))
         } else {
-          lines.push(versionStr)
+          const dimSummary = summary ? chalk.dim(` · ${summary}`) : ''
+          lines.push(`${prefix}${dimSummary}`)
         }
       }
 
@@ -1332,6 +1373,17 @@ export function createOverlayRenderers(state, deps) {
       }
     }
 
+    // 📖 Keep selected changelog row visible by scrolling the overlay viewport (index phase)
+    if (state.changelogPhase === 'index') {
+      const targetLine = 4 + state.changelogCursor  // 📖 3 header lines + 1 blank = versions start at line 4
+      state.changelogScrollOffset = keepOverlayTargetVisible(
+        state.changelogScrollOffset,
+        targetLine,
+        lines.length,
+        state.terminalRows
+      )
+    }
+
     // 📖 Use scrolling with overlay handler
     const CHANGELOG_OVERLAY_BG = chalk.bgRgb(10, 40, 80)  // Dark blue background
     const { visible, offset } = sliceOverlayLines(lines, state.changelogScrollOffset, state.terminalRows)

package/src/tool-metadata.js

@@ -29,13 +29,13 @@ export const TOOL_METADATA = {
   crush: { label: 'Crush', emoji: '💘', flag: '--crush' },
   goose: { label: 'Goose', emoji: '🪿', flag: '--goose' },
   pi: { label: 'Pi', emoji: 'π', flag: '--pi' },
-  // aider: { label: 'Aider', emoji: '🛠', flag: '--aider' },
-  // 'claude-code': { label: 'Claude Code', emoji: '🧠', flag: '--claude-code' },
-  // codex: { label: 'Codex CLI', emoji: '⌘', flag: '--codex' },
-  // gemini: { label: 'Gemini CLI', emoji: '✦', flag: '--gemini' },
-  // qwen: { label: 'Qwen Code', emoji: '🌊', flag: '--qwen' },
-  // openhands: { label: 'OpenHands', emoji: '🤲', flag: '--openhands' },
-  // amp: { label: 'Amp', emoji: '⚡', flag: '--amp' },
+  aider: { label: 'Aider', emoji: '🛠', flag: '--aider' },
+  'claude-code': { label: 'Claude Code', emoji: '🧠', flag: '--claude-code' },
+  codex: { label: 'Codex CLI', emoji: '⌘', flag: '--codex' },
+  gemini: { label: 'Gemini CLI', emoji: '✦', flag: '--gemini' },
+  qwen: { label: 'Qwen Code', emoji: '🌊', flag: '--qwen' },
+  openhands: { label: 'OpenHands', emoji: '🤲', flag: '--openhands' },
+  amp: { label: 'Amp', emoji: '⚡', flag: '--amp' },
 }
 
 export const TOOL_MODE_ORDER = [
@@ -45,13 +45,13 @@ export const TOOL_MODE_ORDER = [
   'crush',
   'goose',
   'pi',
-  // 'aider',
-  // 'claude-code',
-  // 'codex',
-  // 'gemini',
-  // 'qwen',
-  // 'openhands',
-  // 'amp',
+  'aider',
+  'claude-code',
+  'codex',
+  'gemini',
+  'qwen',
+  'openhands',
+  'amp',
 ]
 
 export function getToolMeta(mode) {