free-coding-models 0.2.17 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 ---
 
+## 0.3.1
+
+### Added
+- **CLI `--help` output**: `free-coding-models --help` now prints the full launcher, analysis, config, and daemon command matrix in a non-interactive format.
+
+### Fixed
+- **Outdated-version footer alert**: The main TUI now shows a full-width red footer line with manual `npm install -g free-coding-models@latest` recovery instructions, but only when a newer npm version is actually known.
+- **Claude Code proxy auth conflict**: Proxy launches now sanitize inherited env vars and use only `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_BASE_URL`, matching the `free-claude-code` contract instead of mixing Anthropic auth modes.
+- **Codex CLI proxy routing**: Codex launches now force an explicit custom provider config and the proxy now supports `POST /v1/responses`, so `codex-cli 0.114.0` no longer depends on the broken built-in OAuth/base-url path.
+- **Anthropic token counting**: Added `POST /v1/messages/count_tokens` with a fast local estimate so Claude-compatible clients keep their budgeting flow through FCM Proxy V2.
+- **Gemini proxy failure mode**: Gemini launch now preflights the installed CLI/config, blocks incompatible builds like `0.33.0`, and surfaces `~/.gemini/settings.json` schema errors instead of pretending proxy mode works.
+
+### Changed
+- **Proxy auto-sync now follows the current tool**: The proxy overlay no longer asks for a separate active tool; cleanup and auto-sync now target the current `Z` mode whenever that tool supports persisted proxy config.
+- **Install Endpoints (`Y`) is narrower on purpose**: `Claude Code`, `Codex`, and `Gemini` were removed from the install-target menu so the flow only lists tools with a stable persisted-config contract.
+- **Proxy model listing is more Codex-friendly**: `GET /v1/models` now returns both the usual OpenAI `data` array and a `models` array with `slug` fields for clients that expect a richer catalog shape.
+- **Launcher diagnostics now mention the beta state clearly**: Proxy-backed external tools now remind users that the integration is still stabilizing when a launch is blocked.
+
+## 0.3.0
+
+### Added
+- **Always-on background proxy service**: FCM Proxy V2 can run as a persistent background service via `launchd` (macOS) or `systemd` (Linux). All tools get free model access 24/7 — no need to keep the TUI open.
+- **Anthropic wire format translation**: Native bidirectional translation between Anthropic Messages API (`POST /v1/messages`) and OpenAI Chat Completions. Claude Code works natively through FCM Proxy V2.
+- **Dedicated FCM Proxy V2 overlay**: New full-page overlay (from Settings → "FCM Proxy V2 settings →" or `J` key) with proxy config, service status, restart, stop, force-kill, and log viewer.
+- **`J` key — FCM Proxy V2 shortcut**: Opens the proxy settings directly from the main view. Footer shows a green `📡 FCM Proxy V2 On` badge when active, red `📡 FCM Proxy V2 Off` when disabled.
+- **CLI daemon subcommand**: `free-coding-models daemon [status|install|uninstall|restart|stop|logs]` for headless service control.
+- **Stable proxy identity**: Persistent token and preferred port (`18045`) survive daemon restarts — env files and tool configs remain valid across reboots.
+- **Health endpoint**: `GET /v1/health` returns uptime, version, and account/model counts for liveness probes.
+- **`GET /v1/stats` endpoint**: Authenticated endpoint returning per-account health, token stats, totals, and proxy uptime for monitoring and debugging.
+- **Hot-reload**: FCM Proxy V2 watches `~/.free-coding-models.json` and reloads proxy topology automatically when config changes.
+- **Version mismatch detection**: The overlay warns when the running service version differs from the installed FCM version.
+- **Dev environment guard**: `installDaemon()` is blocked when running from a git checkout to prevent hardcoding local repo paths in OS service files.
+- **Generalized proxy sync module** (`src/proxy-sync.js`): Single-endpoint proxy config sync for 12 tools (OpenCode, OpenClaw, Crush, Goose, Pi, Aider, Amp, Qwen, Claude Code, Codex, OpenHands). Writes one `fcm-proxy` provider with all models, cleans up old per-provider `fcm-*` vestiges.
+- **Retry backoff with jitter**: Progressive delays between retries (0ms, 300ms, 800ms + random jitter) to avoid re-hitting the same rate-limit window on 429s.
+- **Automatic account cooldown on consecutive failures**: When an account accumulates 3+ consecutive non-429 failures, it enters graduated cooldown (30s → 60s → 120s). Proxy routes around failing accounts automatically. Resets on success.
+
+### Changed
+- **Rebranded to FCM Proxy V2**: All user-facing references to "daemon", "FCM Proxy", and "Proxy & Daemon" renamed to "FCM Proxy V2" across CLI messages, TUI overlays, endpoint installer, and service descriptions.
+- **Proxy overlay generalized for all tools**: "Persist proxy in OpenCode" → "Auto-sync proxy to {tool}", "Clean OpenCode proxy config" → "Clean {tool} proxy config". New "Active tool" selector row cycles through all 12 proxy-syncable tools.
+- **Feedback overlay redesigned**: Renamed "Report bug" to "Feedback, bugs & requests", input is now left-aligned with a visible cursor, framed by horizontal separator lines. `I` key now covers all feedback types.
+- **Proxy settings moved to dedicated overlay**: The 5 proxy rows in Settings are replaced by a single entry that opens a full-page manager.
+- **Proxy topology extracted to shared module**: `src/proxy-topology.js` is now used by both TUI and daemon, eliminating code duplication.
+- **TUI delegates to background service**: `ensureProxyRunning()` checks for a running service first and reuses its port/token instead of starting an in-process proxy.
+- **Endpoint installer supports proxy mode**: When installing endpoints (Y key) with "FCM Proxy V2" connection mode, env files point to the service's stable token/port.
+- **Claude Code / Codex / Gemini require proxy**: These tools now refuse to launch without FCM Proxy V2 enabled, showing clear instructions to enable it. When proxy is on, they route through it automatically.
+- **Goose launcher rewritten**: Now writes proper custom provider JSON + updates `config.yaml` with `GOOSE_PROVIDER`/`GOOSE_MODEL` for guaranteed auto-selection (replaces obsolete `OPENAI_HOST`/`OPENAI_MODEL` env vars).
+- **Crush launcher improved**: Removed `disable_default_providers` flag, sets both `models.large` and `models.small` defaults for reliable auto-selection.
+- **Pi launcher improved**: Now passes `--provider` and `--model` CLI flags for guaranteed model pre-selection.
+
+### Fixed
+- **Terminal width warning behavior**: Warning now shows max 2 times per session with emojis and double spacing.
+- **Body size limit** (security): `readBody()` now enforces a 10 MB limit. Oversized payloads receive 413.
+- **Stack trace leak prevention** (security): Error responses no longer include `err.message`.
+- **SSE buffer overflow guard** (security): Anthropic SSE transformer limits buffer to 1 MB.
+- **`new URL()` crash protection**: Malformed upstream URLs caught instead of crashing.
+- **`execSync` timeout safety**: All `execSync` calls in daemon-manager use a 15-second timeout via `execSyncSafe()`.
+- **Daemon startup crash protection**: `loadConfig()`, `buildMergedModelsForDaemon()`, and `buildProxyTopologyFromConfig()` wrapped in try/catch.
+- **`resolveCloudflareUrl()` null guard**: Empty provider URLs skipped instead of crashing.
+- **Health check buffer limit**: Responses capped at 64 KB.
+- **SSE line buffering**: SSE tap now correctly handles lines split across chunk boundaries.
+- **Empty choices fallback**: `translateOpenAIToAnthropic` returns fallback content block when OpenAI response has empty choices.
+- **Tool calls streaming index tracking**: Proper `nextBlockIndex`/`currentBlockIndex` counters for correct indexing across multiple tool calls.
+- **Pipe error propagation**: Error handlers on both sides of SSE pipes to prevent uncaught errors on mid-stream disconnects.
+- **Input validation**: `translateAnthropicToOpenAI` guards against null/undefined/non-object input.
+- **Hot-reload race condition**: Config watcher uses `reloadInProgress` flag to prevent concurrent reloads.
+- **Fake response stubs**: Added `destroy()`, `removeListener()`, and `socket: null` for better compatibility.
+- **API key trimming**: Whitespace-trimmed and empty keys filtered out in topology builder.
+- **`writeFileSync` error messages**: Plist and systemd service file write failures now throw clear error messages.
+
+---
+
 ## 0.2.17
 
 ### Added

package/README.md

@@ -46,6 +46,9 @@ By Vanessa Depraute
   <sub>Ping free coding models from 20 providers in real-time — pick the best one for OpenCode, OpenClaw, or any AI coding assistant</sub>
 </p>
 
+> ⚠️ **Beta notice**  
+> FCM Proxy V2 support for external tools is still in beta. Claude Code, Codex, Gemini, and the other proxy-backed launchers already work in many setups, but auth and startup edge cases can still fail while the integration stabilizes.
+
 <p align="center">
   <img src="demo.gif" alt="free-coding-models demo" width="100%">
 </p>
@@ -69,8 +72,8 @@ By Vanessa Depraute
 
 - **🎯 Coding-focused** — Only LLM models optimized for code generation, not chat or vision
 - **🌐 Multi-provider** — Models from NVIDIA NIM, Groq, Cerebras, SambaNova, OpenRouter, Hugging Face Inference, Replicate, DeepInfra, Fireworks AI, Codestral, Hyperbolic, Scaleway, Google AI, SiliconFlow, Together AI, Cloudflare Workers AI, Perplexity API, Alibaba Cloud (DashScope), ZAI, and iFlow
-- **⚙️ Settings screen** — Press `P` to manage provider API keys, enable/disable providers, configure the proxy, clean OpenCode proxy sync, and manually check/install updates
-- **🔀 Multi-account Proxy (`fcm-proxy`)** — Automatically starts a local reverse proxy that groups all your accounts into a single provider in OpenCode; supports multi-account rotation and auto-detects usage limits to swap between providers.
+- **⚙️ Settings screen** — Press `P` to manage provider API keys, enable/disable providers, access FCM Proxy V2 settings, and check/install updates
+- **📡 FCM Proxy V2** — Built-in reverse proxy with multi-key rotation, rate-limit failover, and Anthropic wire format translation for Claude Code. Optional always-on background service (`launchd`/`systemd`) keeps the proxy running 24/7 — even without the TUI. Dedicated overlay with full status, restart, stop, force-kill, and log viewer.
 - **🚀 Parallel pings** — All models tested simultaneously via native `fetch`
 - **📊 Real-time animation** — Watch latency appear live in alternate screen buffer
 - **🏆 Smart ranking** — Top 3 fastest models highlighted with medals 🥇🥈🥉
@@ -87,7 +90,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 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
+- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider into the compatible persisted-config tools, with a choice between **Direct Provider** (pure API) or **FCM Proxy V2** (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
@@ -179,15 +182,13 @@ bunx free-coding-models YOUR_API_KEY
 
 ### 🆕 What's New
 
-**Version 0.2.6 brings powerful new features:**
-
-- **`--json` flag** — Output model results as JSON for scripting, CI/CD pipelines, and monitoring dashboards. Perfect for automation: `free-coding-models --tier S --json | jq '.[0].modelId'`
-
-- **Persistent ping cache** — Results are cached for 5 minutes between runs. Startup is nearly instant when cache is fresh, and you save API rate limits. Cache file: `~/.free-coding-models.cache.json`
-
-- **Config security check** — Automatically warns if your API key config file has insecure permissions and offers one-click auto-fix with `chmod 600`
+**Version 0.3.1 tightens the proxy/tooling path and ships the missing diagnostics:**
 
-- **Provider colors everywhere** — Provider names are now colored consistently in logs, settings, and the main table for better visual recognition
+- **Claude Code proxy launches are cleaner** — FCM now launches Claude Code with an Anthropic-only proxy contract (`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`) instead of mixing auth modes.
+- **Codex proxy launches now use the right API path** — Codex is forced into an explicit custom provider config and the proxy now implements `POST /v1/responses`.
+- **Gemini proxy launches fail fast when unsupported** — Older Gemini CLI builds and invalid local config are detected up front, with a clear message instead of a misleading broken launch.
+- **Proxy auto-sync follows the current tool** — The FCM Proxy V2 overlay no longer relies on a separate active-tool picker, and `Y` now lists only stable persisted-config install targets.
+- **Beta messaging is explicit** — The README and runtime launcher diagnostics now call out that proxy-backed external tool support is still stabilizing.
 
 ---
 
@@ -216,11 +217,14 @@ free-coding-models --best
  # Analyze for 10 seconds and output the most reliable model
  free-coding-models --fiable
 
- # Output results as JSON (for scripting/automation)
+# Output results as JSON (for scripting/automation)
 free-coding-models --json
 free-coding-models --tier S --json | jq '.[0].modelId'  # Get fastest S-tier model ID
 free-coding-models --json | jq '.[] | select(.avgPing < 500)'  # Filter by latency
 
+# Print the complete CLI help with every supported flag and daemon command
+free-coding-models --help
+
  # Filter models by tier letter
 free-coding-models --tier S          # S+ and S only
 free-coding-models --tier A          # A+, A, A- only
@@ -315,6 +319,7 @@ Press **`P`** to open the Settings screen at any time:
  Keys are saved to `~/.free-coding-models.json` (permissions `0600`).
 
  Manual update is in the same Settings screen (`P`) under **Maintenance** (Enter to check, Enter again to install when an update is available).
+ When a newer npm release is known, the main footer also adds a full-width red warning line with the manual recovery command `npm install -g free-coding-models@latest`.
  Favorites are also persisted in the same config file and survive restarts.
  The main table now starts in `Configured Only` mode, so if nothing is set up yet you can press `P` and add your first API key immediately.
 
@@ -554,31 +559,92 @@ Stability = 0.30 × p95_score
 
 ---
 
-## 🔀 Multi-Account Proxy (`fcm-proxy`)
+## 📡 FCM Proxy V2
+
+`free-coding-models` includes a local reverse proxy that merges all your provider API keys into one endpoint. Optional background service mode keeps it running 24/7 — even without the TUI.
+
+> **Disabled by default** — enable in Settings (`P`) → FCM Proxy V2 settings.
+
+### What the proxy does
+
+| Feature | Description |
+|---------|-------------|
+| **Unified endpoint** | One URL (`http://127.0.0.1:18045/v1`) replaces 20+ provider endpoints |
+| **Key rotation** | Automatically swaps to the next API key when one hits rate limits (429) |
+| **Usage tracking** | Tracks token consumption per provider/model pair in real-time |
+| **Anthropic translation** | Claude Code sends `POST /v1/messages` — the proxy translates to OpenAI format upstream |
+| **Path normalization** | Converts non-standard API paths (ZAI, Cloudflare) to standard `/v1/` calls |
+
+### In-process vs Background Service mode
+
+| | In-process (default) | Background Service (always-on) |
+|---|---|---|
+| **Lifetime** | Starts/stops with TUI | Survives reboots |
+| **Use case** | Quick sessions | 24/7 access from any tool |
+| **Setup** | Toggle in Settings | One-time install via TUI or CLI |
+| **Port** | Random or configured | Stable (`18045` by default) |
+| **Token** | New each session | Persistent (env files stay valid) |
+
+### Quick setup
+
+**Via TUI (recommended):**
+1. Press `P` to open Settings
+2. Select **FCM Proxy V2 settings →** and press Enter
+3. Enable **Proxy mode**, then select **Install background service**
 
-`free-coding-models` includes a built-in reverse proxy that can group all your provider accounts into a single virtual provider.
+**Via CLI:**
+```bash
+free-coding-models daemon install     # Install + start as OS service
+free-coding-models daemon status      # Check running status
+free-coding-models daemon restart     # Restart after config changes
+free-coding-models daemon stop        # Graceful stop (SIGTERM)
+free-coding-models daemon uninstall   # Remove OS service completely
+free-coding-models daemon logs        # Show recent service logs
+```
+
+### Service management
+
+The dedicated **FCM Proxy V2** overlay (accessible via `J` from main TUI, or Settings → Enter) provides full control:
+
+- **Current tool hint** — Shows which Z-selected tool will receive persisted proxy config (when that mode supports it)
+- **Auto-sync toggle** — Automatically write the `fcm-proxy` provider to the current tool's config when the proxy starts
+- **Cleanup** — Remove `fcm-proxy` entries from the current tool's config
+- **Status display** — Running/Stopped/Stale/Unhealthy with PID, port, uptime, account/model counts
+- **Version mismatch detection** — warns if service version differs from installed FCM version
+- **Restart** — stop + start via the OS service manager
+- **Stop** — graceful SIGTERM (service may auto-restart if installed)
+- **Force kill** — emergency SIGKILL for stuck processes
+- **View logs** — last 50 lines from `~/.free-coding-models/daemon-stdout.log`
+
+### Platform support
+
+| Platform | Service type | Config path |
+|----------|-------------|-------------|
+| macOS | `launchd` LaunchAgent | `~/Library/LaunchAgents/com.fcm.proxy.plist` |
+| Linux | `systemd` user service | `~/.config/systemd/user/fcm-proxy.service` |
+| Windows | Not supported | Falls back to in-process proxy |
 
-Important:
-- **Disabled by default** — proxy mode is now opt-in from the Settings screen (`P`)
-- **Direct OpenCode launch remains the default** when proxy mode is off
-- **Token/request logs are only populated by proxied requests** today
+### Config files
 
-### Why use the proxy?
-- **Unified Provider**: Instead of managing 20+ providers in your coding assistant, just use `fcm-proxy`.
-- **Automatic Rotation**: When one account hits its rate limit (429), the proxy automatically swaps to the next available account for that model.
-- **Quota Awareness**: The proxy tracks usage in real-time and prioritizes accounts with the most remaining bandwidth.
-- **Transparent Bridging**: Automatically handles non-standard API paths (like ZAI's `/api/coding/paas/v4/`) and converts them to standard OpenAI-compatible `/v1/` calls.
+| File | Purpose |
+|------|---------|
+| `~/.free-coding-models.json` | API keys, proxy settings, service consent |
+| `~/.free-coding-models/daemon.json` | Status file (PID, port, token) — written by the background service |
+| `~/.free-coding-models/daemon-stdout.log` | Service output log |
 
-### How to use it
-1. Open **Settings** with `P`
-2. Enable **Proxy mode (opt-in)**
-3. Optionally enable **Persist proxy in OpenCode** if you explicitly want `fcm-proxy` written to `~/.config/opencode/opencode.json`
-4. Optionally set **Preferred proxy port** (`0` = auto)
-5. Use `S` in Settings to sync the proxy catalog into OpenCode only when you actually want that persistent config
+The `proxy.activeTool` field is now legacy-only. FCM Proxy V2 follows the current **Z-selected** tool automatically whenever that mode supports persisted proxy sync.
 
-Cleanup:
-- Use the Settings action **Clean OpenCode proxy config**
-- Or run `free-coding-models --clean-proxy`
+### Cleanup
+
+- From the FCM Proxy V2 overlay: **Clean {tool} proxy config** — removes `fcm-proxy` entries from whichever tool is currently selected
+- Or: `free-coding-models --clean-proxy`
+
+### Safety
+
+- **Dev guard**: `installDaemon()` is blocked when running from a git checkout — prevents hardcoding local repo paths in OS service files
+- **Localhost only**: The proxy listens on `127.0.0.1`, never exposed to the network
+- **Consent required**: Service installation requires explicit user action — never auto-installs
+- **Hot-reload**: Config changes are picked up automatically without restarting the service
 
 ---
 
@@ -605,11 +671,11 @@ You can use `free-coding-models` with 12+ AI coding tools. When you select a mod
 | OpenCode Desktop | `--opencode-desktop` | Opens Desktop app |
 | OpenClaw | `--openclaw` | ~/.openclaw/openclaw.json |
 | Crush | `--crush` | ~/.config/crush/crush.json |
-| Goose | `--goose` | Environment variables |
+| Goose | `--goose` | ~/.config/goose/config.yaml + custom_providers/ |
 | **Aider** | `--aider` | ~/.aider.conf.yml |
-| **Claude Code** | `--claude-code` | CLI flag |
-| **Codex** | `--codex` | CLI flag |
-| **Gemini** | `--gemini` | ~/.gemini/settings.json |
+| **Claude Code** ⚡ | `--claude-code` | Requires FCM Proxy V2 |
+| **Codex** ⚡ | `--codex` | Requires FCM Proxy V2 |
+| **Gemini** ⚡ | `--gemini` | Requires FCM Proxy V2 |
 | **Qwen** | `--qwen` | ~/.qwen/settings.json |
 | **OpenHands** | `--openhands` | LLM_MODEL env var |
 | **Amp** | `--amp` | ~/.config/amp/settings.json |
@@ -617,7 +683,13 @@ You can use `free-coding-models` with 12+ AI coding tools. When you select a mod
 
 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.
+⚡ = Requires FCM Proxy V2 background service (press `J` to enable). These tools cannot connect to free providers without the proxy.
+
+Proxy-backed external tool support is still beta. Expect occasional launch/auth rough edges while third-party CLI contracts are still settling.
+
+`Codex` is launched through an explicit custom provider config so it stays in API-key mode through the proxy. `Gemini` proxy launches are version-gated: older builds like `0.33.0` are blocked with a clear diagnostic instead of being misconfigured silently.
+
+The **Install Endpoints** flow (`Y` key) now targets only the tools with a stable persisted config contract. `Claude Code`, `Codex`, and `Gemini` stay launcher-only and should be started directly from FCM.
 
 ---
 
@@ -930,13 +1002,14 @@ This script:
 - **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 → connection mode → scope → models`, Direct or FCM Proxy)
+- **Y** — Open Install Endpoints (`provider → tool → connection mode → scope → models`, Direct or FCM Proxy V2)
 - **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)
 - **N** — Open Changelog overlay (browse index of all versions, `Enter` to view details, `B` to go back)
 - **W** — Cycle ping mode (`FAST` 2s → `NORMAL` 10s → `SLOW` 30s → `FORCED` 4s)
-- **J / I** — Request feature / Report bug
+- **J** — Open FCM Proxy V2 settings (shows green "Proxy On" / red "Proxy Off" badge in footer)
+- **I** — Feedback, bugs & requests
 - **K / Esc** — Show help overlay / Close overlay
 - **Ctrl+C** — Exit
 
@@ -947,12 +1020,12 @@ Pressing **K** now shows a full in-app reference: main hotkeys, settings hotkeys
 `Y` opens a dedicated install flow for configured providers. The 5-step flow is:
 
 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)
+2. **Tool** — Pick the target tool from the compatible install targets:
+   - Config-based: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Pi`, `Aider`, `Amp`, `Qwen`
+   - Env-file based: `OpenHands` (writes `~/.fcm-openhands-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
+   - **🔄 FCM Proxy V2** — route through FCM Proxy V2 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
 
@@ -962,7 +1035,8 @@ Important behavior:
 - `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
+- `Claude Code`, `Codex`, and `Gemini` are launcher-only in this flow for now. Use the normal `Enter` launcher path so FCM can apply the right proxy/runtime contract automatically.
+- For env-based install targets like `OpenHands`, FCM writes a sourceable helper file at `~/.fcm-{tool}-env`
 
  **Keyboard shortcuts (Settings screen — `P` key):**
  - **↑↓** — Navigate providers, maintenance row, and profile rows

package/bin/fcm-proxy-daemon.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+/**
+ * @file bin/fcm-proxy-daemon.js
+ * @description Standalone headless FCM proxy daemon — runs independently of the TUI.
+ *
+ * 📖 This is the always-on background proxy server. It reads the user's config
+ *    (~/.free-coding-models.json), builds the proxy topology (merged models × API keys),
+ *    and starts a ProxyServer on a stable port with a stable token.
+ *
+ * 📖 When installed as a launchd LaunchAgent (macOS) or systemd user service (Linux),
+ *    this daemon starts at login and persists across reboots, allowing Claude Code,
+ *    Gemini CLI, OpenCode, and all other tools to access free models 24/7.
+ *
+ * 📖 Status file: ~/.free-coding-models/daemon.json
+ *    Contains PID, port, token, version, model/account counts. The TUI reads this
+ *    to detect a running daemon and delegate instead of starting an in-process proxy.
+ *
+ * 📖 Hot-reload: Watches ~/.free-coding-models.json for changes and reloads the
+ *    proxy topology (accounts, models) without restarting the process.
+ *
+ * @see src/proxy-topology.js — shared topology builder
+ * @see src/proxy-server.js — ProxyServer implementation
+ * @see src/daemon-manager.js — install/uninstall/status management
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, watch } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+// 📖 Resolve package.json for version info
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+let PKG_VERSION = 'unknown'
+try {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'))
+  PKG_VERSION = pkg.version || 'unknown'
+} catch { /* ignore */ }
+
+// 📖 Config + data paths
+const CONFIG_PATH = join(homedir(), '.free-coding-models.json')
+const DATA_DIR = join(homedir(), '.free-coding-models')
+const DAEMON_STATUS_FILE = join(DATA_DIR, 'daemon.json')
+const LOG_PREFIX = '[fcm-daemon]'
+
+// 📖 Default daemon port — high port unlikely to conflict
+const DEFAULT_DAEMON_PORT = 18045
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function log(msg) {
+  console.log(`${LOG_PREFIX} ${new Date().toISOString()} ${msg}`)
+}
+
+function logError(msg) {
+  console.error(`${LOG_PREFIX} ${new Date().toISOString()} ERROR: ${msg}`)
+}
+
+/**
+ * 📖 Write daemon status file so TUI and tools can discover the running daemon.
+ */
+function writeDaemonStatus(info) {
+  if (!existsSync(DATA_DIR)) {
+    mkdirSync(DATA_DIR, { mode: 0o700, recursive: true })
+  }
+  writeFileSync(DAEMON_STATUS_FILE, JSON.stringify(info, null, 2), { mode: 0o600 })
+}
+
+/**
+ * 📖 Remove daemon status file on shutdown.
+ */
+function removeDaemonStatus() {
+  try {
+    if (existsSync(DAEMON_STATUS_FILE)) unlinkSync(DAEMON_STATUS_FILE)
+  } catch { /* best-effort */ }
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  log(`Starting FCM Proxy V2 v${PKG_VERSION} (PID: ${process.pid})`)
+
+  // 📖 Dynamic imports — keep startup fast, avoid loading TUI-specific modules
+  const { loadConfig, getProxySettings } = await import('../src/config.js')
+  const { ProxyServer } = await import('../src/proxy-server.js')
+  const { buildProxyTopologyFromConfig, buildMergedModelsForDaemon } = await import('../src/proxy-topology.js')
+  const { sources } = await import('../sources.js')
+
+  // 📖 Load config and build initial topology — wrapped in try/catch to provide clear error on startup failures
+  let fcmConfig, proxySettings, mergedModels, accounts, proxyModels
+  try {
+    fcmConfig = loadConfig()
+    proxySettings = getProxySettings(fcmConfig)
+  } catch (err) {
+    logError(`Fatal: Failed to load config: ${err.message}`)
+    process.exit(1)
+  }
+
+  if (!proxySettings.stableToken) {
+    logError('No stableToken in proxy settings — run the TUI first to initialize config.')
+    process.exit(1)
+  }
+
+  const port = proxySettings.preferredPort || DEFAULT_DAEMON_PORT
+  const token = proxySettings.stableToken
+
+  try {
+    log(`Building merged model catalog...`)
+    mergedModels = await buildMergedModelsForDaemon()
+    log(`Merged ${mergedModels.length} model groups`)
+
+    const topology = buildProxyTopologyFromConfig(fcmConfig, mergedModels, sources)
+    accounts = topology.accounts
+    proxyModels = topology.proxyModels
+  } catch (err) {
+    logError(`Fatal: Failed to build initial topology: ${err.message}`)
+    process.exit(1)
+  }
+
+  if (accounts.length === 0) {
+    logError('No API keys configured — FCM Proxy V2 has no accounts to serve. Add keys via the TUI.')
+    process.exit(1)
+  }
+
+  log(`Built proxy topology: ${accounts.length} accounts across ${Object.keys(proxyModels).length} models`)
+
+  // 📖 Start the proxy server
+  const proxy = new ProxyServer({
+    port,
+    accounts,
+    proxyApiKey: token,
+  })
+
+  try {
+    const { port: listeningPort } = await proxy.start()
+    log(`Proxy listening on 127.0.0.1:${listeningPort}`)
+
+    // 📖 Write status file for TUI discovery
+    const statusInfo = {
+      pid: process.pid,
+      port: listeningPort,
+      token,
+      startedAt: new Date().toISOString(),
+      version: PKG_VERSION,
+      modelCount: Object.keys(proxyModels).length,
+      accountCount: accounts.length,
+    }
+    writeDaemonStatus(statusInfo)
+    log(`Status file written to ${DAEMON_STATUS_FILE}`)
+
+    // 📖 Set up config file watcher for hot-reload
+    let reloadTimeout = null
+    // 📖 Prevents concurrent reloads — if a reload is in progress, the next
+    //    watcher event will be queued (one pending max) instead of stacking
+    let reloadInProgress = false
+    let reloadQueued = false
+    const configWatcher = watch(CONFIG_PATH, () => {
+      // 📖 Debounce 1s — config writes can trigger multiple fs events
+      if (reloadTimeout) clearTimeout(reloadTimeout)
+      reloadTimeout = setTimeout(async () => {
+        if (reloadInProgress) {
+          reloadQueued = true
+          return
+        }
+        reloadInProgress = true
+        try {
+          log('Config file changed — reloading topology...')
+          fcmConfig = loadConfig()
+          mergedModels = await buildMergedModelsForDaemon()
+          const newTopology = buildProxyTopologyFromConfig(fcmConfig, mergedModels, sources)
+
+          if (newTopology.accounts.length === 0) {
+            log('Warning: new topology has 0 accounts — keeping current topology')
+            return
+          }
+
+          proxy.updateAccounts(newTopology.accounts)
+          accounts = newTopology.accounts
+          proxyModels = newTopology.proxyModels
+
+          // 📖 Update status file
+          writeDaemonStatus({
+            ...statusInfo,
+            modelCount: Object.keys(proxyModels).length,
+            accountCount: accounts.length,
+          })
+
+          log(`Topology reloaded: ${accounts.length} accounts, ${Object.keys(proxyModels).length} models`)
+        } catch (err) {
+          logError(`Hot-reload failed: ${err.message}`)
+        } finally {
+          reloadInProgress = false
+          // 📖 If another reload was queued during this one, trigger it now
+          if (reloadQueued) {
+            reloadQueued = false
+            configWatcher.emit('change')
+          }
+        }
+      }, 1000)
+    })
+
+    // 📖 Graceful shutdown
+    const shutdown = async (signal) => {
+      log(`Received ${signal} — shutting down...`)
+      if (reloadTimeout) clearTimeout(reloadTimeout)
+      configWatcher.close()
+      try {
+        await proxy.stop()
+      } catch { /* best-effort */ }
+      removeDaemonStatus()
+      log('FCM Proxy V2 stopped cleanly.')
+      process.exit(0)
+    }
+
+    process.on('SIGINT', () => shutdown('SIGINT'))
+    process.on('SIGTERM', () => shutdown('SIGTERM'))
+    process.on('exit', () => removeDaemonStatus())
+
+    // 📖 Keep the process alive
+    log('FCM Proxy V2 ready. Waiting for requests...')
+
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      logError(`Port ${port} is already in use. Another FCM Proxy V2 instance may be running, or another process occupies this port.`)
+      logError(`Change proxy.preferredPort in ~/.free-coding-models.json or stop the conflicting process.`)
+      process.exit(2)
+    }
+    logError(`Failed to start proxy: ${err.message}`)
+    removeDaemonStatus()
+    process.exit(1)
+  }
+}
+
+main().catch(err => {
+  logError(`Fatal: ${err.message}`)
+  removeDaemonStatus()
+  process.exit(1)
+})