free-coding-models 0.1.87 → 0.2.0

package/src/render-table.js

@@ -39,6 +39,18 @@ import { getAvg, getVerdict, getUptime, getStabilityScore } from './utils.js'
 import { usagePlaceholderForProvider } from './ping.js'
 import { formatTokenTotalCompact } from './token-usage-reader.js'
 import { calculateViewport, sortResultsWithPinnedFavorites, renderProxyStatusLine, padEndDisplay } from './render-helpers.js'
+import { getToolMeta } from './tool-metadata.js'
+
+const ACTIVE_FILTER_BG_BY_TIER = {
+  'S+': [57, 255, 20],
+  'S': [57, 255, 20],
+  'A+': [160, 255, 60],
+  'A': [255, 224, 130],
+  'A-': [255, 204, 128],
+  'B+': [255, 171, 64],
+  'B': [239, 83, 80],
+  'C': [186, 104, 200],
+}
 
 const require = createRequire(import.meta.url)
 const { version: LOCAL_VERSION } = require('../package.json')
@@ -77,7 +89,7 @@ export function setActiveProxy(proxyInstance) {
 }
 
 // ─── renderTable: mode param controls footer hint text (opencode vs openclaw) ─────────
-export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false) {
+export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false) {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
 
@@ -119,20 +131,21 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
 
   // 📖 Tool badge keeps the active launch target visible in the header, so the
   // 📖 footer no longer needs a redundant Enter action or mode toggle reminder.
-  let modeBadge
-  if (mode === 'openclaw') {
-    modeBadge = chalk.bold.rgb(255, 100, 50)(' [ ') + chalk.yellow.bold('Z') + chalk.bold.rgb(255, 100, 50)(' Tool : OpenClaw ]')
-  } else if (mode === 'opencode-desktop') {
-    modeBadge = chalk.bold.rgb(0, 200, 255)(' [ ') + chalk.yellow.bold('Z') + chalk.bold.rgb(0, 200, 255)(' Tool : OpenCode Desktop ]')
-  } else {
-    modeBadge = chalk.bold.rgb(0, 200, 255)(' [ ') + chalk.yellow.bold('Z') + chalk.bold.rgb(0, 200, 255)(' Tool : OpenCode CLI ]')
-  }
+  const toolMeta = getToolMeta(mode)
+  const toolBadgeColor = mode === 'openclaw'
+    ? chalk.bold.rgb(255, 100, 50)
+    : chalk.bold.rgb(0, 200, 255)
+  const modeBadge = toolBadgeColor(' [ ') + chalk.yellow.bold('Z') + toolBadgeColor(` Tool : ${toolMeta.label} ]`)
+  const activeHeaderBadge = (text, bg = [57, 255, 20], fg = [0, 0, 0]) => chalk.bgRgb(...bg).rgb(...fg).bold(` ${text} `)
 
   // 📖 Tier filter badge shown when filtering is active (shows exact tier name)
   const TIER_CYCLE_NAMES = [null, 'S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C']
   let tierBadge = ''
+  let activeTierLabel = ''
   if (tierFilterMode > 0) {
-    tierBadge = chalk.bold.rgb(255, 200, 0)(` [${TIER_CYCLE_NAMES[tierFilterMode]}]`)
+    activeTierLabel = TIER_CYCLE_NAMES[tierFilterMode]
+    const tierBg = ACTIVE_FILTER_BG_BY_TIER[activeTierLabel] || [57, 255, 20]
+    tierBadge = ` ${activeHeaderBadge(`TIER (${activeTierLabel})`, tierBg)}`
   }
 
   const normalizeOriginLabel = (name, key) => {
@@ -142,15 +155,23 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
 
   // 📖 Origin filter badge — shown when filtering by provider is active
   let originBadge = ''
+  let activeOriginLabel = ''
   if (originFilterMode > 0) {
     const originKeys = [null, ...Object.keys(sources)]
     const activeOriginKey = originKeys[originFilterMode]
     const activeOriginName = activeOriginKey ? sources[activeOriginKey]?.name ?? activeOriginKey : null
     if (activeOriginName) {
-      originBadge = chalk.bold.rgb(100, 200, 255)(` [${normalizeOriginLabel(activeOriginName, activeOriginKey)}]`)
+      activeOriginLabel = normalizeOriginLabel(activeOriginName, activeOriginKey)
+      const providerRgb = PROVIDER_COLOR[activeOriginKey] || [255, 255, 255]
+      originBadge = ` ${activeHeaderBadge(`PROVIDER (${activeOriginLabel})`, [0, 0, 0], providerRgb)}`
     }
   }
 
+  let configuredBadge = ''
+  if (hideUnconfiguredModels) {
+    configuredBadge = ` ${activeHeaderBadge('CONFIGURED ONLY')}`
+  }
+
   // 📖 Profile badge — shown when a named profile is active (Shift+P to cycle, Shift+S to save)
   let profileBadge = ''
   if (activeProfile) {
@@ -173,14 +194,27 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
   const W_TOKENS = 7
   const W_USAGE = 7
   const MIN_TABLE_WIDTH = 166
+  const warningDurationMs = 5_000
+  const elapsed = widthWarningStartedAt ? Math.max(0, Date.now() - widthWarningStartedAt) : warningDurationMs
+  const remainingMs = Math.max(0, warningDurationMs - elapsed)
+  const showWidthWarning = terminalCols > 0 && terminalCols < MIN_TABLE_WIDTH && !widthWarningDismissed && remainingMs > 0
 
-  if (terminalCols > 0 && terminalCols < MIN_TABLE_WIDTH) {
+  if (showWidthWarning) {
     const lines = []
-    const blankLines = Math.max(0, Math.floor(((terminalRows || 24) - 3) / 2))
-    const warning = 'Please maximize your terminal for optimal use. The current terminal width is too small for the full table.'
+    const blankLines = Math.max(0, Math.floor(((terminalRows || 24) - 5) / 2))
+    const warning = 'Please maximize your terminal for optimal use.'
+    const warning2 = 'The current terminal is too small.'
+    const warning3 = 'Reduce font size or maximize width of terminal.'
     const padLeft = Math.max(0, Math.floor((terminalCols - warning.length) / 2))
+    const padLeft2 = Math.max(0, Math.floor((terminalCols - warning2.length) / 2))
+    const padLeft3 = Math.max(0, Math.floor((terminalCols - warning3.length) / 2))
     for (let i = 0; i < blankLines; i++) lines.push('')
     lines.push(' '.repeat(padLeft) + chalk.red.bold(warning))
+    lines.push(' '.repeat(padLeft2) + chalk.red(warning2))
+    lines.push(' '.repeat(padLeft3) + chalk.red(warning3))
+    lines.push('')
+    lines.push(' '.repeat(Math.max(0, Math.floor((terminalCols - 34) / 2))) + chalk.yellow(`this message will hide in ${(remainingMs / 1000).toFixed(1)}s`))
+    lines.push(' '.repeat(Math.max(0, Math.floor((terminalCols - 20) / 2))) + chalk.dim('press esc to dismiss'))
     while (terminalRows > 0 && lines.length < terminalRows) lines.push('')
     const EL = '\x1b[K'
     return lines.map(line => line + EL).join('\n')
@@ -190,7 +224,7 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
   const sorted = sortResultsWithPinnedFavorites(visibleResults, sortColumn, sortDirection)
 
   const lines = [
-    `  ${chalk.greenBright.bold(`✅ Free-Coding-Models v${LOCAL_VERSION}`)}${modeBadge}${pingControlBadge}${tierBadge}${originBadge}${profileBadge}${chalk.reset('')}   ` +
+    `  ${chalk.greenBright.bold(`✅ Free-Coding-Models v${LOCAL_VERSION}`)}${modeBadge}${pingControlBadge}${tierBadge}${originBadge}${configuredBadge}${profileBadge}${chalk.reset('')}   ` +
       chalk.greenBright(`✅ ${up}`) + chalk.dim(' up  ') +
       chalk.yellow(`⏳ ${timeout}`) + chalk.dim(' timeout  ') +
       chalk.red(`❌ ${down}`) + chalk.dim(' down  ') +
@@ -576,8 +610,30 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
   // 📖 Footer hints keep only navigation and secondary actions now that the
   // 📖 active tool target is already visible in the header badge.
   const hotkey = (keyLabel, text) => chalk.yellow(keyLabel) + chalk.dim(text)
+  // 📖 Active filter pills use a loud green background so tier/provider/configured-only
+  // 📖 states are obvious even when the user misses the smaller header badges.
+  const activeHotkey = (keyLabel, text, bg = [57, 255, 20], fg = [0, 0, 0]) => chalk.bgRgb(...bg).rgb(...fg)(` ${keyLabel}${text} `)
   // 📖 Line 1: core navigation + filtering shortcuts
-  lines.push(chalk.dim(`  ↑↓ Navigate  •  `) + hotkey('F', ' Toggle Favorite') + chalk.dim(`  •  `) + hotkey('T', ' Tier') + chalk.dim(`  •  `) + hotkey('D', ' Provider') + chalk.dim(`  •  `) + hotkey('E', ' Configured Only') + chalk.dim(`  •  `) + hotkey('X', ' Token Logs') + chalk.dim(`  •  `) + hotkey('P', ' Settings') + chalk.dim(`  •  `) + hotkey('K', ' Help'))
+  lines.push(
+    chalk.dim(`  ↑↓ Navigate  •  `) +
+    hotkey('F', ' Toggle Favorite') +
+    chalk.dim(`  •  `) +
+    (tierFilterMode > 0
+      ? activeHotkey('T', ` Tier (${activeTierLabel})`, ACTIVE_FILTER_BG_BY_TIER[activeTierLabel] || [57, 255, 20])
+      : hotkey('T', ' Tier')) +
+    chalk.dim(`  •  `) +
+    (originFilterMode > 0
+      ? activeHotkey('D', ` Provider (${activeOriginLabel})`, [0, 0, 0], PROVIDER_COLOR[[null, ...Object.keys(sources)][originFilterMode]] || [255, 255, 255])
+      : hotkey('D', ' Provider')) +
+    chalk.dim(`  •  `) +
+    (hideUnconfiguredModels ? activeHotkey('E', ' Configured Only') : hotkey('E', ' Configured Only')) +
+    chalk.dim(`  •  `) +
+    hotkey('X', ' Token Logs') +
+    chalk.dim(`  •  `) +
+    hotkey('P', ' Settings') +
+    chalk.dim(`  •  `) +
+    hotkey('K', ' Help')
+  )
   // 📖 Line 2: profiles, recommend, feature request, bug report, and extended hints — gives visibility to less-obvious features
   lines.push(chalk.dim(`  `) + hotkey('⇧P', ' Cycle profile') + chalk.dim(`  •  `) + hotkey('⇧S', ' Save profile') + chalk.dim(`  •  `) + hotkey('Q', ' Smart Recommend') + chalk.dim(`  •  `) + hotkey('J', ' Request feature') + chalk.dim(`  •  `) + hotkey('I', ' Report bug'))
   // 📖 Proxy status line — always rendered with explicit state (starting/running/failed/stopped)

package/src/token-usage-reader.js

@@ -18,7 +18,7 @@
  * @functions
  *   → `buildProviderModelTokenKey` — creates a stable aggregation key
  *   → `loadTokenUsageByProviderModel` — reads request-log.jsonl and returns total tokens by provider+model
- *   → `formatTokenTotalCompact` — renders totals as integer K / M strings for narrow columns
+ *   → `formatTokenTotalCompact` — renders totals as raw ints or compact K / M strings with 2 decimals
  *
  * @exports buildProviderModelTokenKey, loadTokenUsageByProviderModel, formatTokenTotalCompact
  *
@@ -53,11 +53,11 @@ export function loadTokenUsageByProviderModel({ logFile, limit = 50_000 } = {})
   return totals
 }
 
-// 📖 formatTokenTotalCompact keeps the new column narrow and scannable:
-// 📖 0-999 => raw integer, 1k-999k => Nk, 1m+ => NM, no decimals.
+// 📖 formatTokenTotalCompact keeps token counts readable in both the table and log view:
+// 📖 0-999 => raw integer, 1k-999k => N.NNk, 1m+ => N.NNM.
 export function formatTokenTotalCompact(totalTokens) {
   const safeTotal = Number(totalTokens) || 0
-  if (safeTotal >= 1_000_000) return `${Math.floor(safeTotal / 1_000_000)}M`
-  if (safeTotal >= 1_000) return `${Math.floor(safeTotal / 1_000)}k`
+  if (safeTotal >= 999_500) return `${(safeTotal / 1_000_000).toFixed(2)}M`
+  if (safeTotal >= 1_000) return `${(safeTotal / 1_000).toFixed(2)}k`
   return String(Math.floor(safeTotal))
 }

package/src/tool-launchers.js

@@ -0,0 +1,319 @@
+/**
+ * @file src/tool-launchers.js
+ * @description Auto-configure and launch external coding tools from the selected model row.
+ *
+ * @details
+ *   📖 This module extends the existing "pick a model and press Enter" workflow to
+ *   external CLIs that can consume OpenAI-compatible or provider-specific settings.
+ *
+ *   📖 The design is pragmatic:
+ *   - Write a small managed config file when the tool's config shape is stable enough
+ *   - Always export the runtime environment variables before spawning the tool
+ *   - Keep each launcher isolated so a partial integration does not break others
+ *
+ *   📖 Some tools still have weaker official support for arbitrary custom providers.
+ *   For those, we prefer a transparent warning over pretending the integration is
+ *   fully official. The user still gets a reproducible env/config handoff.
+ *
+ * @functions
+ *   → `startExternalTool` — configure and launch the selected external tool mode
+ *
+ * @exports startExternalTool
+ *
+ * @see src/tool-metadata.js
+ * @see src/provider-metadata.js
+ * @see sources.js
+ */
+
+import chalk from 'chalk'
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import { spawn } from 'child_process'
+import { sources } from '../sources.js'
+import { getApiKey, getProxySettings } from './config.js'
+import { ENV_VAR_NAMES, isWindows } from './provider-metadata.js'
+import { getToolMeta } from './tool-metadata.js'
+import { ensureProxyRunning } from './opencode.js'
+
+function ensureDir(filePath) {
+  const dir = dirname(filePath)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+function backupIfExists(filePath) {
+  if (!existsSync(filePath)) return null
+  const backupPath = `${filePath}.backup-${Date.now()}`
+  copyFileSync(filePath, backupPath)
+  return backupPath
+}
+
+function readJson(filePath, fallback) {
+  if (!existsSync(filePath)) return fallback
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'))
+  } catch {
+    return fallback
+  }
+}
+
+function writeJson(filePath, value) {
+  ensureDir(filePath)
+  writeFileSync(filePath, JSON.stringify(value, null, 2))
+}
+
+function getProviderBaseUrl(providerKey) {
+  const url = sources[providerKey]?.url
+  if (!url) return null
+  return url
+    .replace(/\/chat\/completions$/i, '')
+    .replace(/\/responses$/i, '')
+    .replace(/\/predictions$/i, '')
+}
+
+function buildToolEnv(mode, model, config) {
+  const providerKey = model.providerKey
+  const providerUrl = sources[providerKey]?.url || ''
+  const baseUrl = getProviderBaseUrl(providerKey)
+  const apiKey = getApiKey(config, providerKey)
+  const env = { ...process.env }
+  const providerEnvName = ENV_VAR_NAMES[providerKey]
+  if (providerEnvName && apiKey) env[providerEnvName] = apiKey
+
+  // 📖 OpenAI-compatible defaults reused by multiple CLIs.
+  if (apiKey && baseUrl) {
+    env.OPENAI_API_KEY = apiKey
+    env.OPENAI_BASE_URL = baseUrl
+    env.OPENAI_API_BASE = baseUrl
+    env.OPENAI_MODEL = model.modelId
+    env.LLM_API_KEY = apiKey
+    env.LLM_BASE_URL = baseUrl
+    env.LLM_MODEL = `openai/${model.modelId}`
+  }
+
+  // 📖 Provider-specific envs for tools that expect a different wire format.
+  if (mode === 'claude-code' && apiKey && baseUrl) {
+    env.ANTHROPIC_AUTH_TOKEN = apiKey
+    env.ANTHROPIC_BASE_URL = baseUrl
+    env.ANTHROPIC_MODEL = model.modelId
+  }
+
+  if (mode === 'gemini' && apiKey && baseUrl) {
+    env.GOOGLE_API_KEY = apiKey
+    env.GOOGLE_GEMINI_BASE_URL = baseUrl
+  }
+
+  return { env, apiKey, baseUrl, providerUrl }
+}
+
+function spawnCommand(command, args, env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      shell: isWindows,
+      detached: false,
+      env,
+    })
+
+    child.on('exit', (code) => resolve(code))
+    child.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        console.error(chalk.red(`  X Could not find "${command}" in PATH.`))
+        resolve(1)
+      } else {
+        reject(err)
+      }
+    })
+  })
+}
+
+function writeAiderConfig(model, apiKey, baseUrl) {
+  const filePath = join(homedir(), '.aider.conf.yml')
+  const backupPath = backupIfExists(filePath)
+  const content = [
+    '# 📖 Managed by free-coding-models',
+    `openai-api-base: ${baseUrl}`,
+    `openai-api-key: ${apiKey}`,
+    `model: openai/${model.modelId}`,
+    '',
+  ].join('\n')
+  ensureDir(filePath)
+  writeFileSync(filePath, content)
+  return { filePath, backupPath }
+}
+
+function writeCrushConfig(model, apiKey, baseUrl, providerId) {
+  const filePath = join(homedir(), '.config', 'crush', 'crush.json')
+  const backupPath = backupIfExists(filePath)
+  const config = readJson(filePath, { $schema: 'https://charm.land/crush.json' })
+  if (!config.options || typeof config.options !== 'object') config.options = {}
+  config.options.disable_default_providers = true
+  if (!config.providers || typeof config.providers !== 'object') config.providers = {}
+  config.providers[providerId] = {
+    name: 'Free Coding Models',
+    type: 'openai-compat',
+    base_url: baseUrl,
+    api_key: apiKey,
+    models: [
+      {
+        name: model.label,
+        id: model.modelId,
+      },
+    ],
+  }
+  // 📖 Crush expects structured selected models at config.models.{large,small}.
+  // 📖 Root `crush` reads these defaults in interactive mode, unlike `crush run --model`.
+  config.models = {
+    ...(config.models && typeof config.models === 'object' ? config.models : {}),
+    large: { model: model.modelId, provider: providerId },
+  }
+  writeJson(filePath, config)
+  return { filePath, backupPath }
+}
+
+function writeGeminiConfig(model) {
+  const filePath = join(homedir(), '.gemini', 'settings.json')
+  const backupPath = backupIfExists(filePath)
+  const config = readJson(filePath, {})
+  config.model = model.modelId
+  writeJson(filePath, config)
+  return { filePath, backupPath }
+}
+
+function writeQwenConfig(model, providerKey, apiKey, baseUrl) {
+  const filePath = join(homedir(), '.qwen', 'settings.json')
+  const backupPath = backupIfExists(filePath)
+  const config = readJson(filePath, {})
+  if (!config.modelProviders || typeof config.modelProviders !== 'object') config.modelProviders = {}
+  if (!Array.isArray(config.modelProviders.openai)) config.modelProviders.openai = []
+  const nextEntry = {
+    id: model.modelId,
+    name: model.label,
+    envKey: ENV_VAR_NAMES[providerKey] || 'OPENAI_API_KEY',
+    baseUrl,
+  }
+  const filtered = config.modelProviders.openai.filter((entry) => entry?.id !== model.modelId)
+  filtered.unshift(nextEntry)
+  config.modelProviders.openai = filtered
+  config.model = model.modelId
+  writeJson(filePath, config)
+  return { filePath, backupPath, envKey: nextEntry.envKey, apiKey }
+}
+
+function writePiConfig(model, apiKey, baseUrl) {
+  const filePath = join(homedir(), '.pi', 'agent', 'models.json')
+  const backupPath = backupIfExists(filePath)
+  const config = readJson(filePath, { providers: {} })
+  if (!config.providers || typeof config.providers !== 'object') config.providers = {}
+  config.providers.freeCodingModels = {
+    baseUrl,
+    api: 'openai-completions',
+    apiKey,
+    models: [{ id: model.modelId, name: model.label }],
+  }
+  writeJson(filePath, config)
+  return { filePath, backupPath }
+}
+
+function writeAmpConfig(baseUrl) {
+  const filePath = join(homedir(), '.config', 'amp', 'settings.json')
+  const backupPath = backupIfExists(filePath)
+  const config = readJson(filePath, {})
+  config['amp.url'] = baseUrl
+  writeJson(filePath, config)
+  return { filePath, backupPath }
+}
+
+function printConfigResult(toolName, result) {
+  if (!result?.filePath) return
+  console.log(chalk.dim(`  📄 ${toolName} config updated: ${result.filePath}`))
+  if (result.backupPath) console.log(chalk.dim(`  💾 Backup: ${result.backupPath}`))
+}
+
+export async function startExternalTool(mode, model, config) {
+  const meta = getToolMeta(mode)
+  const { env, apiKey, baseUrl } = buildToolEnv(mode, model, config)
+
+  if (!apiKey && mode !== 'amp') {
+    console.log(chalk.yellow(`  ⚠ No API key configured for ${model.providerKey}.`))
+    console.log(chalk.dim('  Configure the provider first from the Settings screen (P) or via env vars.'))
+    console.log()
+    return 1
+  }
+
+  console.log(chalk.cyan(`  ▶ Launching ${meta.label} with ${chalk.bold(model.label)}...`))
+
+  if (mode === 'aider') {
+    printConfigResult(meta.label, writeAiderConfig(model, apiKey, baseUrl))
+    return spawnCommand('aider', ['--model', `openai/${model.modelId}`], env)
+  }
+
+  if (mode === 'crush') {
+    let crushApiKey = apiKey
+    let crushBaseUrl = baseUrl
+    let providerId = 'freeCodingModels'
+    const proxySettings = getProxySettings(config)
+
+    if (proxySettings.enabled) {
+      const started = await ensureProxyRunning(config)
+      crushApiKey = started.proxyToken
+      crushBaseUrl = `http://127.0.0.1:${started.port}/v1`
+      providerId = 'freeCodingModelsProxy'
+      console.log(chalk.dim(`  📖 Crush will use the local FCM proxy on :${started.port} for this launch.`))
+    } else {
+      console.log(chalk.dim('  📖 Crush will use the provider directly for this launch.'))
+    }
+
+    printConfigResult(meta.label, writeCrushConfig(model, crushApiKey, crushBaseUrl, providerId))
+    return spawnCommand('crush', [], env)
+  }
+
+  if (mode === 'goose') {
+    env.OPENAI_HOST = baseUrl
+    env.OPENAI_BASE_PATH = 'v1/chat/completions'
+    env.OPENAI_MODEL = model.modelId
+    console.log(chalk.dim('  📖 Goose uses env-based OpenAI-compatible configuration for this launch.'))
+    return spawnCommand('goose', [], env)
+  }
+
+  if (mode === 'claude-code') {
+    console.log(chalk.yellow('  ⚠ Claude Code expects an Anthropic/Bedrock/Vertex-compatible gateway.'))
+    console.log(chalk.dim('  This launch passes proxy env vars, but your endpoint must support Claude Code wire semantics.'))
+    return spawnCommand('claude', ['--model', model.modelId], env)
+  }
+
+  if (mode === 'codex') {
+    console.log(chalk.dim('  📖 Codex CLI is launched with proxy env vars for this session.'))
+    return spawnCommand('codex', ['--model', model.modelId], env)
+  }
+
+  if (mode === 'gemini') {
+    printConfigResult(meta.label, writeGeminiConfig(model))
+    return spawnCommand('gemini', ['--model', model.modelId], env)
+  }
+
+  if (mode === 'qwen') {
+    printConfigResult(meta.label, writeQwenConfig(model, model.providerKey, apiKey, baseUrl))
+    return spawnCommand('qwen', [], env)
+  }
+
+  if (mode === 'openhands') {
+    console.log(chalk.dim('  📖 OpenHands is launched with --override-with-envs so the selected model applies immediately.'))
+    return spawnCommand('openhands', ['--override-with-envs'], env)
+  }
+
+  if (mode === 'amp') {
+    printConfigResult(meta.label, writeAmpConfig(baseUrl))
+    console.log(chalk.yellow('  ⚠ Amp does not officially expose arbitrary model switching like the other CLIs.'))
+    console.log(chalk.dim('  The proxy URL is written, then Amp is launched so you can reuse the current endpoint.'))
+    return spawnCommand('amp', [], env)
+  }
+
+  if (mode === 'pi') {
+    printConfigResult(meta.label, writePiConfig(model, apiKey, baseUrl))
+    return spawnCommand('pi', [], env)
+  }
+
+  console.log(chalk.red(`  X Unsupported external tool mode: ${mode}`))
+  return 1
+}

package/src/tool-metadata.js

@@ -0,0 +1,63 @@
+/**
+ * @file src/tool-metadata.js
+ * @description Shared metadata for supported launch targets and mode ordering.
+ *
+ * @details
+ *   📖 The TUI now supports more than the historical OpenCode/OpenClaw trio.
+ *   Centralizing mode metadata keeps the header badge, help screen, key handler,
+ *   and CLI parsing aligned instead of hard-coding tool names in multiple files.
+ *
+ *   📖 The metadata here is intentionally small:
+ *   - display label for the active tool badge
+ *   - optional emoji for compact UI hints
+ *   - flag name used in CLI help
+ *
+ *   📖 External tool integrations are still implemented elsewhere. This file only
+ *   answers "what modes exist?" and "how should they be presented to the user?".
+ *
+ * @functions
+ *   → `getToolMeta` — return display metadata for one mode
+ *   → `getToolModeOrder` — stable mode cycle order for the `Z` hotkey
+ *
+ * @exports TOOL_METADATA, TOOL_MODE_ORDER, getToolMeta, getToolModeOrder
+ */
+
+export const TOOL_METADATA = {
+  opencode: { label: 'OpenCode CLI', emoji: '💻', flag: '--opencode' },
+  'opencode-desktop': { label: 'OpenCode Desktop', emoji: '🖥', flag: '--opencode-desktop' },
+  openclaw: { label: 'OpenClaw', emoji: '🦞', flag: '--openclaw' },
+  crush: { label: 'Crush', emoji: '💘', flag: '--crush' },
+  goose: { label: 'Goose', emoji: '🪿', flag: '--goose' },
+  // 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' },
+  // pi: { label: 'Pi', emoji: 'π', flag: '--pi' },
+}
+
+export const TOOL_MODE_ORDER = [
+  'opencode',
+  'opencode-desktop',
+  'openclaw',
+  'crush',
+  'goose',
+  // 'aider',
+  // 'claude-code',
+  // 'codex',
+  // 'gemini',
+  // 'qwen',
+  // 'openhands',
+  // 'amp',
+  // 'pi',
+]
+
+export function getToolMeta(mode) {
+  return TOOL_METADATA[mode] || { label: mode, emoji: '•', flag: null }
+}
+
+export function getToolModeOrder() {
+  return [...TOOL_MODE_ORDER]
+}