Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Add Cline CLI as a first-class FCC harness (#1446)

Ali Khokharc4ed677c425b
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index b386648d..ba3aa083 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -172,6 +172,9 @@ for real prompts against supported providers:
- `fcc-opencode`, stable OpenCode V1, and the OpenAI Responses behavior it
relies on, including an FCC-scoped model catalog and process-local provider
configuration.
+- `fcc-cline`, stable Cline CLI, and the OpenAI Responses behavior it relies
+ on, including an FCC-scoped model catalog, attached local sessions, and
+ process-local provider configuration.
- Configured Discord and Telegram messaging bridges, including command handling,
reply-based conversation branches, status updates, transcript rendering,
managed Claude/Codex task execution where configured, task stop/clear flows,
@@ -227,6 +230,7 @@ Console scripts are registered in [pyproject.toml](pyproject.toml):
- `fcc-codex` calls `free_claude_code.cli.launchers.codex:launch`.
- `fcc-pi` calls `free_claude_code.cli.launchers.pi:launch`.
- `fcc-opencode` calls `free_claude_code.cli.launchers.opencode:launch`.
+- `fcc-cline` calls `free_claude_code.cli.launchers.cline:launch`.
[scripts/install.sh](scripts/install.sh) and [scripts/install.ps1](scripts/install.ps1)
install or update the uv tool plus optional voice extras. On Windows the
@@ -235,7 +239,7 @@ per-user application bundle and desktop link. [scripts/uninstall.sh](scripts/uni
and [scripts/uninstall.ps1](scripts/uninstall.ps1) remove those exact desktop
artifacts, the FCC uv tool, and the managed `~/.fcc/` tree from
[config/paths.py](src/free_claude_code/config/paths.py); they do not remove
-uv, Claude Code, Codex, Pi, OpenCode, or uv-managed Python runtimes. [scripts/ci.sh](scripts/ci.sh) and
+uv, Claude Code, Codex, Pi, OpenCode, Cline, or uv-managed Python runtimes. [scripts/ci.sh](scripts/ci.sh) and
[scripts/ci.ps1](scripts/ci.ps1) mirror [.github/workflows/tests.yml](.github/workflows/tests.yml)
for local pre-push verification.
@@ -1198,7 +1202,7 @@ client environment.
owns the client-neutral projection from FCC's `/v1/models` response to direct,
nested `provider/model` routes. It removes Claude-only compatibility aliases,
deduplicates normal and no-thinking forms deterministically, and is shared by
-Codex and OpenCode. Each launcher remains responsible for translating those
+Codex, OpenCode, and Cline. Each launcher remains responsible for translating those
neutral entries into its client's configuration format.
[cli/launchers/pi.py](src/free_claude_code/cli/launchers/pi.py) owns the installed
@@ -1238,6 +1242,36 @@ own the installed `fcc-opencode` launcher for stable OpenCode V1:
commands pass through without requiring FCC. Other arguments are forwarded
unchanged after the FCC process configuration is ready.
+[cli/launchers/cline.py](src/free_claude_code/cli/launchers/cline.py) and
+[cli/launchers/cline_config.py](src/free_claude_code/cli/launchers/cline_config.py)
+own the installed `fcc-cline` launcher for Cline CLI 3.0.55 or newer:
+
+- Attached inference sessions require a reachable FCC server and a non-empty
+ routable `/v1/models` snapshot. Preparation is fail-closed, and the launcher
+ prepends Cline's built-in `openai-native` provider while leaving an explicit
+ caller `--model` selection intact.
+- The launcher creates protected temporary `providers.json` and `models.json`
+ files. For that child only, they retarget Cline's existing OpenAI Responses
+ transport to FCC's `/v1` surface, rename it to Free Claude Code, replace its
+ catalog with nested FCC model slugs, and carry the canonical proxy token.
+ Cline 3.0.55's session gateway cannot instantiate user-defined provider IDs,
+ so this built-in transport seam is required even though its startup picker can
+ read custom providers.
+- `CLINE_PROVIDER_SETTINGS_PATH` points only that child at the generated
+ settings, and `CLINE_SESSION_BACKEND_MODE=local` keeps attached sessions in
+ the launcher lifecycle. Native Cline config, data, credentials, plugins, and
+ sessions remain Cline-owned.
+- Native configuration and package-management commands pass through without
+ requiring FCC. Hub, dashboard, schedule, connection, hook, kanban, and Zen
+ surfaces are rejected because they can outlive the temporary credential and
+ must be run with ordinary `cline`.
+- Cline sandbox data overrides are also rejected: released Cline rewrites its
+ provider-settings path in that mode, which would displace FCC's ephemeral
+ credential file. Ordinary Cline remains the owner of sandboxed runs.
+- Cline's provider picker can still expose its native providers. Startup and
+ command-line routing remain FCC-owned; deliberately switching providers
+ inside the running Cline process is an explicit opt-out for that process.
+
[cli/managed/](src/free_claude_code/cli/managed/) owns managed Claude Code subprocesses used by
Discord and Telegram messaging. Managed task invocations extend the same proxy
environment only with non-interactive terminal settings, optional `--resume`,
@@ -1261,7 +1295,7 @@ reports a count-only failure, and leaves failures available for the next cleanup
attempt. Real-session registration is collision-safe and becomes durable tree
state only after the manager accepts it.
-Codex, Pi, and OpenCode are supported through their installed launchers. FCC
+Codex, Pi, OpenCode, and Cline are supported through their installed launchers. FCC
does not keep internal managed session runners for them because no user-facing
messaging setting selects those clients for Discord or Telegram.
diff --git a/README.md b/README.md
index cd3e77d1..9dc0fee1 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@
## What You Get
- **48 providers. 1.3B+ free tokens a month. One proxy.** Use free, paid, subscription, or local models from one searchable Admin UI.
-- **4 coding agents. One model catalog.** Run Claude Code, Codex, Pi, or OpenCode with your FCC models.
+- **5 coding agents. One model catalog.** Run Claude Code, Codex, Pi, OpenCode, or Cline with your FCC models.
- **Up to 90% fewer terminal-output tokens.** Optional [RTK](https://github.com/rtk-ai/rtk) filters common command output, while five FCC optimizations handle quota probes, command-prefix detection, titles, suggestions, and filepaths without calling a provider.
- **Terminal, desktop, IDE, or phone.** Work through native launchers, VS Code, Codex App, JetBrains, Discord, or Telegram.
- **Voice notes in. Code out.** Talk to your agent using local Whisper or NVIDIA NIM transcription.
@@ -135,14 +135,22 @@ OpenCode:
fcc-opencode
```
-All four launchers use the current Admin UI settings. Use the agent's model picker to choose from the models FCC exposes. Normal CLI arguments still work, for example:
+Cline:
+
+```bash
+fcc-cline
+```
+
+All five launchers use the current Admin UI settings. Use the agent's model picker to choose from the models FCC exposes. Normal CLI arguments still work, for example:
```bash
fcc-codex exec "hello"
```
-`fcc-pi` and `fcc-opencode` register FCC only for the launched process; your
-existing agent settings, sessions, credentials, and extensions remain unchanged.
+`fcc-pi`, `fcc-opencode`, and `fcc-cline` configure FCC only for the launched
+process; your existing agent settings, sessions, credentials, and extensions
+remain unchanged. `fcc-cline` supports attached terminal sessions; run Cline's
+hub, schedule, connector, Zen, and sandbox-data workflows with ordinary `cline`.
<a id="model-picker"></a>
@@ -288,7 +296,7 @@ Open **Admin UI → Model Config → Reasoning** and select the behavior you wan
| Selection | Behavior |
| --- | --- |
-| **From client** (default) | Use the effort sent by Claude Code, Codex, Pi, or OpenCode. If none is sent, keep the provider default. |
+| **From client** (default) | Use the effort sent by Claude Code, Codex, Pi, OpenCode, or Cline. If none is sent, keep the provider default. |
| **Off** | Request reasoning to be disabled. |
| **Low**, **Medium**, **High**, **X-High**, or **Max** | Override the client with the selected reasoning level. |
| **Inherit** (Fable, Opus, Sonnet, and Haiku only) | Use the root Reasoning selection. |
@@ -302,7 +310,7 @@ Providers that do not support a selected control retain their own behavior.
## Connect Your Client
For terminal use, start `fcc-server`, then run `fcc-claude`, `fcc-codex`,
-`fcc-pi`, or `fcc-opencode`. Use the guides below for editor integrations.
+`fcc-pi`, `fcc-opencode`, or `fcc-cline`. Use the guides below for editor integrations.
<details>
<summary><strong>Claude Code in VS Code</strong></summary>
@@ -537,7 +545,7 @@ Stop every running FCC command before uninstalling.
**Keeps**
- uv and Python
-- Claude Code, Codex, Pi, OpenCode, and RTK
+- Claude Code, Codex, Pi, OpenCode, Cline, and RTK
- Shared PATH entries
macOS/Linux:
diff --git a/pyproject.toml b/pyproject.toml
index 30089a21..53b7bbe9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.5.1"
+version = "5.6.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
@@ -34,6 +34,7 @@ fcc-claude = "free_claude_code.cli.launchers.claude:launch"
fcc-codex = "free_claude_code.cli.launchers.codex:launch"
fcc-pi = "free_claude_code.cli.launchers.pi:launch"
fcc-opencode = "free_claude_code.cli.launchers.opencode:launch"
+fcc-cline = "free_claude_code.cli.launchers.cline:launch"
[project.gui-scripts]
fcc-desktop = "free_claude_code.cli.desktop_entrypoint:launch"
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 3253bb8a..bf42e064 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -23,6 +23,7 @@ $CodexInstallUrl = "https://chatgpt.com/codex/install.ps1"
$PiInstallUrl = "https://pi.dev/install.ps1"
$OpenCodeReleaseBaseUrl = "https://github.com/anomalyco/opencode/releases/latest/download"
$MinOpenCodeVersion = "1.18.18"
+$MinClineVersion = "3.0.55"
$RtkVersion = "0.44.2"
$RtkReleaseBaseUrl = "https://github.com/rtk-ai/rtk/releases/download/v$RtkVersion"
$RtkWindowsAssetName = "rtk-x86_64-pc-windows-msvc.zip"
@@ -32,6 +33,7 @@ $script:InstallClaudeCode = $true
$script:InstallCodex = $true
$script:InstallPi = $true
$script:InstallOpenCode = $true
+$script:InstallCline = $false
$script:PiAvailable = $false
$script:EnableRtk = $Rtk.IsPresent
$FccCommands = @(
@@ -42,6 +44,7 @@ $FccCommands = @(
"fcc-codex",
"fcc-pi",
"fcc-opencode",
+ "fcc-cline",
"fcc-init",
"free-claude-code"
)
@@ -102,8 +105,11 @@ function Select-CodingAgents {
$script:InstallCodex = Read-YesNo "Install or verify Codex for fcc-codex?"
$script:InstallPi = Read-YesNo "Install or verify Pi for fcc-pi?"
$script:InstallOpenCode = Read-YesNo "Install or verify OpenCode for fcc-opencode?"
+ $script:InstallCline = Read-YesNo `
+ -Prompt "Install or verify Cline CLI for fcc-cline?" `
+ -DefaultYes $script:InstallCline
- if ($script:InstallClaudeCode -or $script:InstallCodex -or $script:InstallPi -or $script:InstallOpenCode) {
+ if ($script:InstallClaudeCode -or $script:InstallCodex -or $script:InstallPi -or $script:InstallOpenCode -or $script:InstallCline) {
break
}
Write-Host "Select at least one coding agent."
@@ -247,7 +253,7 @@ function Add-KnownBinDirectories {
}
}
-function Add-PiBinDirectories {
+function Add-NpmBinDirectories {
if ($DryRun) {
return
}
@@ -543,6 +549,9 @@ function Configure-RtkForSelectedAgents {
if ($script:InstallOpenCode) {
Invoke-RtkCommand -Arguments @("init", "--global", "--opencode")
}
+ if ($script:InstallCline) {
+ Write-Host "Optional for each project: cd <project>; `$env:RTK_TELEMETRY_DISABLED='1'; rtk init --agent cline"
+ }
}
function Ensure-ClaudeCode {
@@ -571,7 +580,7 @@ function Ensure-Codex {
function Ensure-Pi {
$script:PiAvailable = $false
- Add-PiBinDirectories
+ Add-NpmBinDirectories
$existingPi = Get-ApplicationCommand "pi"
if ($existingPi -and ($DryRun -or (Test-PiApplication $existingPi))) {
Write-Host "Pi already found on PATH; verifying it."
@@ -581,7 +590,7 @@ function Ensure-Pi {
Write-Host "The existing 'pi' command at '$($existingPi.Source)' is not Pi Coding Agent; installing Pi."
}
Invoke-DownloadedPowerShellInstaller -Url $PiInstallUrl -Name "Pi"
- Add-PiBinDirectories
+ Add-NpmBinDirectories
if (-not $DryRun) {
$currentPi = Get-ApplicationCommand "pi"
@@ -608,7 +617,7 @@ function Convert-SemanticVersionOutput {
if ([string]::IsNullOrWhiteSpace($Output)) {
return ""
}
- if ($Output -match '(?m)^\s*(?:(?:uv|opencode)(?:\s+version)?\s+|v)?(?<version>\d+\.\d+\.\d+(?:[-+][0-9A-Za-z][0-9A-Za-z.-]*)?)(?:\s+\([^\r\n]*\))?\s*$') {
+ if ($Output -match '(?m)^\s*(?:(?:uv|opencode|cline)(?:\s+version)?\s+|v)?(?<version>\d+\.\d+\.\d+(?:[-+][0-9A-Za-z][0-9A-Za-z.-]*)?)(?:\s+\([^\r\n]*\))?\s*$') {
return $Matches["version"]
}
return ""
@@ -753,6 +762,74 @@ function Ensure-OpenCode {
Confirm-OpenCodeApplication
}
+function Get-ClineVersion {
+ param([string] $ClinePath)
+
+ $output = Invoke-Utf8NativeCapture -FilePath $ClinePath -Arguments @("--version")
+ $version = Convert-SemanticVersionOutput $output
+ if ([string]::IsNullOrWhiteSpace($version)) {
+ throw "Cline is present, but 'cline --version' did not return a valid semantic version."
+ }
+ return $version
+}
+
+function Confirm-ClineApplication {
+ if ($DryRun) {
+ Write-Host "+ cline --version"
+ return
+ }
+
+ $command = Get-ApplicationCommand "cline"
+ if (-not $command) {
+ throw "Cline was installed, but 'cline' is not available on PATH."
+ }
+ $version = Get-ClineVersion $command.Source
+ if (-not (Test-SupportedStableVersion -Version $version -Minimum $MinClineVersion)) {
+ throw "Stable Cline $MinClineVersion or newer is required; found Cline $version after installation."
+ }
+ Write-Host "Verified Cline $version."
+}
+
+function Ensure-Cline {
+ Add-NpmBinDirectories
+
+ if ($DryRun) {
+ if (Get-ApplicationCommand "cline") {
+ Write-Host "+ cline --version"
+ Write-Host "A compatible Cline will be preserved; an older version will be upgraded with cline update."
+ }
+ elseif (Get-ApplicationCommand "npm") {
+ Write-Host "+ npm install -g cline"
+ }
+ else {
+ throw "Cline installation requires npm. Install Node.js from https://nodejs.org/en/download, then rerun the installer."
+ }
+ Confirm-ClineApplication
+ return
+ }
+
+ $command = Get-ApplicationCommand "cline"
+ if ($command) {
+ $version = Get-ClineVersion $command.Source
+ if (Test-SupportedStableVersion -Version $version -Minimum $MinClineVersion) {
+ Write-Host "Cline $version already satisfies >=$MinClineVersion; leaving it unchanged."
+ return
+ }
+ Write-Host "Cline $version does not satisfy stable >=$MinClineVersion; upgrading it with Cline."
+ Invoke-NativeCommand -FilePath $command.Source -Arguments @("update")
+ }
+ else {
+ $npm = Get-ApplicationCommand "npm"
+ if (-not $npm) {
+ throw "Cline installation requires npm. Install Node.js from https://nodejs.org/en/download, then rerun the installer."
+ }
+ Invoke-NativeCommand -FilePath $npm.Source -Arguments @("install", "-g", "cline")
+ }
+
+ Add-NpmBinDirectories
+ Confirm-ClineApplication
+}
+
function Ensure-SelectedCodingAgents {
if ($script:InstallClaudeCode) {
Write-Step "Ensuring Claude Code is installed"
@@ -774,7 +851,12 @@ function Ensure-SelectedCodingAgents {
Ensure-OpenCode
}
- if ((-not $script:InstallClaudeCode) -and (-not $script:InstallCodex) -and (-not $script:PiAvailable) -and (-not $script:InstallOpenCode)) {
+ if ($script:InstallCline) {
+ Write-Step "Ensuring Cline CLI is installed"
+ Ensure-Cline
+ }
+
+ if ((-not $script:InstallClaudeCode) -and (-not $script:InstallCodex) -and (-not $script:PiAvailable) -and (-not $script:InstallOpenCode) -and (-not $script:InstallCline)) {
throw "No selected coding agent was installed. Re-run the installer and choose at least one."
}
}
@@ -929,7 +1011,7 @@ function Configure-AndConfirmFreeClaudeCode {
if ($DryRun) {
Write-Host "+ uv tool update-shell"
Write-Host "+ uv tool dir --bin"
- Write-Host "+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, fcc-pi, and fcc-opencode in the uv tool bin directory"
+ Write-Host "+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, fcc-pi, fcc-opencode, and fcc-cline in the uv tool bin directory"
Write-Host "+ fcc-server --version"
Export-FccDesktopIcon `
-DesktopCommand "<uv-tool-bin>\fcc-desktop.exe" `
@@ -956,7 +1038,7 @@ function Configure-AndConfirmFreeClaudeCode {
[IO.Path]::AltDirectorySeparatorChar
)
$installedCommands = @{}
- foreach ($commandName in @("fcc-desktop", "fcc-server", "fcc-claude", "fcc-codex", "fcc-pi", "fcc-opencode")) {
+ foreach ($commandName in @("fcc-desktop", "fcc-server", "fcc-claude", "fcc-codex", "fcc-pi", "fcc-opencode", "fcc-cline")) {
$command = Get-ApplicationCommand $commandName
if (-not $command) {
throw "Free Claude Code installation did not create '$commandName'."
@@ -1059,6 +1141,7 @@ if ((-not [string]::IsNullOrWhiteSpace($TorchBackend)) -and (-not ($VoiceLocal -
}
Add-KnownBinDirectories
+$script:InstallCline = [bool] ((Get-ApplicationCommand "cline") -or (Get-ApplicationCommand "npm"))
Write-Step "Checking for running Free Claude Code processes"
Assert-NoFccProcessesRunning
@@ -1099,4 +1182,10 @@ else {
if ($script:InstallOpenCode) {
Write-Host "Run OpenCode with: fcc-opencode"
}
+ if ($script:InstallCline) {
+ Write-Host "Run Cline with: fcc-cline"
+ }
+ else {
+ Write-Host "The fcc-cline wrapper is ready after you install Cline CLI."
+ }
}
diff --git a/scripts/install.sh b/scripts/install.sh
index 02e3266a..3b17820b 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -9,13 +9,14 @@ CODEX_INSTALL_URL="https://chatgpt.com/codex/install.sh"
PI_INSTALL_URL="https://pi.dev/install.sh"
OPENCODE_INSTALL_URL="https://opencode.ai/install"
MIN_OPENCODE_VERSION="1.18.18"
+MIN_CLINE_VERSION="3.0.55"
RTK_VERSION="0.44.2"
RTK_RELEASE_BASE_URL="https://github.com/rtk-ai/rtk/releases/download/v$RTK_VERSION"
UV_INSTALL_URL="https://astral.sh/uv/install.sh"
FCC_MACOS_BUNDLE_ID="io.github.alishahryar1.free-claude-code"
FCC_MACOS_OWNER_FILE=".free-claude-code-owner"
# Include retired entry points so updates reject older FCC processes before replacement.
-FCC_COMMANDS="fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-init free-claude-code"
+FCC_COMMANDS="fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline fcc-init free-claude-code"
dry_run=0
voice_nim=0
@@ -25,6 +26,7 @@ install_claude=1
install_codex=1
install_pi=1
install_opencode=1
+install_cline=0
enable_rtk=0
torch_backend=""
temporary_file=""
@@ -115,7 +117,18 @@ choose_coding_agents() {
install_opencode=0
fi
- if [ "$install_claude" -eq 1 ] || [ "$install_codex" -eq 1 ] || [ "$install_pi" -eq 1 ] || [ "$install_opencode" -eq 1 ]; then
+ if [ "$install_cline" -eq 1 ]; then
+ cline_default=yes
+ else
+ cline_default=no
+ fi
+ if prompt_yes_no "Install or verify Cline CLI for fcc-cline?" "$cline_default"; then
+ install_cline=1
+ else
+ install_cline=0
+ fi
+
+ if [ "$install_claude" -eq 1 ] || [ "$install_codex" -eq 1 ] || [ "$install_pi" -eq 1 ] || [ "$install_opencode" -eq 1 ] || [ "$install_cline" -eq 1 ]; then
break
fi
printf 'Select at least one coding agent.\n\n' >&4
@@ -207,7 +220,7 @@ add_known_bin_directories() {
hash -r 2>/dev/null || true
}
-add_pi_bin_directories() {
+add_npm_bin_directories() {
[ "$dry_run" -eq 0 ] || return 0
add_known_bin_directories
if command -v npm >/dev/null 2>&1; then
@@ -525,6 +538,9 @@ configure_rtk_for_selected_agents() {
if [ "$install_opencode" -eq 1 ]; then
run_rtk_init init --global --opencode
fi
+ if [ "$install_cline" -eq 1 ]; then
+ printf 'Optional for each project: cd <project> && RTK_TELEMETRY_DISABLED=1 rtk init --agent cline\n'
+ fi
}
ensure_claude() {
@@ -551,7 +567,7 @@ ensure_codex() {
ensure_pi() {
pi_available=0
- add_pi_bin_directories
+ add_npm_bin_directories
existing_pi_path=$(command -v pi 2>/dev/null || true)
if [ "$dry_run" -eq 1 ] && command -v pi >/dev/null 2>&1; then
@@ -563,7 +579,7 @@ ensure_pi() {
printf "The existing 'pi' command at %s is not Pi Coding Agent; installing Pi.\n" "$existing_pi_path"
fi
download_and_run "$PI_INSTALL_URL" sh "Pi"
- add_pi_bin_directories
+ add_npm_bin_directories
if [ "$dry_run" -eq 0 ]; then
current_pi_path=$(command -v pi 2>/dev/null || true)
@@ -642,6 +658,71 @@ ensure_opencode() {
verify_opencode_command
}
+current_cline_version() {
+ if output=$(cline --version 2>/dev/null); then
+ :
+ else
+ return 1
+ fi
+
+ version=$(printf '%s\n' "$output" | awk '
+ /^[[:space:]]*((cline( version)?[[:space:]]+)|v)?[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?[[:space:]]*$/ &&
+ match($0, /[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?/) {
+ print substr($0, RSTART, RLENGTH)
+ exit
+ }
+ ')
+ [ -n "$version" ] || return 1
+ printf '%s\n' "$version"
+}
+
+verify_cline_command() {
+ if [ "$dry_run" -eq 1 ]; then
+ print_command cline --version
+ return 0
+ fi
+
+ command -v cline >/dev/null 2>&1 || fail "Cline was installed, but 'cline' is not available on PATH."
+ version=$(current_cline_version) || fail "Cline is present, but 'cline --version' did not return a valid semantic version."
+ if ! stable_version_is_supported "$version" "$MIN_CLINE_VERSION"; then
+ fail "Stable Cline $MIN_CLINE_VERSION or newer is required; found Cline $version after installation."
+ fi
+ printf 'Verified Cline %s.\n' "$version"
+}
+
+ensure_cline() {
+ add_npm_bin_directories
+
+ if [ "$dry_run" -eq 1 ]; then
+ if command -v cline >/dev/null 2>&1; then
+ print_command cline --version
+ printf 'A compatible Cline will be preserved; an older version will be upgraded with cline update.\n'
+ elif command -v npm >/dev/null 2>&1; then
+ print_command npm install -g cline
+ else
+ fail "Cline installation requires npm. Install Node.js from https://nodejs.org/en/download, then rerun the installer."
+ fi
+ verify_cline_command
+ return 0
+ fi
+
+ if command -v cline >/dev/null 2>&1; then
+ version=$(current_cline_version) || fail "Cline is present, but 'cline --version' did not return a valid semantic version."
+ if stable_version_is_supported "$version" "$MIN_CLINE_VERSION"; then
+ printf 'Cline %s already satisfies >=%s; leaving it unchanged.\n' "$version" "$MIN_CLINE_VERSION"
+ return 0
+ fi
+ printf 'Cline %s does not satisfy stable >=%s; upgrading it with Cline.\n' "$version" "$MIN_CLINE_VERSION"
+ run cline update
+ else
+ command -v npm >/dev/null 2>&1 || fail "Cline installation requires npm. Install Node.js from https://nodejs.org/en/download, then rerun the installer."
+ run npm install -g cline
+ fi
+
+ add_npm_bin_directories
+ verify_cline_command
+}
+
ensure_selected_coding_agents() {
if [ "$install_claude" -eq 1 ]; then
step "Ensuring Claude Code is installed"
@@ -663,7 +744,12 @@ ensure_selected_coding_agents() {
ensure_opencode
fi
- if [ "$install_claude" -eq 0 ] && [ "$install_codex" -eq 0 ] && [ "$pi_available" -eq 0 ] && [ "$install_opencode" -eq 0 ]; then
+ if [ "$install_cline" -eq 1 ]; then
+ step "Ensuring Cline CLI is installed"
+ ensure_cline
+ fi
+
+ if [ "$install_claude" -eq 0 ] && [ "$install_codex" -eq 0 ] && [ "$pi_available" -eq 0 ] && [ "$install_opencode" -eq 0 ] && [ "$install_cline" -eq 0 ]; then
fail "No selected coding agent was installed. Re-run the installer and choose at least one."
fi
}
@@ -850,7 +936,7 @@ configure_and_verify_free_claude_code() {
if [ "$dry_run" -eq 1 ]; then
print_command uv tool dir --bin
- printf '+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, fcc-pi, and fcc-opencode in the uv tool bin directory\n'
+ printf '+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, fcc-pi, fcc-opencode, and fcc-cline in the uv tool bin directory\n'
print_command fcc-server --version
return 0
fi
@@ -868,7 +954,7 @@ configure_and_verify_free_claude_code() {
export PATH
hash -r 2>/dev/null || true
- for command_name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode; do
+ for command_name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline; do
[ -x "$tool_bin/$command_name" ] || fail "Free Claude Code installation did not create $tool_bin/$command_name."
done
@@ -967,6 +1053,9 @@ PLIST
parse_args "$@"
validate_args
add_known_bin_directories
+if command -v cline >/dev/null 2>&1 || command -v npm >/dev/null 2>&1; then
+ install_cline=1
+fi
step "Checking for running Free Claude Code processes"
assert_no_fcc_processes_running
@@ -1030,4 +1119,9 @@ else
if [ "$install_opencode" -eq 1 ]; then
printf 'Run OpenCode with: fcc-opencode\n'
fi
+ if [ "$install_cline" -eq 1 ]; then
+ printf 'Run Cline with: fcc-cline\n'
+ else
+ printf 'The fcc-cline wrapper is ready after you install Cline CLI.\n'
+ fi
fi
diff --git a/scripts/uninstall.ps1 b/scripts/uninstall.ps1
index 885f80d7..ae7cb5ea 100644
--- a/scripts/uninstall.ps1
+++ b/scripts/uninstall.ps1
@@ -18,6 +18,7 @@ $FccCommands = @(
"fcc-codex",
"fcc-pi",
"fcc-opencode",
+ "fcc-cline",
"fcc-init",
"free-claude-code"
)
diff --git a/scripts/uninstall.sh b/scripts/uninstall.sh
index 1c551cf9..a8f6d969 100644
--- a/scripts/uninstall.sh
+++ b/scripts/uninstall.sh
@@ -6,7 +6,7 @@ FCC_HOME_DIRNAME=".fcc"
FCC_MACOS_BUNDLE_ID="io.github.alishahryar1.free-claude-code"
FCC_MACOS_OWNER_FILE=".free-claude-code-owner"
# Include retired entry points so older installations are fully stopped and removed.
-FCC_COMMANDS="fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-init free-claude-code"
+FCC_COMMANDS="fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline fcc-init free-claude-code"
dry_run=0
uv_tool_bin=""
diff --git a/smoke/README.md b/smoke/README.md
index 49b376f3..24e1e9f2 100644
--- a/smoke/README.md
+++ b/smoke/README.md
@@ -56,7 +56,7 @@ Default targets do not send real bot messages or load voice backends:
| `api` | messages, count_tokens full payload, errors, `/stop`, optimizations | configured provider only for streaming messages |
| `auth` | canonical bearer auth, conflicting legacy headers, invalid/missing auth | none; test sets an isolated token |
| `cli` | server entrypoint, Claude CLI adaptive thinking, session cleanup | Claude CLI binary and provider only for real CLI |
-| `clients` | VS Code and JetBrains protocol payloads; Pi and OpenCode CLI prompts | configured provider; installed Pi/OpenCode binaries for their CLI scenarios |
+| `clients` | VS Code and JetBrains protocol payloads; Pi, OpenCode, and Cline CLI prompts | configured provider; installed Pi/OpenCode/Cline binaries for their CLI scenarios |
| `config` | env precedence, removed-env migration, proxy/timeouts | none |
| `extensibility` | provider runtime and platform factory construction | none |
| `messaging` | fake Discord/Telegram full flow, literal clear scopes, trees, persistence, voice cancel | none |
diff --git a/smoke/capabilities.py b/smoke/capabilities.py
index ac6f5300..e90253f4 100644
--- a/smoke/capabilities.py
+++ b/smoke/capabilities.py
@@ -514,6 +514,20 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
),
("test_opencode_cli_prompt_e2e",),
),
+ CapabilityContract(
+ "cli",
+ "cline_cli_integration",
+ "cline_cli_integration",
+ "free_claude_code.cli.launchers.cline",
+ "Cline binary, live FCC model catalog, and protected child-process files",
+ "Responses provider scoped to FCC for attached local sessions",
+ "version, detached mode, proxy, or catalog failure exits without fallback",
+ (
+ "tests/cli/test_cline_launcher.py",
+ "tests/cli/test_model_catalog.py",
+ ),
+ ("test_cline_cli_prompt_e2e",),
+ ),
CapabilityContract(
"extensibility",
"provider_platform_abcs",
diff --git a/smoke/features.py b/smoke/features.py
index 5cb0f48c..653503ef 100644
--- a/smoke/features.py
+++ b/smoke/features.py
@@ -101,6 +101,22 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
),
"skip only when OpenCode is absent; configured providers must pass",
),
+ FeatureCoverage(
+ "cline_cli_integration",
+ "Cline discovers FCC models and sends Responses through the proxy",
+ (
+ "tests/cli/test_cline_launcher.py",
+ "tests/cli/test_model_catalog.py",
+ ),
+ ("test_probe_and_models_routes",),
+ ("test_cline_cli_prompt_e2e",),
+ ("clients",),
+ (
+ "stable Cline CLI",
+ "configured provider credentials or local provider endpoint",
+ ),
+ "skip only when Cline is absent; configured providers must pass",
+ ),
FeatureCoverage(
"provider_matrix",
"Every configured provider prefix can satisfy conversation scenarios",
diff --git a/smoke/product/test_client_product_live.py b/smoke/product/test_client_product_live.py
index add95a65..33734827 100644
--- a/smoke/product/test_client_product_live.py
+++ b/smoke/product/test_client_product_live.py
@@ -189,6 +189,68 @@ def test_opencode_cli_prompt_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> N
assert "POST /v1/chat/completions" not in server_log
[email protected]_target("clients")
+def test_cline_cli_prompt_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None:
+ if not shutil.which("cline"):
+ pytest.skip("missing_env: Cline CLI not found")
+ uv_bin = shutil.which("uv")
+ if not uv_bin:
+ pytest.skip("missing_env: uv not found")
+ provider_model = ProviderMatrixDriver(smoke_config).first_model()
+ auth_token = smoke_config.settings.proxy_auth_token
+ isolated_home = tmp_path / "cline-home"
+ isolated_home.mkdir()
+
+ with SmokeServerDriver(
+ smoke_config,
+ name="product-cline-cli",
+ env_overrides={
+ "MODEL": provider_model.full_model,
+ "ANTHROPIC_AUTH_TOKEN": auth_token,
+ "MESSAGING_PLATFORM": "none",
+ },
+ ).run() as server:
+ env = os.environ.copy()
+ env.update(
+ {
+ "HOST": "127.0.0.1",
+ "PORT": str(server.port),
+ "FCC_OPEN_BROWSER": "0",
+ "ANTHROPIC_AUTH_TOKEN": auth_token,
+ "HOME": str(isolated_home),
+ "USERPROFILE": str(isolated_home),
+ }
+ )
+ env.pop("CLINE_PROVIDER_SETTINGS_PATH", None)
+ env.pop("CLINE_SESSION_BACKEND_MODE", None)
+ result = subprocess.run(
+ [
+ uv_bin,
+ "run",
+ "--project",
+ str(smoke_config.root),
+ "--no-sync",
+ "fcc-cline",
+ "--json",
+ "--model",
+ provider_model.full_model,
+ "Reply with exactly FCC_SMOKE_CLINE",
+ ],
+ cwd=tmp_path,
+ env=env,
+ check=False,
+ capture_output=True,
+ text=True,
+ timeout=smoke_config.timeout_s + 15,
+ )
+ server_log = server.log_path.read_text(encoding="utf-8", errors="replace")
+
+ assert result.returncode == 0, result.stderr or result.stdout
+ assert "FCC_SMOKE_CLINE" in result.stdout
+ assert "POST /v1/responses" in server_log
+ assert "POST /v1/chat/completions" not in server_log
+
+
@pytest.mark.smoke_target("cli")
def test_claude_cli_adaptive_thinking_e2e(
smoke_config: SmokeConfig, tmp_path: Path
diff --git a/src/free_claude_code/cli/launchers/cline.py b/src/free_claude_code/cli/launchers/cline.py
new file mode 100644
index 00000000..6ea98051
--- /dev/null
+++ b/src/free_claude_code/cli/launchers/cline.py
@@ -0,0 +1,370 @@
+"""Installed `fcc-cline` launcher for the stable Cline CLI."""
+
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Never
+
+from free_claude_code.cli.local_http import with_local_proxy_bypass
+from free_claude_code.config.loader import get_settings
+from free_claude_code.config.server_urls import local_proxy_root_url
+
+from .cline_config import CLINE_PROVIDER_ID, ClineConfig, build_cline_config
+from .common import preflight_proxy, resolve_client_binary, run_client_process
+from .model_catalog import client_models_from_response, fetch_proxy_models_response
+
+_BINARY_NAME = "cline"
+_DISPLAY_NAME = "Cline CLI"
+_INSTALL_HINT = (
+ "Install Cline from: https://docs.cline.bot/getting-started/installing-cline"
+)
+_MINIMUM_VERSION = (3, 0, 55)
+_VERSION_TIMEOUT_SECONDS = 5.0
+_VERSION_PATTERN = re.compile(
+ r"(?m)^\s*(?:cline(?:\s+version)?\s+|v)?"
+ r"(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z.-]+)?\s*$"
+)
+_PASSTHROUGH_COMMANDS = frozenset(
+ {
+ "auth",
+ "config",
+ "history",
+ "h",
+ "plugin",
+ "skill",
+ "mcp",
+ "doctor",
+ "update",
+ "version",
+ }
+)
+_PASSTHROUGH_FLAGS = frozenset({"--help", "-h", "--version", "-V", "--update"})
+_DETACHED_COMMANDS = frozenset(
+ {"connect", "schedule", "hub", "dashboard", "hook", "kanban"}
+)
+_DETACHED_FLAGS = frozenset({"--zen", "-z", "--kanban"})
+_VALUE_OPTIONS = frozenset(
+ {
+ "--auto-approve",
+ "-c",
+ "--cwd",
+ "--thinking",
+ "--compaction",
+ "--id",
+ "-P",
+ "--provider",
+ "-k",
+ "--key",
+ "-m",
+ "--model",
+ "-s",
+ "--system",
+ "-t",
+ "--timeout",
+ "--config",
+ "--data-dir",
+ "--hooks-dir",
+ "--team-name",
+ }
+)
+_OPTIONAL_VALUE_OPTIONS = frozenset({"--retries"})
+_BOOLEAN_OPTIONS = frozenset(
+ {
+ "-p",
+ "--plan",
+ "--json",
+ "-i",
+ "--tui",
+ "-z",
+ "--zen",
+ "--acp",
+ "--worktree",
+ "--update",
+ "--kanban",
+ "-v",
+ "--verbose",
+ "-a",
+ "--act",
+ "-y",
+ "--yolo",
+ "-h",
+ "--help",
+ "-V",
+ "--version",
+ }
+)
+
+
+def launch(argv: Sequence[str] | None = None) -> None:
+ """Launch one attached Cline process with an FCC-only default provider."""
+
+ args = list(sys.argv[1:] if argv is None else argv)
+ binary_path = resolve_client_binary(
+ binary_name=_BINARY_NAME,
+ display_name=_DISPLAY_NAME,
+ install_hint=_INSTALL_HINT,
+ )
+
+ if is_cline_passthrough(args):
+ _run(binary_path, args, os.environ)
+ return
+ if detached_cline_surface(args):
+ print(
+ "fcc-cline supports attached terminal sessions only. "
+ "Run this detached Cline surface with ordinary cline instead.",
+ file=sys.stderr,
+ )
+ raise SystemExit(2)
+ _reject_sandbox_override(args, os.environ)
+ _reject_routing_overrides(args)
+ require_compatible_cline(binary_path)
+
+ settings = get_settings()
+ auth_token = settings.proxy_auth_token.strip()
+ if not auth_token:
+ print("Free Claude Code proxy authentication token is empty.", file=sys.stderr)
+ raise SystemExit(1)
+
+ proxy_root_url = local_proxy_root_url(settings)
+ if error := preflight_proxy(proxy_root_url):
+ print(
+ f"Free Claude Code proxy is not reachable at {proxy_root_url}: {error}",
+ file=sys.stderr,
+ )
+ print("Start it in another terminal with: fcc-server", file=sys.stderr)
+ raise SystemExit(1)
+
+ try:
+ models = client_models_from_response(
+ fetch_proxy_models_response(proxy_root_url, auth_token)
+ )
+ config = build_cline_config(
+ models,
+ proxy_root_url=proxy_root_url,
+ auth_token=auth_token,
+ )
+ except Exception as exc:
+ print(f"Could not prepare the Cline FCC model catalog: {exc}", file=sys.stderr)
+ raise SystemExit(1) from None
+
+ _run_with_temporary_config(
+ binary_path=binary_path,
+ args=args,
+ config=config,
+ proxy_root_url=proxy_root_url,
+ )
+
+
+def is_cline_passthrough(argv: Sequence[str]) -> bool:
+ """Return whether Cline can run without FCC-owned process configuration."""
+
+ before_separator = _before_separator(argv)
+ if any(argument in _PASSTHROUGH_FLAGS for argument in before_separator):
+ return True
+ return first_root_positional(argv) in _PASSTHROUGH_COMMANDS
+
+
+def detached_cline_surface(argv: Sequence[str]) -> bool:
+ """Return whether arguments request a process that outlives this launcher."""
+
+ before_separator = _before_separator(argv)
+ if any(argument in _DETACHED_FLAGS for argument in before_separator):
+ return True
+ return first_root_positional(argv) in _DETACHED_COMMANDS
+
+
+def first_root_positional(argv: Sequence[str]) -> str | None:
+ """Find Cline's first root positional without taking over CLI parsing."""
+
+ index = 0
+ while index < len(argv):
+ argument = argv[index]
+ if argument == "--":
+ return None
+ if argument in _VALUE_OPTIONS:
+ index += 2
+ continue
+ if _is_joined_value_option(argument):
+ index += 1
+ continue
+ if argument in _OPTIONAL_VALUE_OPTIONS:
+ if index + 1 < len(argv) and not argv[index + 1].startswith("-"):
+ index += 2
+ else:
+ index += 1
+ continue
+ if argument.startswith("--retries=") or argument in _BOOLEAN_OPTIONS:
+ index += 1
+ continue
+ if argument.startswith("-"):
+ return None
+ return argument
+ return None
+
+
+def require_compatible_cline(binary_path: str) -> None:
+ """Exit unless the installed Cline satisfies FCC's released contract."""
+
+ version = cline_binary_version(binary_path)
+ if version is not None and version >= _MINIMUM_VERSION:
+ return
+
+ minimum = ".".join(str(part) for part in _MINIMUM_VERSION)
+ print(
+ f"The Cline CLI at {binary_path} must be a stable release at least version {minimum}.",
+ file=sys.stderr,
+ )
+ print("Upgrade it with: cline update", file=sys.stderr)
+ raise SystemExit(126)
+
+
+def cline_binary_version(binary_path: str) -> tuple[int, int, int] | None:
+ """Read a stable semantic Cline version without invoking a shell."""
+
+ try:
+ result = subprocess.run(
+ [binary_path, "--version"],
+ check=False,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ text=True,
+ timeout=_VERSION_TIMEOUT_SECONDS,
+ )
+ except OSError, subprocess.TimeoutExpired:
+ return None
+ if result.returncode != 0:
+ return None
+
+ match = _VERSION_PATTERN.search(result.stdout)
+ if match is None:
+ return None
+ return int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+
+def build_cline_launcher_env(
+ *,
+ proxy_root_url: str,
+ providers_path: Path,
+ base_env: Mapping[str, str],
+) -> dict[str, str]:
+ """Build the child-only Cline environment while preserving native state."""
+
+ env = with_local_proxy_bypass(base_env, proxy_root_url=proxy_root_url)
+ env["CLINE_PROVIDER_SETTINGS_PATH"] = str(providers_path)
+ env["CLINE_SESSION_BACKEND_MODE"] = "local"
+ return env
+
+
+def _run_with_temporary_config(
+ *,
+ binary_path: str,
+ args: Sequence[str],
+ config: ClineConfig,
+ proxy_root_url: str,
+) -> None:
+ try:
+ temp_config = tempfile.TemporaryDirectory(prefix="fcc-cline-")
+ except OSError as exc:
+ _temporary_config_error(exc)
+
+ with temp_config as temp_directory:
+ settings_directory = Path(temp_directory, "settings")
+ providers_path = settings_directory / "providers.json"
+ models_path = settings_directory / "models.json"
+ try:
+ settings_directory.mkdir(mode=0o700)
+ _write_private_json(providers_path, config.providers)
+ _write_private_json(models_path, config.models)
+ except OSError as exc:
+ _temporary_config_error(exc)
+
+ _run(
+ binary_path,
+ ["--provider", CLINE_PROVIDER_ID, *args],
+ build_cline_launcher_env(
+ proxy_root_url=proxy_root_url,
+ providers_path=providers_path,
+ base_env=os.environ,
+ ),
+ )
+
+
+def _write_private_json(path: Path, payload: Mapping[str, object]) -> None:
+ descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+ with os.fdopen(descriptor, "w", encoding="utf-8") as output:
+ json.dump(payload, output, ensure_ascii=True, indent=2)
+ output.write("\n")
+
+
+def _run(binary_path: str, args: Sequence[str], env: Mapping[str, str]) -> None:
+ run_client_process(
+ command=[binary_path, *args],
+ env=env,
+ binary_name=_BINARY_NAME,
+ display_name=_DISPLAY_NAME,
+ install_hint=_INSTALL_HINT,
+ )
+
+
+def _reject_routing_overrides(argv: Sequence[str]) -> None:
+ for argument in _before_separator(argv):
+ if (
+ argument in {"-P", "--provider", "-k", "--key"}
+ or argument.startswith(("--provider=", "--key="))
+ or (argument.startswith(("-P", "-k")) and len(argument) > 2)
+ ):
+ print(
+ "fcc-cline owns the Cline provider and API key. "
+ "Use ordinary cline for a different provider.",
+ file=sys.stderr,
+ )
+ raise SystemExit(2)
+
+
+def _reject_sandbox_override(argv: Sequence[str], base_env: Mapping[str, str]) -> None:
+ has_data_dir = any(
+ argument == "--data-dir" or argument.startswith("--data-dir=")
+ for argument in _before_separator(argv)
+ )
+ sandbox_enabled = base_env.get("CLINE_SANDBOX", "").strip() == "1"
+ if not has_data_dir and not sandbox_enabled:
+ return
+
+ print(
+ "fcc-cline cannot use Cline sandbox data overrides because Cline replaces "
+ "the ephemeral FCC provider file in that mode. Use ordinary cline for "
+ "--data-dir or CLINE_SANDBOX=1.",
+ file=sys.stderr,
+ )
+ raise SystemExit(2)
+
+
+def _before_separator(argv: Sequence[str]) -> Sequence[str]:
+ try:
+ return argv[: argv.index("--")]
+ except ValueError:
+ return argv
+
+
+def _is_joined_value_option(argument: str) -> bool:
+ if any(
+ argument.startswith(f"{option}=")
+ for option in _VALUE_OPTIONS
+ if option.startswith("--")
+ ):
+ return True
+ return any(
+ argument.startswith(option) and len(argument) > len(option)
+ for option in _VALUE_OPTIONS
+ if option.startswith("-") and not option.startswith("--")
+ )
+
+
+def _temporary_config_error(exc: OSError) -> Never:
+ print(f"Could not create temporary Cline configuration: {exc}", file=sys.stderr)
+ raise SystemExit(1) from None
diff --git a/src/free_claude_code/cli/launchers/cline_config.py b/src/free_claude_code/cli/launchers/cline_config.py
new file mode 100644
index 00000000..3b7d23b0
--- /dev/null
+++ b/src/free_claude_code/cli/launchers/cline_config.py
@@ -0,0 +1,92 @@
+"""Process-local Cline CLI configuration for FCC model routing."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from free_claude_code.core.json_types import JsonObject
+
+from .common import proxy_v1_url
+from .model_catalog import ClientModel
+
+# Cline's released session gateway only instantiates built-in providers. FCC
+# replaces this process-local Responses provider's endpoint and catalog instead
+# of creating a custom provider that the picker can see but inference cannot.
+CLINE_PROVIDER_ID = "openai-native"
+
+
+@dataclass(frozen=True, slots=True)
+class ClineConfig:
+ """Private provider settings and model registry for one Cline process."""
+
+ providers: JsonObject = field(repr=False)
+ models: JsonObject = field(repr=False)
+
+
+def build_cline_config(
+ models: tuple[ClientModel, ...],
+ *,
+ proxy_root_url: str,
+ auth_token: str,
+ now: datetime | None = None,
+) -> ClineConfig:
+ """Translate a non-empty FCC model snapshot into Cline's file contracts."""
+
+ if not models:
+ raise ValueError("Cline requires at least one routable FCC model")
+
+ timestamp = (
+ (now or datetime.now(UTC)).astimezone(UTC).isoformat().replace("+00:00", "Z")
+ )
+ default_model = models[0].wire_slug
+ provider_settings: JsonObject = {
+ "provider": CLINE_PROVIDER_ID,
+ "apiKey": auth_token,
+ "model": default_model,
+ "protocol": "openai-responses",
+ "baseUrl": proxy_v1_url(proxy_root_url),
+ "capabilities": ["streaming", "tools"],
+ }
+ model_entries: JsonObject = {
+ model.wire_slug: {
+ "name": model.display_name,
+ "capabilities": [
+ "streaming",
+ "tools",
+ *(["reasoning"] if model.allows_reasoning else []),
+ ],
+ "supportsReasoning": model.allows_reasoning,
+ "apiFormat": "openai-responses",
+ }
+ for model in models
+ }
+
+ return ClineConfig(
+ providers={
+ "version": 1,
+ "modes": {},
+ "lastUsedProvider": CLINE_PROVIDER_ID,
+ "providers": {
+ CLINE_PROVIDER_ID: {
+ "settings": provider_settings,
+ "updatedAt": timestamp,
+ "tokenSource": "manual",
+ }
+ },
+ },
+ models={
+ "version": 1,
+ "providers": {
+ CLINE_PROVIDER_ID: {
+ "provider": {
+ "name": "Free Claude Code",
+ "baseUrl": proxy_v1_url(proxy_root_url),
+ "defaultModelId": default_model,
+ "protocol": "openai-responses",
+ "client": "openai",
+ "capabilities": ["streaming", "tools"],
+ },
+ "models": model_entries,
+ }
+ },
+ },
+ )
diff --git a/src/free_claude_code/cli/launchers/common.py b/src/free_claude_code/cli/launchers/common.py
index 6ff8e9a7..a2886454 100644
--- a/src/free_claude_code/cli/launchers/common.py
+++ b/src/free_claude_code/cli/launchers/common.py
@@ -18,6 +18,13 @@ PROXY_PREFLIGHT_PATH = "/health"
PROXY_PREFLIGHT_TIMEOUT_SECONDS = 1.5
+def proxy_v1_url(proxy_root_url: str) -> str:
+ """Return the canonical local proxy API root for client launchers."""
+
+ stripped = proxy_root_url.rstrip("/")
+ return stripped if stripped.endswith("/v1") else f"{stripped}/v1"
+
+
def preflight_proxy(proxy_root_url: str) -> str | None:
"""Return an error message when the local proxy health check is unreachable."""
diff --git a/src/free_claude_code/cli/launchers/opencode_config.py b/src/free_claude_code/cli/launchers/opencode_config.py
index 9f410096..a8727d87 100644
--- a/src/free_claude_code/cli/launchers/opencode_config.py
+++ b/src/free_claude_code/cli/launchers/opencode_config.py
@@ -4,6 +4,7 @@ from dataclasses import dataclass
from free_claude_code.core.json_types import JsonObject
+from .common import proxy_v1_url
from .model_catalog import ClientModel
OPENCODE_API_KEY_ENV = "FCC_OPENCODE_API_KEY"
@@ -37,7 +38,7 @@ def build_opencode_config(
"name": "Free Claude Code",
"npm": "@ai-sdk/openai",
"options": {
- "baseURL": _ensure_v1_url(proxy_root_url),
+ "baseURL": proxy_v1_url(proxy_root_url),
"apiKey": f"{{env:{OPENCODE_API_KEY_ENV}}}",
},
}
@@ -60,8 +61,3 @@ def build_opencode_config(
"small_model": default_model,
},
)
-
-
-def _ensure_v1_url(url: str) -> str:
- stripped = url.rstrip("/")
- return stripped if stripped.endswith("/v1") else f"{stripped}/v1"
diff --git a/tests/cli/test_cline_launcher.py b/tests/cli/test_cline_launcher.py
new file mode 100644
index 00000000..7272b472
--- /dev/null
+++ b/tests/cli/test_cline_launcher.py
@@ -0,0 +1,563 @@
+"""Contract tests for the installed `fcc-cline` launcher."""
+
+import json
+import os
+import subprocess
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from free_claude_code.cli.launchers.cline_config import (
+ CLINE_PROVIDER_ID,
+ build_cline_config,
+)
+from free_claude_code.cli.launchers.model_catalog import ClientModel
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.json_types import JsonObject
+
+
+def _settings(*, token: str = "proxy-token") -> Settings:
+ return Settings(
+ host="0.0.0.0",
+ port=9191,
+ proxy_auth_enabled=False,
+ proxy_auth_token=token,
+ model="nvidia_nim/test-model",
+ )
+
+
+def _models_payload() -> JsonObject:
+ return {
+ "data": [
+ {
+ "id": "anthropic/nvidia_nim/vendor/model",
+ "display_name": "Nested model",
+ },
+ {
+ "id": "claude-3-freecc-no-thinking/open_router/plain-model",
+ "display_name": "No-thinking model",
+ },
+ ]
+ }
+
+
+def test_cline_config_uses_responses_and_only_known_metadata() -> None:
+ config = build_cline_config(
+ (
+ ClientModel(
+ wire_slug="nvidia_nim/vendor/model",
+ provider_model_ref="nvidia_nim/vendor/model",
+ display_name="Nested model",
+ allows_reasoning=True,
+ ),
+ ClientModel(
+ wire_slug="claude-3-freecc-no-thinking/open_router/plain-model",
+ provider_model_ref="open_router/plain-model",
+ display_name="No-thinking model",
+ allows_reasoning=False,
+ ),
+ ),
+ proxy_root_url="http://127.0.0.1:9191/",
+ auth_token="proxy-token",
+ now=datetime(2026, 8, 15, 12, 30, tzinfo=UTC),
+ )
+
+ assert config.providers == {
+ "version": 1,
+ "modes": {},
+ "lastUsedProvider": "openai-native",
+ "providers": {
+ "openai-native": {
+ "settings": {
+ "provider": "openai-native",
+ "apiKey": "proxy-token",
+ "model": "nvidia_nim/vendor/model",
+ "protocol": "openai-responses",
+ "baseUrl": "http://127.0.0.1:9191/v1",
+ "capabilities": ["streaming", "tools"],
+ },
+ "updatedAt": "2026-08-15T12:30:00Z",
+ "tokenSource": "manual",
+ }
+ },
+ }
+ assert config.models == {
+ "version": 1,
+ "providers": {
+ "openai-native": {
+ "provider": {
+ "name": "Free Claude Code",
+ "baseUrl": "http://127.0.0.1:9191/v1",
+ "defaultModelId": "nvidia_nim/vendor/model",
+ "protocol": "openai-responses",
+ "client": "openai",
+ "capabilities": ["streaming", "tools"],
+ },
+ "models": {
+ "nvidia_nim/vendor/model": {
+ "name": "Nested model",
+ "capabilities": ["streaming", "tools", "reasoning"],
+ "supportsReasoning": True,
+ "apiFormat": "openai-responses",
+ },
+ "claude-3-freecc-no-thinking/open_router/plain-model": {
+ "name": "No-thinking model",
+ "capabilities": ["streaming", "tools"],
+ "supportsReasoning": False,
+ "apiFormat": "openai-responses",
+ },
+ },
+ }
+ },
+ }
+ serialized = json.dumps(config.providers | config.models)
+ assert "contextWindow" not in serialized
+ assert "maxTokens" not in serialized
+ assert "reasoningEffort" not in serialized
+ assert "proxy-token" not in repr(config)
+
+
+def test_cline_config_rejects_empty_model_catalog() -> None:
+ with pytest.raises(ValueError, match="at least one"):
+ build_cline_config(
+ (),
+ proxy_root_url="http://127.0.0.1:9191",
+ auth_token="proxy-token",
+ )
+
+
+ "argv",
+ [
+ ["--help"],
+ ["--verbose", "--version"],
+ ["auth", "login"],
+ ["--config", "elsewhere", "config"],
+ ["history"],
+ ["h"],
+ ["plugin", "list"],
+ ["skill", "list"],
+ ["mcp", "list"],
+ ["doctor"],
+ ["update"],
+ ["version"],
+ ],
+)
+def test_cline_management_commands_are_native_passthrough(argv: list[str]) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ assert cline.is_cline_passthrough(argv)
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "get_settings") as get_settings,
+ patch.object(cline, "require_compatible_cline") as require_version,
+ patch.object(cline, "run_client_process") as run_client_process,
+ ):
+ cline.launch(argv)
+
+ assert run_client_process.call_args.kwargs["command"] == [
+ "resolved-cline",
+ *argv,
+ ]
+ get_settings.assert_not_called()
+ require_version.assert_not_called()
+
+
+ "argv",
+ [
+ ["connect", "discord"],
+ ["--cwd", "workspace", "schedule", "list"],
+ ["hub", "start"],
+ ["dashboard"],
+ ["hook"],
+ ["kanban"],
+ ["--zen", "prompt"],
+ ["-z", "prompt"],
+ ["--kanban"],
+ ],
+)
+def test_cline_detached_surfaces_are_rejected_before_fcc_calls(
+ argv: list[str], capsys: pytest.CaptureFixture[str]
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "get_settings") as get_settings,
+ patch.object(cline, "require_compatible_cline") as require_version,
+ patch.object(cline, "run_client_process") as run_client_process,
+ pytest.raises(SystemExit) as exc_info,
+ ):
+ cline.launch(argv)
+
+ assert exc_info.value.code == 2
+ assert "attached terminal sessions only" in capsys.readouterr().err
+ get_settings.assert_not_called()
+ require_version.assert_not_called()
+ run_client_process.assert_not_called()
+
+
+ "argv",
+ [
+ ["-P", "openrouter", "prompt"],
+ ["-Popenrouter", "prompt"],
+ ["--provider", "openrouter", "prompt"],
+ ["--provider=openrouter", "prompt"],
+ ["-k", "secret", "prompt"],
+ ["-ksecret", "prompt"],
+ ["--key", "secret", "prompt"],
+ ["--key=secret", "prompt"],
+ ],
+)
+def test_cline_rejects_caller_owned_routing(argv: list[str]) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "require_compatible_cline") as require_version,
+ pytest.raises(SystemExit) as exc_info,
+ ):
+ cline.launch(argv)
+
+ assert exc_info.value.code == 2
+ require_version.assert_not_called()
+
+
+ ("argv", "sandbox_env"),
+ [
+ (["--data-dir", "isolated", "prompt"], None),
+ (["--data-dir=isolated", "prompt"], None),
+ (["prompt"], "1"),
+ ],
+)
+def test_cline_rejects_sandbox_overrides_that_replace_ephemeral_credentials(
+ argv: list[str],
+ sandbox_env: str | None,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ if sandbox_env is None:
+ monkeypatch.delenv("CLINE_SANDBOX", raising=False)
+ else:
+ monkeypatch.setenv("CLINE_SANDBOX", sandbox_env)
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "require_compatible_cline") as require_version,
+ patch.object(cline, "run_client_process") as run_client_process,
+ pytest.raises(SystemExit) as exc_info,
+ ):
+ cline.launch(argv)
+
+ assert exc_info.value.code == 2
+ assert "replaces the ephemeral FCC provider file" in capsys.readouterr().err
+ require_version.assert_not_called()
+ run_client_process.assert_not_called()
+
+
+ ("argv", "expected"),
+ [
+ ([], None),
+ (["prompt"], "prompt"),
+ (["--cwd", "workspace", "prompt"], "prompt"),
+ (["--cwd=workspace", "prompt"], "prompt"),
+ (["-cworkspace", "prompt"], "prompt"),
+ (["--retries", "4", "prompt"], "prompt"),
+ (["--retries=4", "prompt"], "prompt"),
+ (["--verbose", "doctor"], "doctor"),
+ (["--unknown", "hub"], None),
+ (["--", "hub"], None),
+ ],
+)
+def test_cline_root_positional_scanner(argv: list[str], expected: str | None) -> None:
+ from free_claude_code.cli.launchers.cline import first_root_positional
+
+ assert first_root_positional(argv) == expected
+
+
+ ("output", "return_code", "expected"),
+ [
+ ("3.0.55\n", 0, (3, 0, 55)),
+ ("cline version 3.1.0\n", 0, (3, 1, 0)),
+ ("v3.1.0+release.1\n", 0, (3, 1, 0)),
+ ("3.1.0-beta.1\n", 0, None),
+ ("unexpected 3.1.0\n", 0, None),
+ ("3.1.0\n", 1, None),
+ ],
+)
+def test_cline_version_probe(
+ output: str,
+ return_code: int,
+ expected: tuple[int, int, int] | None,
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with patch.object(
+ cline.subprocess,
+ "run",
+ return_value=SimpleNamespace(stdout=output, returncode=return_code),
+ ):
+ assert cline.cline_binary_version("resolved-cline") == expected
+
+
+def test_cline_version_probe_handles_timeout() -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with patch.object(
+ cline.subprocess,
+ "run",
+ side_effect=subprocess.TimeoutExpired("cline", 5),
+ ):
+ assert cline.cline_binary_version("resolved-cline") is None
+
+
+def test_cline_rejects_incompatible_version_with_update_hint(
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with (
+ patch.object(cline, "cline_binary_version", return_value=(3, 0, 54)),
+ pytest.raises(SystemExit) as exc_info,
+ ):
+ cline.require_compatible_cline("resolved-cline")
+
+ assert exc_info.value.code == 126
+ captured = capsys.readouterr()
+ assert "at least version 3.0.55" in captured.err
+ assert "cline update" in captured.err
+
+
+def test_cline_child_env_is_process_local_and_preserves_native_state(
+ tmp_path: Path,
+) -> None:
+ from free_claude_code.cli.launchers.cline import build_cline_launcher_env
+
+ providers_path = tmp_path / "settings" / "providers.json"
+ env = build_cline_launcher_env(
+ proxy_root_url="http://127.0.0.1:9191",
+ providers_path=providers_path,
+ base_env={
+ "PATH": "keep",
+ "CLINE_PROVIDER_SETTINGS_PATH": "stale-provider-file",
+ "CLINE_SESSION_BACKEND_MODE": "hub",
+ "CLINE_DATA_DIR": "keep-user-state",
+ "CLINE_CONFIG_DIR": "keep-user-config",
+ "HTTP_PROXY": "http://proxy.example",
+ },
+ )
+
+ assert env["PATH"] == "keep"
+ assert env["CLINE_PROVIDER_SETTINGS_PATH"] == str(providers_path)
+ assert env["CLINE_SESSION_BACKEND_MODE"] == "local"
+ assert env["CLINE_DATA_DIR"] == "keep-user-state"
+ assert env["CLINE_CONFIG_DIR"] == "keep-user-config"
+ assert env["HTTP_PROXY"] == "http://proxy.example"
+ assert env["NO_PROXY"] == "127.0.0.1,localhost,::1"
+ assert env["no_proxy"] == env["NO_PROXY"]
+
+
+def test_cline_launch_uses_private_ephemeral_files_and_preserves_model_flag(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ monkeypatch.setenv("CLINE_DATA_DIR", "keep-native-state")
+ observed_providers_path: Path | None = None
+ observed_models_path: Path | None = None
+
+ def observe_process(
+ *,
+ command: list[str],
+ env: Mapping[str, str],
+ binary_name: str,
+ display_name: str,
+ install_hint: str,
+ ) -> None:
+ nonlocal observed_providers_path, observed_models_path
+ del binary_name, display_name, install_hint
+ assert command == [
+ "resolved-cline",
+ "--provider",
+ CLINE_PROVIDER_ID,
+ "--model",
+ "open_router/chosen/model",
+ "hello",
+ ]
+ observed_providers_path = Path(env["CLINE_PROVIDER_SETTINGS_PATH"])
+ observed_models_path = observed_providers_path.with_name("models.json")
+ providers = json.loads(observed_providers_path.read_text(encoding="utf-8"))
+ models = json.loads(observed_models_path.read_text(encoding="utf-8"))
+ settings = providers["providers"][CLINE_PROVIDER_ID]["settings"]
+ assert settings["apiKey"] == "proxy-token"
+ assert settings["protocol"] == "openai-responses"
+ assert settings["baseUrl"] == "http://127.0.0.1:9191/v1"
+ assert (
+ "nvidia_nim/vendor/model"
+ in models["providers"][CLINE_PROVIDER_ID]["models"]
+ )
+ assert env["CLINE_SESSION_BACKEND_MODE"] == "local"
+ assert env["CLINE_DATA_DIR"] == "keep-native-state"
+
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "require_compatible_cline"),
+ patch.object(cline, "get_settings", return_value=_settings()),
+ patch.object(cline, "preflight_proxy", return_value=None),
+ patch.object(
+ cline,
+ "fetch_proxy_models_response",
+ return_value=_models_payload(),
+ ) as fetch_models,
+ patch.object(cline, "run_client_process", side_effect=observe_process),
+ ):
+ cline.launch(["--model", "open_router/chosen/model", "hello"])
+
+ fetch_models.assert_called_once_with("http://127.0.0.1:9191", "proxy-token")
+ assert observed_providers_path is not None
+ assert observed_models_path is not None
+ assert not observed_providers_path.exists()
+ assert not observed_models_path.exists()
+
+
+def test_cline_fails_closed_when_proxy_is_unreachable(
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "require_compatible_cline"),
+ patch.object(cline, "get_settings", return_value=_settings()),
+ patch.object(cline, "preflight_proxy", return_value="connection refused"),
+ patch.object(cline, "fetch_proxy_models_response") as fetch_models,
+ patch.object(cline, "run_client_process") as run_client_process,
+ pytest.raises(SystemExit) as exc_info,
+ ):
+ cline.launch(["hello"])
+
+ assert exc_info.value.code == 1
+ assert "fcc-server" in capsys.readouterr().err
+ fetch_models.assert_not_called()
+ run_client_process.assert_not_called()
+
+
+def test_cline_fails_closed_when_catalog_has_no_routable_models(
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "require_compatible_cline"),
+ patch.object(cline, "get_settings", return_value=_settings()),
+ patch.object(cline, "preflight_proxy", return_value=None),
+ patch.object(
+ cline,
+ "fetch_proxy_models_response",
+ return_value={"data": [{"id": "claude-opus-4-20250514"}]},
+ ),
+ patch.object(cline, "run_client_process") as run_client_process,
+ pytest.raises(SystemExit) as exc_info,
+ ):
+ cline.launch(["hello"])
+
+ assert exc_info.value.code == 1
+ assert "at least one routable FCC model" in capsys.readouterr().err
+ run_client_process.assert_not_called()
+
+
+def test_cline_rejects_empty_proxy_token_before_network_calls(
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "require_compatible_cline"),
+ patch.object(
+ cline,
+ "get_settings",
+ return_value=SimpleNamespace(
+ host="0.0.0.0",
+ port=9191,
+ proxy_auth_token=" ",
+ ),
+ ),
+ patch.object(cline, "preflight_proxy") as preflight_proxy,
+ patch.object(cline, "run_client_process") as run_client_process,
+ pytest.raises(SystemExit) as exc_info,
+ ):
+ cline.launch([])
+
+ assert exc_info.value.code == 1
+ assert "token is empty" in capsys.readouterr().err
+ preflight_proxy.assert_not_called()
+ run_client_process.assert_not_called()
+
+
+def test_cline_reports_temporary_config_creation_failure(
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "require_compatible_cline"),
+ patch.object(cline, "get_settings", return_value=_settings()),
+ patch.object(cline, "preflight_proxy", return_value=None),
+ patch.object(
+ cline, "fetch_proxy_models_response", return_value=_models_payload()
+ ),
+ patch.object(
+ cline.tempfile,
+ "TemporaryDirectory",
+ side_effect=OSError("temporary directory unavailable"),
+ ),
+ patch.object(cline, "run_client_process") as run_client_process,
+ pytest.raises(SystemExit) as exc_info,
+ ):
+ cline.launch(["hello"])
+
+ assert exc_info.value.code == 1
+ assert "temporary directory unavailable" in capsys.readouterr().err
+ run_client_process.assert_not_called()
+
+
+ os.name == "nt", reason="POSIX file modes are not enforced on Windows"
+)
+def test_cline_provider_file_is_owner_only(monkeypatch: pytest.MonkeyPatch) -> None:
+ from free_claude_code.cli.launchers import cline
+
+ observed_mode: int | None = None
+
+ def observe_process(**kwargs: object) -> None:
+ nonlocal observed_mode
+ env = kwargs["env"]
+ assert isinstance(env, Mapping)
+ observed_mode = Path(env["CLINE_PROVIDER_SETTINGS_PATH"]).stat().st_mode & 0o777
+
+ with (
+ patch.object(cline, "resolve_client_binary", return_value="resolved-cline"),
+ patch.object(cline, "require_compatible_cline"),
+ patch.object(cline, "get_settings", return_value=_settings()),
+ patch.object(cline, "preflight_proxy", return_value=None),
+ patch.object(
+ cline, "fetch_proxy_models_response", return_value=_models_payload()
+ ),
+ patch.object(cline, "run_client_process", side_effect=observe_process),
+ ):
+ cline.launch(["hello"])
+
+ assert observed_mode == 0o600
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index 800e14d8..66ac8049 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -65,6 +65,7 @@ def test_cli_scripts_are_registered() -> None:
"fcc-codex": "free_claude_code.cli.launchers.codex:launch",
"fcc-pi": "free_claude_code.cli.launchers.pi:launch",
"fcc-opencode": "free_claude_code.cli.launchers.opencode:launch",
+ "fcc-cline": "free_claude_code.cli.launchers.cline:launch",
}
assert pyproject["project"]["gui-scripts"] == {
"fcc-desktop": "free_claude_code.cli.desktop_entrypoint:launch",
diff --git a/tests/scripts/test_installers.py b/tests/scripts/test_installers.py
index aaa15a2b..32df3ecc 100644
--- a/tests/scripts/test_installers.py
+++ b/tests/scripts/test_installers.py
@@ -18,6 +18,7 @@ FCC_COMMANDS = (
"fcc-codex",
"fcc-pi",
"fcc-opencode",
+ "fcc-cline",
"fcc-init",
"free-claude-code",
)
@@ -48,7 +49,7 @@ def _braced_body(text: str, declaration: str) -> str:
def _posix_command(name: str) -> str:
- version = "1.18.18" if name == "opencode" else "1.0.0"
+ version = {"opencode": "1.18.18", "cline": "3.0.55"}.get(name, "1.0.0")
help_output = (
' echo " --extension, -e <path> Load an extension"\n'
' echo " --models <patterns> Scope models"'
@@ -72,6 +73,13 @@ fi
def _posix_npm_command() -> str:
return """#!/bin/sh
echo "npm:$*" >> "$CALL_LOG"
+if [ "${1:-}" = "install" ] && [ "${2:-}" = "-g" ] && [ "${3:-}" = "cline" ]; then
+ [ "$FAIL_STEP" = "cline-install" ] && exit 72
+ mkdir -p "$FAKE_NPM_PREFIX/bin"
+ cp "$FAKE_FIXTURES/cline-command.sh" "$FAKE_NPM_PREFIX/bin/cline"
+ chmod +x "$FAKE_NPM_PREFIX/bin/cline"
+ exit 0
+fi
if [ "${1:-}" = "prefix" ] && [ "${2:-}" = "-g" ]; then
printf '%s\n' "$FAKE_NPM_PREFIX"
exit 0
@@ -107,6 +115,7 @@ if [ "${{1:-}}" = "tool" ] && [ "${{2:-}}" = "install" ]; then
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-claude"
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-pi"
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-opencode"
+ cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-cline"
if [ "$FAIL_STEP" != "fcc-missing" ]; then
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-codex"
fi
@@ -378,6 +387,7 @@ chmod +x "$HOME/.local/bin/uv"
_write_executable(fixtures / "codex-command.sh", _posix_command("codex"))
_write_executable(fixtures / "pi-command.sh", _posix_command("pi"))
_write_executable(fixtures / "opencode-command.sh", _posix_command("opencode"))
+ _write_executable(fixtures / "cline-command.sh", _posix_command("cline"))
rtk_command = _posix_rtk_command().encode()
with tarfile.open(
fixtures / "rtk-x86_64-unknown-linux-musl.tar.gz", "w:gz"
@@ -415,6 +425,9 @@ esac
""",
)
_write_executable(bin_dir / "opencode", _posix_command("opencode"))
+ npm_prefix = tmp_path / "npm-prefix"
+ npm_prefix.mkdir()
+ _write_executable(bin_dir / "npm", _posix_npm_command())
_write_executable(
bin_dir / "sha256sum",
"""#!/bin/sh
@@ -440,6 +453,7 @@ printf '%s %s\n' "$checksum" "$1"
"FCC_RUNNING_COMMAND": "",
"FCC_RUNNING_PHASE": "early",
"FAKE_UNAME": "Linux",
+ "FAKE_NPM_PREFIX": str(npm_prefix),
"CLAUDE_CONFIG_DIR": "",
"FAIL_STEP": "",
}
@@ -459,6 +473,7 @@ def test_install_sh_fresh_install_is_verified(posix_harness: PosixHarness) -> No
assert calls.index("codex-install:1") < calls.index("codex:--version")
assert calls.index("pi-install") < calls.index("pi:--version")
assert calls.index("opencode-install") < calls.index("opencode:--version")
+ assert calls.index("npm:install -g cline") < calls.index("cline:--version")
assert calls.index("uv-install") < calls.index("uv:--version")
assert any(
call.startswith(
@@ -562,7 +577,7 @@ def test_install_sh_preserves_existing_rtk_and_configures_only_selected_agent(
) -> None:
posix_harness.add_rtk()
- result = posix_harness.run_interactive("n\ny\nn\nn\ny\n")
+ result = posix_harness.run_interactive("n\ny\nn\nn\nn\ny\n")
assert result.returncode == 0, result.stdout
assert "verifying it without updating it" in result.stdout
@@ -609,7 +624,7 @@ def test_install_sh_stops_when_rtk_setup_fails(
def test_install_sh_reprompts_then_installs_only_selected_agent(
posix_harness: PosixHarness,
) -> None:
- result = posix_harness.run_interactive("n\nn\nn\nn\nn\ny\nn\nn\nn\n")
+ result = posix_harness.run_interactive("n\nn\nn\nn\nn\nn\ny\nn\nn\nn\nn\n")
assert result.returncode == 0, result.stdout
assert "Select at least one coding agent." in result.stdout
@@ -617,6 +632,7 @@ def test_install_sh_reprompts_then_installs_only_selected_agent(
assert "Run Claude Code with: fcc-claude" not in result.stdout
assert "Run Pi with: fcc-pi" not in result.stdout
assert "Run OpenCode with: fcc-opencode" not in result.stdout
+ assert "Run Cline with: fcc-cline" not in result.stdout
calls = posix_harness.calls()
assert "codex-install:1" in calls
assert not any("claude.ai" in call for call in calls)
@@ -627,7 +643,7 @@ def test_install_sh_reprompts_then_installs_only_selected_agent(
def test_install_sh_rejects_uninstalled_only_selection(
posix_harness: PosixHarness,
) -> None:
- result = posix_harness.run_interactive("n\nn\ny\nn\nn\n", fail_step="pi-skip")
+ result = posix_harness.run_interactive("n\nn\ny\nn\nn\nn\n", fail_step="pi-skip")
assert result.returncode != 0
assert "No selected coding agent was installed." in result.stdout
@@ -727,6 +743,7 @@ def test_install_sh_preserves_valid_existing_tools(
posix_harness.add_client("claude")
posix_harness.add_client("codex")
posix_harness.add_client("pi")
+ posix_harness.add_client("cline")
posix_harness.add_uv(uv_version)
result = posix_harness.run()
@@ -866,6 +883,8 @@ def test_install_sh_replaces_prerelease_uv(
"opencode-download",
"opencode-install",
"opencode-verify",
+ "cline-install",
+ "cline-verify",
"uv-download",
"uv-install",
"uv-verify",
@@ -898,6 +917,8 @@ def test_install_sh_stops_without_success_on_each_failure(
"opencode-download": "opencode-install",
"opencode-install": "opencode:--version",
"opencode-verify": "astral.sh",
+ "cline-install": "cline:--version",
+ "cline-verify": "astral.sh",
"uv-download": "uv-install",
"uv-install": "uv:--version",
"uv-verify": "uv:tool install",
@@ -1161,7 +1182,7 @@ def _windows_shortcut_icon(
def _batch_client(name: str) -> str:
- version = "1.18.18" if name == "opencode" else "1.0.0"
+ version = {"opencode": "1.18.18", "cline": "3.0.55"}.get(name, "1.0.0")
help_output = (
"echo --extension, -e ^<path^> Load an extension\n"
"echo --models ^<patterns^> Scope models"
@@ -1182,9 +1203,15 @@ exit /b 0
def _batch_npm() -> str:
return r"""@echo off
echo npm:%*>>"%CALL_LOG%"
+if "%1"=="install" if "%2"=="-g" if "%3"=="cline" goto install_cline
if "%1"=="prefix" if "%2"=="-g" echo %FAKE_NPM_PREFIX%& exit /b 0
if "%1"=="config" if "%2"=="get" if "%3"=="prefix" echo %FAKE_NPM_PREFIX%& exit /b 0
exit /b 71
+:install_cline
+if "%FAIL_STEP%"=="cline-install" exit /b 72
+if not exist "%FAKE_NPM_PREFIX%" mkdir "%FAKE_NPM_PREFIX%"
+copy /y "%FAKE_FIXTURES%\cline-command.cmd" "%FAKE_NPM_PREFIX%\cline.cmd" >nul
+exit /b 0
"""
@@ -1209,6 +1236,7 @@ copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-desktop.cmd" >nul
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-claude.cmd" >nul
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-pi.cmd" >nul
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-opencode.cmd" >nul
+copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-cline.cmd" >nul
if not "%FAIL_STEP%"=="fcc-missing" copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-codex.cmd" >nul
exit /b 0
:update_shell
@@ -1333,6 +1361,9 @@ def powershell_harness(
(fixtures / "opencode-command.cmd").write_text(
_batch_client("opencode"), encoding="utf-8"
)
+ (fixtures / "cline-command.cmd").write_text(
+ _batch_client("cline"), encoding="utf-8"
+ )
(fixtures / "rtk-command.cmd").write_text(_batch_rtk(), encoding="utf-8")
(fixtures / "uv-command.cmd").write_text(_batch_uv("0.11.28"), encoding="utf-8")
(fixtures / "fcc-command.cmd").write_text(
@@ -1405,6 +1436,9 @@ Add-Content -LiteralPath $env:CALL_LOG -Value "uv-install"
arcname="opencode.exe",
)
(bin_dir / "opencode.cmd").write_text(_batch_client("opencode"), encoding="utf-8")
+ npm_prefix = tmp_path / "npm-prefix"
+ npm_prefix.mkdir()
+ (bin_dir / "npm.cmd").write_text(_batch_npm(), encoding="utf-8")
wrapper = tmp_path / "run-installer.ps1"
wrapper.write_text(
@@ -1503,6 +1537,7 @@ $installer = [scriptblock]::Create($installerSource)
"CLAUDE_CONFIG_DIR": "",
"FAKE_FIXTURES": str(fixtures),
"FAKE_TOOL_BIN": str(tool_bin),
+ "FAKE_NPM_PREFIX": str(npm_prefix),
"FCC_INSTALLER": str(_repo_root() / "scripts" / "install.ps1"),
"FCC_PROCESS_MARKER": str(tmp_path / "fcc-process-ready"),
"FCC_RUNNING_COMMAND": "",
@@ -1530,6 +1565,7 @@ def test_install_ps1_fresh_install_is_verified(
assert calls.index("codex-install:1") < calls.index("codex:--version")
assert calls.index("pi-install") < calls.index("pi:--version")
assert any("anomalyco/opencode" in call for call in calls)
+ assert calls.index("npm:install -g cline") < calls.index("cline:--version")
assert calls.index("uv-install") < calls.index("uv:--version")
assert any(
call.startswith(
@@ -1766,6 +1802,7 @@ def test_install_ps1_preserves_valid_existing_tools(
powershell_harness.add_client("claude")
powershell_harness.add_client("codex")
powershell_harness.add_client("pi")
+ powershell_harness.add_client("cline")
powershell_harness.add_uv(uv_version)
result = powershell_harness.run()
@@ -1907,6 +1944,8 @@ def test_install_ps1_replaces_prerelease_uv(
"opencode-download",
"opencode-archive",
"opencode-verify",
+ "cline-install",
+ "cline-verify",
"uv-download",
"uv-install",
"uv-verify",
@@ -1939,6 +1978,8 @@ def test_install_ps1_stops_without_success_on_each_failure(
"opencode-download": "uv-install",
"opencode-archive": "uv-install",
"opencode-verify": "astral.sh",
+ "cline-install": "cline:--version",
+ "cline-verify": "astral.sh",
"uv-download": "uv-install",
"uv-install": "uv:--version",
"uv-verify": "uv:tool install",
@@ -2130,10 +2171,27 @@ Invoke-DownloadedPowerShellInstaller `
@pytest.mark.parametrize(
("answers", "expected", "expected_messages"),
[
- (("", "", "", "", ""), "True,True,True,True,False", ()),
(
- ("maybe", "n", "n", "n", "n", "n", "y", "n", "n", "y"),
- "False,True,False,False,True",
+ ("", "", "", "", "", ""),
+ "True,True,True,True,False,False",
+ (),
+ ),
+ (
+ (
+ "maybe",
+ "n",
+ "n",
+ "n",
+ "n",
+ "n",
+ "n",
+ "y",
+ "n",
+ "n",
+ "n",
+ "y",
+ ),
+ "False,True,False,False,False,True",
("Please answer Y or N.", "Select at least one coding agent."),
),
],
@@ -2156,6 +2214,7 @@ $script:InstallClaudeCode = $true
$script:InstallCodex = $true
$script:InstallPi = $true
$script:InstallOpenCode = $true
+$script:InstallCline = $false
$script:EnableRtk = $false
function Read-Host {{
param([string] $Prompt)
@@ -2166,7 +2225,7 @@ function Read-Host {{
function Read-YesNo {{{read_yes_no}}}
function Select-CodingAgents {{{select_agents}}}
Select-CodingAgents
-Write-Output "selection:$($script:InstallClaudeCode),$($script:InstallCodex),$($script:InstallPi),$($script:InstallOpenCode),$($script:EnableRtk)"
+Write-Output "selection:$($script:InstallClaudeCode),$($script:InstallCodex),$($script:InstallPi),$($script:InstallOpenCode),$($script:InstallCline),$($script:EnableRtk)"
"""
result = subprocess.run(
@@ -2192,6 +2251,7 @@ $script:InstallClaudeCode = $false
$script:InstallCodex = $true
$script:InstallPi = $false
$script:InstallOpenCode = $false
+$script:InstallCline = $false
$script:PiAvailable = $false
$script:Calls = @()
function Write-Step {{ param([string] $Message) }}
@@ -2199,6 +2259,7 @@ function Ensure-ClaudeCode {{ $script:Calls += "claude" }}
function Ensure-Codex {{ $script:Calls += "codex" }}
function Ensure-Pi {{ $script:Calls += "pi"; $script:PiAvailable = $true }}
function Ensure-OpenCode {{ $script:Calls += "opencode" }}
+function Ensure-Cline {{ $script:Calls += "cline" }}
function Ensure-SelectedCodingAgents {{{body}}}
Ensure-SelectedCodingAgents
Write-Output "calls:$($script:Calls -join ',')"
@@ -2228,6 +2289,7 @@ $script:InstallClaudeCode = $false
$script:InstallCodex = $true
$script:InstallPi = $true
$script:InstallOpenCode = $false
+$script:InstallCline = $false
$script:PiAvailable = $false
$script:Calls = @()
function Write-Step {{ param([string] $Message) }}
@@ -2262,12 +2324,14 @@ $script:InstallClaudeCode = $false
$script:InstallCodex = $false
$script:InstallPi = $true
$script:InstallOpenCode = $false
+$script:InstallCline = $false
$script:PiAvailable = $false
function Write-Step {{ param([string] $Message) }}
function Ensure-ClaudeCode {{ }}
function Ensure-Codex {{ }}
function Ensure-Pi {{ }}
function Ensure-OpenCode {{ }}
+function Ensure-Cline {{ }}
function Ensure-SelectedCodingAgents {{{body}}}
Ensure-SelectedCodingAgents
"""
diff --git a/tests/scripts/test_uninstallers.py b/tests/scripts/test_uninstallers.py
index 60b4246e..9515459b 100644
--- a/tests/scripts/test_uninstallers.py
+++ b/tests/scripts/test_uninstallers.py
@@ -13,6 +13,7 @@ FCC_COMMANDS = (
"fcc-codex",
"fcc-pi",
"fcc-opencode",
+ "fcc-cline",
"fcc-init",
"free-claude-code",
)
@@ -134,6 +135,7 @@ def posix_uninstall_harness(tmp_path: Path) -> PosixUninstallHarness:
_write_executable(bin_dir / "codex", "#!/bin/sh\nexit 0\n")
_write_executable(bin_dir / "pi", "#!/bin/sh\nexit 0\n")
_write_executable(bin_dir / "opencode", "#!/bin/sh\nexit 0\n")
+ _write_executable(bin_dir / "cline", "#!/bin/sh\nexit 0\n")
_write_executable(
bin_dir / "pgrep",
"""#!/bin/sh
@@ -165,7 +167,7 @@ if [ "${1:-}" = "tool" ] && [ "${2:-}" = "uninstall" ]; then
echo 'Tool `free-claude-code` is not installed' >&2
exit 2
fi
- for name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-init free-claude-code; do
+ for name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline fcc-init free-claude-code; do
/bin/rm -f "$FAKE_TOOL_BIN/$name"
done
echo "Uninstalled free-claude-code"
@@ -235,6 +237,7 @@ def test_uninstall_sh_removes_and_verifies_only_fcc(
assert (posix_uninstall_harness.bin_dir / "codex").exists()
assert (posix_uninstall_harness.bin_dir / "pi").exists()
assert (posix_uninstall_harness.bin_dir / "opencode").exists()
+ assert (posix_uninstall_harness.bin_dir / "cline").exists()
assert posix_uninstall_harness.calls() == [
"uv:tool dir --bin",
"uv:tool uninstall free-claude-code",
@@ -480,7 +483,7 @@ def powershell_uninstall_harness(
(tool_bin / f"{name}.cmd").write_text(
"@echo off\nexit /b 0\n", encoding="utf-8"
)
- for name in ("claude", "codex", "pi", "opencode"):
+ for name in ("claude", "codex", "pi", "opencode", "cline"):
(bin_dir / f"{name}.cmd").write_text("@echo off\nexit /b 0\n", encoding="utf-8")
uv_commands = " ".join(FCC_COMMANDS)
@@ -592,6 +595,7 @@ def test_uninstall_ps1_removes_and_verifies_only_fcc(
assert (powershell_uninstall_harness.bin_dir / "codex.cmd").exists()
assert (powershell_uninstall_harness.bin_dir / "pi.cmd").exists()
assert (powershell_uninstall_harness.bin_dir / "opencode.cmd").exists()
+ assert (powershell_uninstall_harness.bin_dir / "cline.cmd").exists()
assert powershell_uninstall_harness.calls() == [
"uv:tool dir --bin",
"uv:tool uninstall free-claude-code",
diff --git a/uv.lock b/uv.lock
index 5dda1e9b..74c4d5e9 100644
--- a/uv.lock
+++ b/uv.lock
@@ -607,7 +607,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.5.1"
+version = "5.6.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },