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 Hermes as an FCC-routed coding harness (#1484)
Ali Khokhar548c264949b0
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 2e517deb..51e55854 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -12,15 +12,16 @@ and how contributors should extend it.Free Claude Code is a local proxy for agent clients. It accepts AnthropicMessages traffic from Claude Code and Pi clients and OpenAI Responses traffic-from Codex and OpenCode clients, routes the request to a configured upstream-provider, and preserves the wire protocol expected by the caller.+from Codex, OpenCode, Cline, and Hermes clients, routes the request to a+configured upstream provider, and preserves the wire protocol expected by the+caller.There are three runtime surfaces:- HTTP proxy: FastAPI routes expose Anthropic-compatible, Responses-compatible,health, model-listing, stop, and admin endpoints.-- CLI launchers: wrapper entrypoints prepare Claude Code, Codex, Pi, and- OpenCode sessions so they target the local proxy.+- CLI launchers: wrapper entrypoints prepare Claude Code, Codex, Pi, OpenCode,+ Cline, and Hermes sessions so they target the local proxy.- Messaging bridge: optional Discord or Telegram adapters turn chat messagesinto managed client CLI sessions.@@ -30,6 +31,8 @@ flowchart LRCodex[Codex CLI, IDE, and App] --> ProxyAPIPi[Pi Coding Agent] --> ProxyAPIOpenCode[OpenCode CLI] --> ProxyAPI+ Cline[Cline CLI] --> ProxyAPI+ Hermes[Hermes Agent] --> ProxyAPIAdminUI[Local Admin UI] --> ProxyAPIBots[Discord or Telegram Bots] --> Messaging[Messaging Bridge]Messaging --> ClientCLI[Managed Client CLI Sessions]@@ -175,6 +178,9 @@ for real prompts against supported providers:- `fcc-cline`, stable Cline CLI, and the OpenAI Responses behavior it relieson, including an FCC-scoped model catalog, attached local sessions, andprocess-local provider configuration.+- `fcc-hermes`, Hermes Agent 0.20.4 or newer, and the OpenAI Responses behavior+ it relies on for attached terminal sessions, including an FCC-scoped model+ catalog and process-local managed 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,@@ -231,6 +237,7 @@ Console scripts are registered in [pyproject.toml](pyproject.toml):- `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`.+- `fcc-hermes` calls `free_claude_code.cli.launchers.hermes: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@@ -239,7 +246,7 @@ per-user application bundle and desktop link. [scripts/uninstall.sh](scripts/uniand [scripts/uninstall.ps1](scripts/uninstall.ps1) remove those exact desktopartifacts, 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, Cline, or uv-managed Python runtimes. [scripts/ci.sh](scripts/ci.sh) and+uv, Claude Code, Codex, Pi, OpenCode, Cline, Hermes, 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.@@ -1277,7 +1284,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, OpenCode, and Cline. Each launcher remains responsible for translating those+Codex, OpenCode, Cline, and Hermes. Each launcher remains responsible for translating thoseneutral entries into its client's configuration format.[cli/launchers/pi.py](src/free_claude_code/cli/launchers/pi.py) owns the installed@@ -1347,6 +1354,30 @@ own the installed `fcc-cline` launcher for Cline CLI 3.0.55 or newer:command-line routing remain FCC-owned; deliberately switching providersinside the running Cline process is an explicit opt-out for that process.+[cli/launchers/hermes.py](src/free_claude_code/cli/launchers/hermes.py) and+[cli/launchers/hermes_config.py](src/free_claude_code/cli/launchers/hermes_config.py)+own the installed `fcc-hermes` launcher for Hermes Agent 0.20.4 or newer:++- Attached sessions require a reachable FCC server, a canonical proxy token,+ and a non-empty routable `/v1/models` snapshot. The launcher rejects caller+ provider overrides and validates explicit model choices against that snapshot.+- Each invocation gets a private, secret-free Hermes managed overlay containing+ a uniquely named custom provider. Hermes uses its `codex_responses` transport+ against FCC's `/v1`; the proxy token exists only in a unique child-process+ environment variable.+- Hermes itself verifies that the overlay is active before inference begins.+ Existing administrator-managed scopes are rejected rather than shadowed, and+ failures in version, health, catalog, temporary configuration, or activation+ all stop before the attached session starts.+- The overlay clears Hermes's main fallback formats and pins the audited built-in+ auxiliary tasks to the live FCC route while preserving same-route retries.+ Native profiles, sessions, memory, skills, plugins, credentials, and+ `HERMES_HOME` remain Hermes-owned.+- Help, version, and ordinary management commands pass through without FCC.+ Detached services are rejected because they can outlive the temporary route.+ A deliberate in-session `/model` switch is an explicit opt-out; Hermes has no+ process-wide provider lock for every plugin or future subsystem.+[cli/managed/](src/free_claude_code/cli/managed/) owns managed Claude Code subprocesses used byDiscord and Telegram messaging. Managed task invocations extend the same proxyenvironment only with non-interactive terminal settings, optional `--resume`,@@ -1370,7 +1401,7 @@ reports a count-only failure, and leaves failures available for the next cleanupattempt. Real-session registration is collision-safe and becomes durable treestate only after the manager accepts it.-Codex, Pi, OpenCode, and Cline are supported through their installed launchers. FCC+Codex, Pi, OpenCode, Cline, and Hermes are supported through their installed launchers. FCCdoes not keep internal managed session runners for them because no user-facingmessaging setting selects those clients for Discord or Telegram.diff --git a/README.md b/README.mdindex f3aec137..d3fe9090 100644--- a/README.md+++ b/README.md@@ -26,7 +26,7 @@## What You Get- **48 ToS-friendly providers. 1.3B+ free tokens every month.** Use free, paid, subscription, and local models from one searchable UI without putting your account at risk. FCC follows provider terms and removes integrations if they stop being allowed.-- **5 coding agents. One model catalog.** Run [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [OpenCode](https://github.com/anomalyco/opencode), or [Cline](https://github.com/cline/cline) with your FCC models.+- **6 coding agents. One model catalog.** Run [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [OpenCode](https://github.com/anomalyco/opencode), [Cline](https://github.com/cline/cline), or [Hermes](https://github.com/NousResearch/hermes-agent) with your FCC models.- **Keep coding through provider outages.** After retries are exhausted, FCC automatically tries your next configured model without making you restart the turn—across every client.- **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](https://code.visualstudio.com/), [Codex App](https://learn.chatgpt.com/docs/app), [JetBrains](https://www.jetbrains.com/), [Discord](https://discord.com/), or [Telegram](https://telegram.org/).@@ -131,14 +131,21 @@ Cline: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:+Hermes:++```bash+fcc-hermes+```++All six 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:```bashfcc-codex exec "hello"```FCC launchers leave your existing agent settings, sessions, credentials, and-extensions unchanged.+extensions unchanged. `fcc-hermes` starts attached sessions through FCC; choosing+another provider with Hermes `/model` intentionally leaves the FCC route.<a id="model-picker"></a>@@ -288,7 +295,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, OpenCode, or Cline. If none is sent, keep the provider default. |+| **From client** (default) | Use the effort sent by Claude Code, Codex, Pi, OpenCode, Cline, or Hermes. 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 +309,7 @@ Providers that do not support a selected control retain their own behavior.## Connect Your ClientFor terminal use, start `fcc-server`, then run `fcc-claude`, `fcc-codex`,-`fcc-pi`, `fcc-opencode`, or `fcc-cline`. Use the guides below for editor integrations.+`fcc-pi`, `fcc-opencode`, `fcc-cline`, or `fcc-hermes`. Use the guides below for editor integrations.<details><summary><strong>Claude Code in VS Code</strong></summary>@@ -539,7 +546,7 @@ Stop every running FCC command before uninstalling.**Keeps**- uv and Python-- Claude Code, Codex, Pi, OpenCode, Cline, and RTK+- Claude Code, Codex, Pi, OpenCode, Cline, Hermes, and RTK- Shared PATH entriesmacOS/Linux:diff --git a/pyproject.toml b/pyproject.tomlindex cff32a13..0c2ab225 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "5.8.2"+version = "5.9.0"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"@@ -35,6 +35,7 @@ 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"+fcc-hermes = "free_claude_code.cli.launchers.hermes:launch"[project.gui-scripts]fcc-desktop = "free_claude_code.cli.desktop_entrypoint:launch"diff --git a/scripts/install.ps1 b/scripts/install.ps1index bf42e064..ad690df3 100644--- a/scripts/install.ps1+++ b/scripts/install.ps1@@ -24,6 +24,8 @@ $PiInstallUrl = "https://pi.dev/install.ps1"$OpenCodeReleaseBaseUrl = "https://github.com/anomalyco/opencode/releases/latest/download"$MinOpenCodeVersion = "1.18.18"$MinClineVersion = "3.0.55"+$HermesInstallUrl = "https://hermes-agent.nousresearch.com/install.ps1"+$MinHermesVersion = "0.20.4"$RtkVersion = "0.44.2"$RtkReleaseBaseUrl = "https://github.com/rtk-ai/rtk/releases/download/v$RtkVersion"$RtkWindowsAssetName = "rtk-x86_64-pc-windows-msvc.zip"@@ -34,6 +36,7 @@ $script:InstallCodex = $true$script:InstallPi = $true$script:InstallOpenCode = $true$script:InstallCline = $false+$script:InstallHermes = $true$script:PiAvailable = $false$script:EnableRtk = $Rtk.IsPresent$FccCommands = @(@@ -45,6 +48,7 @@ $FccCommands = @("fcc-pi","fcc-opencode","fcc-cline",+ "fcc-hermes","fcc-init","free-claude-code")@@ -108,8 +112,11 @@ function Select-CodingAgents {$script:InstallCline = Read-YesNo `-Prompt "Install or verify Cline CLI for fcc-cline?" `-DefaultYes $script:InstallCline+ $script:InstallHermes = Read-YesNo `+ -Prompt "Install or verify Hermes Agent for fcc-hermes?" `+ -DefaultYes $script:InstallHermes- if ($script:InstallClaudeCode -or $script:InstallCodex -or $script:InstallPi -or $script:InstallOpenCode -or $script:InstallCline) {+ if ($script:InstallClaudeCode -or $script:InstallCodex -or $script:InstallPi -or $script:InstallOpenCode -or $script:InstallCline -or $script:InstallHermes) {break}Write-Host "Select at least one coding agent."@@ -244,6 +251,9 @@ function Add-KnownBinDirectories {Add-PathEntry (Join-Path $env:USERPROFILE ".local\bin")Add-PathEntry (Join-Path $env:USERPROFILE ".opencode\bin")}+ if (-not [string]::IsNullOrWhiteSpace($env:LOCALAPPDATA)) {+ Add-PathEntry (Join-Path $env:LOCALAPPDATA "hermes\hermes-agent\bin")+ }if (-not [string]::IsNullOrWhiteSpace($env:LOCALAPPDATA)) {Add-PathEntry (Join-Path $env:LOCALAPPDATA "Programs\OpenAI\Codex\bin")Add-PathEntry (Join-Path $env:LOCALAPPDATA "pi-node\current")@@ -291,13 +301,20 @@ function Invoke-DownloadedPowerShellInstaller {param([string] $Url,[string] $Name,- [switch] $NonInteractive+ [switch] $NonInteractive,+ [string[]] $ScriptArguments = @())if ($DryRun) {Write-Host "+ irm $Url -OutFile <temporary-script>"$prefix = if ($NonInteractive) { "CODEX_NON_INTERACTIVE=1 " } else { "" }- Write-Host "+ ${prefix}powershell -NoProfile -ExecutionPolicy Bypass -File <temporary-script>"+ $suffix = if ($ScriptArguments.Count -gt 0) {+ " " + (($ScriptArguments | ForEach-Object { Format-Argument $_ }) -join " ")+ }+ else {+ ""+ }+ Write-Host "+ ${prefix}powershell -NoProfile -ExecutionPolicy Bypass -File <temporary-script>$suffix"return}@@ -328,13 +345,14 @@ function Invoke-DownloadedPowerShellInstaller {if ($NonInteractive) {$env:CODEX_NON_INTERACTIVE = "1"}- Invoke-NativeCommand -FilePath $powerShellPath -Arguments @(+ $installerArguments = @("-NoProfile","-ExecutionPolicy","Bypass","-File",$temporaryScript- )+ ) + $ScriptArguments+ Invoke-NativeCommand -FilePath $powerShellPath -Arguments $installerArguments}finally {if ($hadNonInteractive) {@@ -617,7 +635,7 @@ function Convert-SemanticVersionOutput {if ([string]::IsNullOrWhiteSpace($Output)) {return ""}- 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*$') {+ if ($Output -match '(?m)^\s*(?:(?:uv|opencode|cline)(?:\s+version)?\s+|Hermes Agent\s+v?|v)?(?<version>\d+\.\d+\.\d+(?:[-+][0-9A-Za-z][0-9A-Za-z.-]*)?)(?:\s+\([^\r\n]*\))?\s*$') {return $Matches["version"]}return ""@@ -830,6 +848,83 @@ function Ensure-Cline {Confirm-ClineApplication}+function Get-HermesVersion {+ param([string] $HermesPath)++ $output = Invoke-Utf8NativeCapture -FilePath $HermesPath -Arguments @("--version")+ $version = Convert-SemanticVersionOutput $output+ if ([string]::IsNullOrWhiteSpace($version)) {+ throw "Hermes Agent is present, but 'hermes --version' did not return a valid semantic version."+ }+ return $version+}++function Confirm-HermesArchitecture {+ $architecture = $env:PROCESSOR_ARCHITEW6432+ if ([string]::IsNullOrWhiteSpace($architecture)) {+ $architecture = $env:PROCESSOR_ARCHITECTURE+ }+ if ([string]::IsNullOrWhiteSpace($architecture)) {+ $architecture = [Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString()+ }+ if ($architecture.ToUpperInvariant() -notin @("ARM64", "AMD64", "X64", "X86_64")) {+ throw "Hermes Agent does not provide a supported Windows release for architecture '$architecture'."+ }+}++function Confirm-HermesApplication {+ if ($DryRun) {+ Write-Host "+ hermes --version"+ return+ }++ $command = Get-ApplicationCommand "hermes"+ if (-not $command) {+ throw "Hermes Agent was installed, but 'hermes' is not available on PATH."+ }+ $version = Get-HermesVersion $command.Source+ if (-not (Test-SupportedStableVersion -Version $version -Minimum $MinHermesVersion)) {+ throw "Hermes Agent $MinHermesVersion or newer is required; found Hermes $version after installation."+ }+ Write-Host "Verified Hermes Agent $version."+}++function Install-Hermes {+ Confirm-HermesArchitecture+ Invoke-DownloadedPowerShellInstaller `+ -Url $HermesInstallUrl `+ -Name "Hermes Agent" `+ -ScriptArguments @("-NonInteractive", "-SkipSetup")+ Add-KnownBinDirectories+}++function Ensure-Hermes {+ if ($DryRun) {+ if (Get-ApplicationCommand "hermes") {+ Write-Host "+ hermes --version"+ Write-Host "A compatible Hermes Agent will be preserved; an older version will be upgraded with the official installer."+ }+ else {+ Install-Hermes+ }+ Confirm-HermesApplication+ return+ }++ $command = Get-ApplicationCommand "hermes"+ if ($command) {+ $version = Get-HermesVersion $command.Source+ if (Test-SupportedStableVersion -Version $version -Minimum $MinHermesVersion) {+ Write-Host "Hermes Agent $version already satisfies >=$MinHermesVersion; leaving it unchanged."+ return+ }+ Write-Host "Hermes Agent $version does not satisfy >=$MinHermesVersion; upgrading it with the official installer."+ }++ Install-Hermes+ Confirm-HermesApplication+}+function Ensure-SelectedCodingAgents {if ($script:InstallClaudeCode) {Write-Step "Ensuring Claude Code is installed"@@ -856,7 +951,12 @@ function Ensure-SelectedCodingAgents {Ensure-Cline}- if ((-not $script:InstallClaudeCode) -and (-not $script:InstallCodex) -and (-not $script:PiAvailable) -and (-not $script:InstallOpenCode) -and (-not $script:InstallCline)) {+ if ($script:InstallHermes) {+ Write-Step "Ensuring Hermes Agent is installed"+ Ensure-Hermes+ }++ if ((-not $script:InstallClaudeCode) -and (-not $script:InstallCodex) -and (-not $script:PiAvailable) -and (-not $script:InstallOpenCode) -and (-not $script:InstallCline) -and (-not $script:InstallHermes)) {throw "No selected coding agent was installed. Re-run the installer and choose at least one."}}@@ -1011,7 +1111,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, fcc-opencode, and fcc-cline in the uv tool bin directory"+ Write-Host "+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, fcc-pi, fcc-opencode, fcc-cline, and fcc-hermes in the uv tool bin directory"Write-Host "+ fcc-server --version"Export-FccDesktopIcon `-DesktopCommand "<uv-tool-bin>\fcc-desktop.exe" `@@ -1038,7 +1138,7 @@ function Configure-AndConfirmFreeClaudeCode {[IO.Path]::AltDirectorySeparatorChar)$installedCommands = @{}- foreach ($commandName in @("fcc-desktop", "fcc-server", "fcc-claude", "fcc-codex", "fcc-pi", "fcc-opencode", "fcc-cline")) {+ foreach ($commandName in @("fcc-desktop", "fcc-server", "fcc-claude", "fcc-codex", "fcc-pi", "fcc-opencode", "fcc-cline", "fcc-hermes")) {$command = Get-ApplicationCommand $commandNameif (-not $command) {throw "Free Claude Code installation did not create '$commandName'."@@ -1188,4 +1288,10 @@ else {else {Write-Host "The fcc-cline wrapper is ready after you install Cline CLI."}+ if ($script:InstallHermes) {+ Write-Host "Run Hermes Agent with: fcc-hermes"+ }+ else {+ Write-Host "The fcc-hermes wrapper is ready after you install Hermes Agent."+ }}diff --git a/scripts/install.sh b/scripts/install.shindex 3b17820b..1a6c8a1a 100644--- a/scripts/install.sh+++ b/scripts/install.sh@@ -10,13 +10,15 @@ 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"+HERMES_INSTALL_URL="https://hermes-agent.nousresearch.com/install.sh"+MIN_HERMES_VERSION="0.20.4"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-cline fcc-init free-claude-code"+FCC_COMMANDS="fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline fcc-hermes fcc-init free-claude-code"dry_run=0voice_nim=0@@ -27,6 +29,7 @@ install_codex=1install_pi=1install_opencode=1install_cline=0+install_hermes=1enable_rtk=0torch_backend=""temporary_file=""@@ -128,7 +131,18 @@ choose_coding_agents() {install_cline=0fi- if [ "$install_claude" -eq 1 ] || [ "$install_codex" -eq 1 ] || [ "$install_pi" -eq 1 ] || [ "$install_opencode" -eq 1 ] || [ "$install_cline" -eq 1 ]; then+ if [ "$install_hermes" -eq 1 ]; then+ hermes_default=yes+ else+ hermes_default=no+ fi+ if prompt_yes_no "Install or verify Hermes Agent for fcc-hermes?" "$hermes_default"; then+ install_hermes=1+ else+ install_hermes=0+ fi++ if [ "$install_claude" -eq 1 ] || [ "$install_codex" -eq 1 ] || [ "$install_pi" -eq 1 ] || [ "$install_opencode" -eq 1 ] || [ "$install_cline" -eq 1 ] || [ "$install_hermes" -eq 1 ]; thenbreakfiprintf 'Select at least one coding agent.\n\n' >&4@@ -290,16 +304,26 @@ download_and_run() {url=$1interpreter=$2label=$3- non_interactive=${4:-0}+ shift 3+ non_interactive=0+ if [ "$#" -gt 0 ]; then+ non_interactive=$1+ shift+ fiif [ "$dry_run" -eq 1 ]; thenprint_command curl -fsSL "$url" -o "<temporary-script>"if [ "$non_interactive" -eq 1 ]; thenprintf '+ CODEX_NON_INTERACTIVE=1 'quote_arg "$interpreter"- printf ' <temporary-script>\n'+ printf ' <temporary-script>'+ for arg in "$@"; do+ printf ' '+ quote_arg "$arg"+ done+ printf '\n'else- print_command "$interpreter" "<temporary-script>"+ print_command "$interpreter" "<temporary-script>" "$@"fireturn 0fi@@ -322,16 +346,20 @@ download_and_run() {quote_arg "$interpreter"printf ' 'quote_arg "$temporary_file"+ for arg in "$@"; do+ printf ' '+ quote_arg "$arg"+ doneprintf '\n'- if CODEX_NON_INTERACTIVE=1 "$interpreter" "$temporary_file"; then+ if CODEX_NON_INTERACTIVE=1 "$interpreter" "$temporary_file" "$@"; then:elsestatus=$?fail "$label installation failed with exit code $status."fielse- print_command "$interpreter" "$temporary_file"- if "$interpreter" "$temporary_file"; then+ print_command "$interpreter" "$temporary_file" "$@"+ if "$interpreter" "$temporary_file" "$@"; then:elsestatus=$?@@ -723,6 +751,88 @@ ensure_cline() {verify_cline_command}+current_hermes_version() {+ if output=$(hermes --version 2>/dev/null); then+ :+ else+ return 1+ fi++ version=$(printf '%s\n' "$output" | awk '+ 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_hermes_command() {+ if [ "$dry_run" -eq 1 ]; then+ print_command hermes --version+ return 0+ fi++ command -v hermes >/dev/null 2>&1 || fail "Hermes Agent was installed, but 'hermes' is not available on PATH."+ version=$(current_hermes_version) || fail "Hermes Agent is present, but 'hermes --version' did not return a valid semantic version."+ if ! stable_version_is_supported "$version" "$MIN_HERMES_VERSION"; then+ fail "Hermes Agent $MIN_HERMES_VERSION or newer is required; found Hermes $version after installation."+ fi+ printf 'Verified Hermes Agent %s.\n' "$version"+}++hermes_platform_is_supported() {+ hermes_platform=$(uname -s)+ hermes_architecture=$(uname -m)+ case "$hermes_platform:$hermes_architecture" in+ Linux:x86_64|Linux:amd64|Linux:aarch64|Linux:arm64|Darwin:aarch64|Darwin:arm64)+ return 0+ ;;+ *)+ return 1+ ;;+ esac+}++confirm_hermes_platform() {+ if hermes_platform_is_supported; then+ return 0+ fi+ fail "Hermes Agent does not provide a supported release for $hermes_platform $hermes_architecture."+}++install_hermes() {+ confirm_hermes_platform+ download_and_run "$HERMES_INSTALL_URL" bash "Hermes Agent" 0 --non-interactive --skip-setup+ add_known_bin_directories+}++ensure_hermes() {+ if [ "$dry_run" -eq 1 ]; then+ if command -v hermes >/dev/null 2>&1; then+ print_command hermes --version+ printf 'A compatible Hermes Agent will be preserved; an older version will be upgraded with the official installer.\n'+ else+ install_hermes+ fi+ verify_hermes_command+ return 0+ fi++ if command -v hermes >/dev/null 2>&1; then+ version=$(current_hermes_version) || fail "Hermes Agent is present, but 'hermes --version' did not return a valid semantic version."+ if stable_version_is_supported "$version" "$MIN_HERMES_VERSION"; then+ printf 'Hermes Agent %s already satisfies >=%s; leaving it unchanged.\n' "$version" "$MIN_HERMES_VERSION"+ return 0+ fi+ printf 'Hermes Agent %s does not satisfy >=%s; upgrading it with the official installer.\n' "$version" "$MIN_HERMES_VERSION"+ fi++ install_hermes+ verify_hermes_command+}+ensure_selected_coding_agents() {if [ "$install_claude" -eq 1 ]; thenstep "Ensuring Claude Code is installed"@@ -749,7 +859,12 @@ ensure_selected_coding_agents() {ensure_clinefi- if [ "$install_claude" -eq 0 ] && [ "$install_codex" -eq 0 ] && [ "$pi_available" -eq 0 ] && [ "$install_opencode" -eq 0 ] && [ "$install_cline" -eq 0 ]; then+ if [ "$install_hermes" -eq 1 ]; then+ step "Ensuring Hermes Agent is installed"+ ensure_hermes+ fi++ if [ "$install_claude" -eq 0 ] && [ "$install_codex" -eq 0 ] && [ "$pi_available" -eq 0 ] && [ "$install_opencode" -eq 0 ] && [ "$install_cline" -eq 0 ] && [ "$install_hermes" -eq 0 ]; thenfail "No selected coding agent was installed. Re-run the installer and choose at least one."fi}@@ -936,7 +1051,7 @@ configure_and_verify_free_claude_code() {if [ "$dry_run" -eq 1 ]; thenprint_command uv tool dir --bin- printf '+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, fcc-pi, fcc-opencode, and fcc-cline in the uv tool bin directory\n'+ printf '+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, fcc-pi, fcc-opencode, fcc-cline, and fcc-hermes in the uv tool bin directory\n'print_command fcc-server --versionreturn 0fi@@ -954,7 +1069,7 @@ configure_and_verify_free_claude_code() {export PATHhash -r 2>/dev/null || true- for command_name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline; do+ for command_name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline fcc-hermes; do[ -x "$tool_bin/$command_name" ] || fail "Free Claude Code installation did not create $tool_bin/$command_name."done@@ -1056,6 +1171,9 @@ add_known_bin_directoriesif command -v cline >/dev/null 2>&1 || command -v npm >/dev/null 2>&1; theninstall_cline=1fi+if ! command -v hermes >/dev/null 2>&1 && ! hermes_platform_is_supported; then+ install_hermes=0+fistep "Checking for running Free Claude Code processes"assert_no_fcc_processes_running@@ -1067,7 +1185,7 @@ fistep "Checking installation prerequisites"require_command curl-if [ "$install_claude" -eq 1 ] || [ "$install_opencode" -eq 1 ]; then+if [ "$install_claude" -eq 1 ] || [ "$install_opencode" -eq 1 ] || [ "$install_hermes" -eq 1 ]; thenrequire_command bashfirequire_command sh@@ -1124,4 +1242,9 @@ elseelseprintf 'The fcc-cline wrapper is ready after you install Cline CLI.\n'fi+ if [ "$install_hermes" -eq 1 ]; then+ printf 'Run Hermes Agent with: fcc-hermes\n'+ else+ printf 'The fcc-hermes wrapper is ready after you install Hermes Agent.\n'+ fifidiff --git a/scripts/uninstall.ps1 b/scripts/uninstall.ps1index ae7cb5ea..f990ac7c 100644--- a/scripts/uninstall.ps1+++ b/scripts/uninstall.ps1@@ -19,6 +19,7 @@ $FccCommands = @("fcc-pi","fcc-opencode","fcc-cline",+ "fcc-hermes","fcc-init","free-claude-code")@@ -335,5 +336,5 @@ if ($DryRun) {}else {Write-Host "Free Claude Code has been removed and verified."- Write-Host "uv, Claude Code, Codex, Pi, OpenCode, the uv-managed Python runtime, and shared PATH entries were left installed."+ Write-Host "uv, Claude Code, Codex, Pi, OpenCode, Cline, Hermes Agent, the uv-managed Python runtime, and shared PATH entries were left installed."}diff --git a/scripts/uninstall.sh b/scripts/uninstall.shindex a8f6d969..850e2e39 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-cline fcc-init free-claude-code"+FCC_COMMANDS="fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline fcc-hermes fcc-init free-claude-code"dry_run=0uv_tool_bin=""@@ -298,5 +298,5 @@ if [ "$dry_run" -eq 1 ]; thenprintf '\nDry run complete. No changes were made.\n'elseprintf '\nFree Claude Code has been removed and verified.\n'- printf 'uv, Claude Code, Codex, Pi, OpenCode, the uv-managed Python runtime, and shared PATH entries were left installed.\n'+ printf 'uv, Claude Code, Codex, Pi, OpenCode, Cline, Hermes Agent, the uv-managed Python runtime, and shared PATH entries were left installed.\n'fidiff --git a/smoke/README.md b/smoke/README.mdindex 2fc93ffe..04408c35 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, automatic WebSearch, Auto-mode classifier, session cleanup | Claude CLI binary and provider only for real CLI; connected OpenAI account for Auto mode; `FCC_SMOKE_RUN_WEB_TOOLS=1` for WebSearch |-| `clients` | VS Code and JetBrains protocol payloads; Pi, OpenCode, and Cline CLI prompts | configured provider; installed Pi/OpenCode/Cline binaries for their CLI scenarios |+| `clients` | VS Code and JetBrains protocol payloads; Pi, OpenCode, Cline, and Hermes CLI prompts | configured provider; installed Pi/OpenCode/Cline binaries; Hermes uses a local fake upstream || `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.pyindex 59785cd4..457eb967 100644--- a/smoke/capabilities.py+++ b/smoke/capabilities.py@@ -567,6 +567,20 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (),("test_cline_cli_prompt_e2e",),),+ CapabilityContract(+ "cli",+ "hermes_cli_integration",+ "hermes_cli_integration",+ "free_claude_code.cli.launchers.hermes",+ "Hermes Agent 0.20.4+, live FCC catalog, and process-only managed overlay",+ "Responses provider scoped to FCC for attached terminal sessions",+ "version, policy, activation, proxy, or catalog failure exits before inference",+ (+ "tests/cli/test_hermes_config.py",+ "tests/cli/test_hermes_launcher.py",+ ),+ ("test_hermes_cli_prompt_e2e",),+ ),CapabilityContract("extensibility","provider_platform_abcs",diff --git a/smoke/features.py b/smoke/features.pyindex 5f49009b..e505a796 100644--- a/smoke/features.py+++ b/smoke/features.py@@ -137,6 +137,19 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (),"skip only when Cline is absent; configured providers must pass",),+ FeatureCoverage(+ "hermes_cli_integration",+ "Hermes discovers FCC models and sends Responses through the proxy",+ (+ "tests/cli/test_hermes_config.py",+ "tests/cli/test_hermes_launcher.py",+ ),+ ("test_probe_and_models_routes",),+ ("test_hermes_cli_prompt_e2e",),+ ("clients",),+ ("Hermes Agent 0.20.4+",),+ "skip only when Hermes is absent; the local fake upstream 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.pyindex dc2f2c65..f970f70b 100644--- a/smoke/product/test_client_product_live.py+++ b/smoke/product/test_client_product_live.py@@ -12,6 +12,7 @@ from pathlib import Pathimport pytest+from free_claude_code.config.provider_catalog import PROVIDER_CATALOGfrom free_claude_code.core.json_types import JsonObject, JsonValuefrom smoke.lib.claude_cli_matrix import run_claude_clifrom smoke.lib.config import SmokeConfig@@ -268,6 +269,122 @@ def test_cline_cli_prompt_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> Noneassert "POST /v1/chat/completions" not in server_log[email protected]_target("clients")+def test_hermes_cli_prompt_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None:+ if not shutil.which("hermes"):+ pytest.skip("missing_env: Hermes Agent not found")+ uv_bin = shutil.which("uv")+ if not uv_bin:+ pytest.skip("missing_env: uv not found")++ model_id = "fcc-smoke-hermes"+ full_model = f"lmstudio/{model_id}"+ marker = "FCC_SMOKE_HERMES"+ auth_token = smoke_config.settings.proxy_auth_token+ isolated_home = tmp_path / "home"+ hermes_home = tmp_path / "hermes-home"+ isolated_home.mkdir()+ hermes_home.mkdir()+ native_config = hermes_home / "config.yaml"+ native_env = hermes_home / ".env"+ native_config.write_text(+ json.dumps(+ {+ "model": {+ "provider": "openrouter",+ "default": "native/model",+ }+ },+ indent=2,+ )+ + "\n",+ encoding="utf-8",+ )+ native_env.write_text("OPENAI_API_KEY=native-sentinel\n", encoding="utf-8")+ config_before = native_config.read_bytes()+ env_before = native_env.read_bytes()+ credential_env_keys = {+ descriptor.credential_env+ for descriptor in PROVIDER_CATALOG.values()+ if descriptor.credential_env is not None+ }++ with (+ _successful_openai_provider(model_id=model_id, marker=marker) as (+ provider_base_url,+ provider_requests,+ ),+ SmokeServerDriver(+ smoke_config,+ name="product-hermes-cli",+ env_overrides={+ "MODEL": full_model,+ "MODEL_FABLE": full_model,+ "MODEL_OPUS": full_model,+ "MODEL_SONNET": full_model,+ "MODEL_HAIKU": full_model,+ "LM_STUDIO_BASE_URL": provider_base_url,+ "MESSAGING_PLATFORM": "none",+ },+ env_unset=credential_env_keys,+ ).run() as server,+ ):+ env = os.environ.copy()+ for key in credential_env_keys:+ env.pop(key, None)+ for key in tuple(env):+ if key.startswith("FCC_HERMES_"):+ env.pop(key)+ 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),+ "HERMES_HOME": str(hermes_home),+ }+ )+ env.pop("HERMES_MANAGED_DIR", None)+ result = subprocess.run(+ [+ uv_bin,+ "run",+ "--project",+ str(smoke_config.root),+ "--no-sync",+ "fcc-hermes",+ "--model",+ full_model,+ "-z",+ f"Reply with exactly {marker}",+ ],+ 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 result.stdout == f"{marker}\n"+ assert result.stderr == ""+ assert "GET /v1/models" in server_log+ assert server_log.count("POST /v1/responses") == 1+ assert "POST /v1/chat/completions" not in server_log+ assert [request["path"] for request in provider_requests] == [+ "/v1/chat/completions"+ ]+ provider_body = provider_requests[0]["body"]+ assert isinstance(provider_body, dict)+ assert provider_body["model"] == model_id+ assert native_config.read_bytes() == config_before+ assert native_env.read_bytes() == env_before++@pytest.mark.smoke_target("cli")def test_claude_cli_adaptive_thinking_e2e(smoke_config: SmokeConfig, tmp_path: Path@@ -604,6 +721,98 @@ def _deliberately_failing_openai_provider() -> Iterator[tuple[str, list[str]]]:thread.join(timeout=5)+@contextmanager+def _successful_openai_provider(+ *, model_id: str, marker: str+) -> Iterator[tuple[str, list[JsonObject]]]:+ provider_requests: list[JsonObject] = []++ class Handler(BaseHTTPRequestHandler):+ protocol_version = "HTTP/1.1"++ def do_GET(self) -> None:+ if self.path == "/v1/models":+ self._write_json(+ HTTPStatus.OK,+ {+ "object": "list",+ "data": [{"id": model_id, "object": "model"}],+ },+ )+ return+ if self.path == "/api/v0/models":+ self._write_json(HTTPStatus.OK, {"data": []})+ return+ self._write_json(HTTPStatus.NOT_FOUND, {"error": "not found"})++ def do_POST(self) -> None:+ length = int(self.headers.get("content-length", "0"))+ raw_body = self.rfile.read(length)+ parsed: JsonValue = json.loads(raw_body) if raw_body else {}+ if not isinstance(parsed, dict):+ self._write_json(HTTPStatus.BAD_REQUEST, {"error": "invalid body"})+ return+ provider_requests.append({"path": self.path, "body": parsed})+ if self.path != "/v1/chat/completions":+ self._write_json(HTTPStatus.NOT_FOUND, {"error": "not found"})+ return++ self.send_response(HTTPStatus.OK)+ self.send_header("content-type", "text/event-stream")+ self.send_header("cache-control", "no-cache")+ self.send_header("connection", "close")+ self.end_headers()+ self._write_chunk(content=marker, finish_reason=None)+ self._write_chunk(content=None, finish_reason="stop")+ self.wfile.write(b"data: [DONE]\n\n")+ self.wfile.flush()++ def log_message(self, format: str, *args: object) -> None:+ return++ def _write_json(self, status: HTTPStatus, payload: object) -> None:+ body = json.dumps(payload).encode("utf-8")+ self.send_response(status)+ self.send_header("content-type", "application/json")+ self.send_header("content-length", str(len(body)))+ self.end_headers()+ self.wfile.write(body)++ def _write_chunk(+ self, *, content: str | None, finish_reason: str | None+ ) -> None:+ delta: JsonObject = {}+ if content is not None:+ delta = {"role": "assistant", "content": content}+ payload = {+ "id": "chatcmpl-hermes-smoke",+ "object": "chat.completion.chunk",+ "created": 0,+ "model": model_id,+ "choices": [+ {+ "index": 0,+ "delta": delta,+ "finish_reason": finish_reason,+ }+ ],+ }+ self.wfile.write(f"data: {json.dumps(payload)}\n\n".encode())+ self.wfile.flush()++ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)+ server.daemon_threads = True+ thread = threading.Thread(target=server.serve_forever, daemon=True)+ thread.start()+ try:+ port = int(server.server_address[1])+ yield f"http://127.0.0.1:{port}/v1", provider_requests+ finally:+ server.shutdown()+ server.server_close()+ thread.join(timeout=5)++@pytest.mark.smoke_target("cli")def test_claude_cli_multiturn_tool_protocol_e2e(smoke_config: SmokeConfig) -> None:provider_model = ProviderMatrixDriver(smoke_config).first_model()diff --git a/src/free_claude_code/cli/launchers/hermes.py b/src/free_claude_code/cli/launchers/hermes.pynew file mode 100644index 00000000..d75e1bf9--- /dev/null+++ b/src/free_claude_code/cli/launchers/hermes.py@@ -0,0 +1,522 @@+"""Installed `fcc-hermes` launcher for attached Hermes Agent sessions."""++import json+import os+import re+import secrets+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 .common import preflight_proxy, resolve_client_binary, run_client_process+from .hermes_config import (+ HERMES_KEY_ENV_PREFIX,+ HermesManagedConfig,+ build_hermes_managed_config,+)+from .model_catalog import client_models_from_response, fetch_proxy_models_response++_BINARY_NAME = "hermes"+_DISPLAY_NAME = "Hermes Agent"+_INSTALL_URL = "https://hermes-agent.nousresearch.com/docs/installation"+_INSTALL_HINT = f"Install Hermes Agent from: {_INSTALL_URL}"+_MINIMUM_VERSION = (0, 20, 4)+_VERSION_TIMEOUT_SECONDS = 5.0+_ACTIVATION_TIMEOUT_SECONDS = 15.0+_VERSION_PATTERN = re.compile(r"(?i)\b(?:Hermes Agent\s+)?v?(\d+)\.(\d+)\.(\d+)\b")+_PASSTHROUGH_FLAGS = frozenset({"-h", "--help", "-V", "--version"})+_DETACHED_COMMANDS = frozenset(+ {+ "acp",+ "rl",+ "gateway",+ "cron",+ "serve",+ "dashboard",+ "gui",+ "desktop",+ "proxy",+ }+)+_GLOBAL_VALUE_OPTIONS = frozenset(+ {+ "-z",+ "--oneshot",+ "--usage-file",+ "-m",+ "--model",+ "--provider",+ "--reasoning",+ "-t",+ "--toolsets",+ "-r",+ "--resume",+ "--in",+ "-s",+ "--skills",+ "-p",+ "--profile",+ }+)+_GLOBAL_OPTIONAL_VALUE_OPTIONS = frozenset({"-c", "--continue"})+_GLOBAL_BOOLEAN_OPTIONS = frozenset(+ {+ "--no-restore-cwd",+ "-w",+ "--worktree",+ "--accept-hooks",+ "--yolo",+ "--pass-session-id",+ "--ignore-user-config",+ "--ignore-rules",+ "--safe-mode",+ "--tui",+ "--cli",+ "--dev",+ }+)+++def launch(argv: Sequence[str] | None = None) -> None:+ """Launch one attached Hermes process with an FCC-owned default route."""++ 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_hermes_passthrough(args):+ _run(binary_path, args, os.environ)+ return+ if detached_hermes_surface(args):+ print(+ "fcc-hermes supports attached terminal sessions only. "+ "Run this detached Hermes surface with ordinary hermes instead.",+ file=sys.stderr,+ )+ raise SystemExit(2)++ profile_args = hermes_profile_args(args)+ routed_args, selected_model = _without_routing_overrides(args)+ _reject_managed_policy(os.environ)+ require_compatible_hermes(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)+ )+ managed = build_hermes_managed_config(+ models,+ proxy_root_url=proxy_root_url,+ nonce=secrets.token_hex(8),+ selected_model=selected_model,+ )+ except Exception as exc:+ print(f"Could not prepare the Hermes FCC model catalog: {exc}", file=sys.stderr)+ raise SystemExit(1) from None++ _run_with_managed_config(+ binary_path=binary_path,+ args=routed_args,+ profile_args=profile_args,+ managed=managed,+ proxy_root_url=proxy_root_url,+ auth_token=auth_token,+ )+++def is_hermes_passthrough(argv: Sequence[str]) -> bool:+ """Return whether Hermes should run without FCC process configuration."""++ before_separator = _before_separator(argv)+ if any(argument in _PASSTHROUGH_FLAGS for argument in before_separator):+ return True+ root = first_root_positional(argv)+ return root not in {None, "chat"} and not detached_hermes_surface(argv)+++def detached_hermes_surface(argv: Sequence[str]) -> bool:+ """Return whether arguments request a process that can outlive the wrapper."""++ root = first_root_positional(argv)+ if root in _DETACHED_COMMANDS:+ return True+ return root == "mcp" and _second_positional(argv) == "serve"+++def first_root_positional(argv: Sequence[str]) -> str | None:+ """Find Hermes's root command without copying its full argparse tree."""++ positionals = _root_positionals(argv, limit=1)+ return positionals[0] if positionals else None+++def hermes_profile_args(argv: Sequence[str]) -> tuple[str, ...]:+ """Return the first explicit profile selector Hermes will consume."""++ before_separator = _before_separator(argv)+ index = 0+ while index < len(before_separator):+ argument = before_separator[index]+ if argument in {"-p", "--profile"}:+ if index + 1 < len(before_separator):+ return argument, before_separator[index + 1]+ return ()+ if argument.startswith("--profile="):+ return (argument,)+ index = _next_root_index(before_separator, index)+ return ()+++def require_compatible_hermes(binary_path: str) -> None:+ """Exit unless the installed Hermes satisfies FCC's audited contract."""++ version = hermes_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 Hermes Agent at {binary_path} must be at least version {minimum}.",+ file=sys.stderr,+ )+ print(f"Upgrade it from: {_INSTALL_URL}", file=sys.stderr)+ raise SystemExit(126)+++def hermes_binary_version(binary_path: str) -> tuple[int, int, int] | None:+ """Read a Hermes semantic 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_hermes_launcher_env(+ *,+ managed_directory: Path,+ key_env: str,+ auth_token: str,+ proxy_root_url: str,+ base_env: Mapping[str, str],+) -> dict[str, str]:+ """Build a child-only Hermes environment while preserving native state."""++ filtered = {+ key: value+ for key, value in base_env.items()+ if not key.startswith(HERMES_KEY_ENV_PREFIX)+ and key+ not in {+ "HERMES_MANAGED_DIR",+ "HERMES_INFERENCE_MODEL",+ "HERMES_INFERENCE_PROVIDER",+ }+ }+ env = with_local_proxy_bypass(filtered, proxy_root_url=proxy_root_url)+ env["HERMES_MANAGED_DIR"] = str(managed_directory)+ env[key_env] = auth_token+ return env+++def _run_with_managed_config(+ *,+ binary_path: str,+ args: Sequence[str],+ profile_args: Sequence[str],+ managed: HermesManagedConfig,+ proxy_root_url: str,+ auth_token: str,+) -> None:+ try:+ temp_config = tempfile.TemporaryDirectory(prefix="fcc-hermes-")+ except OSError as exc:+ _temporary_config_error(exc)++ with temp_config as temp_directory:+ managed_directory = Path(temp_directory)+ config_path = managed_directory / "config.yaml"+ try:+ if os.name != "nt":+ managed_directory.chmod(0o700)+ _write_private_json(config_path, managed.config)+ except OSError as exc:+ _temporary_config_error(exc)++ child_env = build_hermes_launcher_env(+ managed_directory=managed_directory,+ key_env=managed.key_env,+ auth_token=auth_token,+ proxy_root_url=proxy_root_url,+ base_env=os.environ,+ )+ _require_overlay_activation(+ binary_path=binary_path,+ profile_args=profile_args,+ expected_provider=managed.provider_ref,+ env=child_env,+ )+ _run(+ binary_path,+ [+ "--provider",+ managed.provider_ref,+ "--model",+ managed.selected_model,+ *args,+ ],+ child_env,+ )+++def _require_overlay_activation(+ *,+ binary_path: str,+ profile_args: Sequence[str],+ expected_provider: str,+ env: Mapping[str, str],+) -> None:+ command = [+ binary_path,+ *profile_args,+ "config",+ "get",+ "model.provider",+ "--json",+ ]+ try:+ result = subprocess.run(+ command,+ check=False,+ capture_output=True,+ text=True,+ timeout=_ACTIVATION_TIMEOUT_SECONDS,+ env=dict(env),+ )+ except OSError, subprocess.TimeoutExpired:+ _overlay_activation_error()+ if result.returncode != 0:+ _overlay_activation_error()++ lines = [line.strip() for line in result.stdout.splitlines() if line.strip()]+ if not lines:+ _overlay_activation_error()+ try:+ active_provider = json.loads(lines[-1])+ except json.JSONDecodeError:+ _overlay_activation_error()+ if active_provider != expected_provider:+ _overlay_activation_error()+++def _without_routing_overrides(argv: Sequence[str]) -> tuple[list[str], str | None]:+ args = list(argv)+ cleaned: list[str] = []+ selected_model: str | None = None+ index = 0+ while index < len(args):+ argument = args[index]+ if argument == "--":+ cleaned.extend(args[index:])+ break+ if argument == "--provider" or argument.startswith("--provider="):+ _routing_override_error()+ if argument in {"-m", "--model"}:+ if index + 1 >= len(args) or args[index + 1] == "--":+ _model_value_error()+ if selected_model is not None:+ _duplicate_model_error()+ selected_model = args[index + 1]+ index += 2+ continue+ if argument.startswith("--model="):+ value = argument.partition("=")[2]+ if not value:+ _model_value_error()+ if selected_model is not None:+ _duplicate_model_error()+ selected_model = value+ index += 1+ continue+ if argument.startswith("-m") and len(argument) > 2:+ if selected_model is not None:+ _duplicate_model_error()+ selected_model = argument[2:]+ index += 1+ continue+ cleaned.append(argument)+ index += 1+ return cleaned, selected_model+++def _reject_managed_policy(base_env: Mapping[str, str]) -> None:+ if base_env.get("HERMES_MANAGED_DIR", "").strip() or _system_policy_exists():+ print(+ "fcc-hermes will not replace an existing Hermes managed policy. "+ "Use ordinary hermes or remove the administrator-managed scope.",+ file=sys.stderr,+ )+ raise SystemExit(2)+++def _system_policy_exists() -> bool:+ return os.name != "nt" and Path("/etc/hermes").exists()+++def _root_positionals(argv: Sequence[str], *, limit: int) -> list[str]:+ before_separator = _before_separator(argv)+ positionals: list[str] = []+ index = 0+ while index < len(before_separator) and len(positionals) < limit:+ argument = before_separator[index]+ if argument in _GLOBAL_VALUE_OPTIONS:+ index += 2+ continue+ if _is_joined_global_value(argument):+ index += 1+ continue+ if argument in _GLOBAL_OPTIONAL_VALUE_OPTIONS:+ if index + 1 < len(before_separator) and not before_separator[+ index + 1+ ].startswith("-"):+ index += 2+ else:+ index += 1+ continue+ if argument in _GLOBAL_BOOLEAN_OPTIONS or argument in _PASSTHROUGH_FLAGS:+ index += 1+ continue+ if argument.startswith("-"):+ index += 1+ continue+ positionals.append(argument)+ index += 1+ return positionals+++def _second_positional(argv: Sequence[str]) -> str | None:+ positionals = _root_positionals(argv, limit=2)+ return positionals[1] if len(positionals) == 2 else None+++def _next_root_index(argv: Sequence[str], index: int) -> int:+ argument = argv[index]+ if argument in _GLOBAL_VALUE_OPTIONS:+ return min(index + 2, len(argv))+ if (+ argument in _GLOBAL_OPTIONAL_VALUE_OPTIONS+ and index + 1 < len(argv)+ and not argv[index + 1].startswith("-")+ ):+ return index + 2+ return index + 1+++def _is_joined_global_value(argument: str) -> bool:+ if any(+ argument.startswith(f"{option}=")+ for option in _GLOBAL_VALUE_OPTIONS+ if option.startswith("--")+ ):+ return True+ return any(+ argument.startswith(option) and len(argument) > len(option)+ for option in _GLOBAL_VALUE_OPTIONS+ if option.startswith("-") and not option.startswith("--")+ )+++def _before_separator(argv: Sequence[str]) -> Sequence[str]:+ try:+ return argv[: argv.index("--")]+ except ValueError:+ return argv+++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 _routing_override_error() -> Never:+ print(+ "fcc-hermes owns the Hermes provider. "+ "Use ordinary hermes for a different provider.",+ file=sys.stderr,+ )+ raise SystemExit(2)+++def _model_value_error() -> Never:+ print("fcc-hermes requires a value after --model/-m.", file=sys.stderr)+ raise SystemExit(2)+++def _duplicate_model_error() -> Never:+ print("fcc-hermes accepts only one --model/-m override.", file=sys.stderr)+ raise SystemExit(2)+++def _temporary_config_error(exc: OSError) -> Never:+ print(f"Could not create temporary Hermes configuration: {exc}", file=sys.stderr)+ raise SystemExit(1) from None+++def _overlay_activation_error() -> Never:+ print(+ "Hermes did not honor the temporary Free Claude Code route. "+ "Check the selected Hermes profile and managed-policy settings.",+ file=sys.stderr,+ )+ raise SystemExit(1)diff --git a/src/free_claude_code/cli/launchers/hermes_config.py b/src/free_claude_code/cli/launchers/hermes_config.pynew file mode 100644index 00000000..4d7d5eee--- /dev/null+++ b/src/free_claude_code/cli/launchers/hermes_config.py@@ -0,0 +1,114 @@+"""Process-local Hermes configuration for FCC model routing."""++from dataclasses import dataclass, field++from free_claude_code.core.json_types import JsonObject++from .common import proxy_v1_url+from .model_catalog import ClientModel++HERMES_PROVIDER_PREFIX = "fcc-"+HERMES_KEY_ENV_PREFIX = "FCC_HERMES_"++_AUXILIARY_TASKS = (+ "vision",+ "web_extract",+ "compression",+ "skills_hub",+ "approval",+ "mcp",+ "title_generation",+ "memory_query_rewrite",+ "tts_audio_tags",+ "triage_specifier",+ "kanban_decomposer",+ "profile_describer",+ "goal_judge",+ "curator",+ "monitor",+ "background_review",+ "moa_reference",+ "moa_aggregator",+)+++@dataclass(frozen=True, slots=True)+class HermesManagedConfig:+ """Secret-free managed overlay for one attached Hermes process."""++ config: JsonObject = field(repr=False)+ provider_key: str+ provider_ref: str+ key_env: str+ selected_model: str+++def build_hermes_managed_config(+ models: tuple[ClientModel, ...],+ *,+ proxy_root_url: str,+ nonce: str,+ selected_model: str | None = None,+) -> HermesManagedConfig:+ """Translate an FCC catalog into one invocation-specific Hermes overlay."""++ if not models:+ raise ValueError("Hermes requires at least one routable FCC model")+ if not nonce or not nonce.isalnum():+ raise ValueError("Hermes configuration nonce must be alphanumeric")++ wire_slugs = tuple(model.wire_slug for model in models)+ active_model = selected_model or wire_slugs[0]+ if active_model not in wire_slugs:+ raise ValueError(f"model is not in the FCC catalog: {active_model}")++ provider_key = f"{HERMES_PROVIDER_PREFIX}{nonce.lower()}"+ provider_ref = f"custom:{provider_key}"+ key_env = f"{HERMES_KEY_ENV_PREFIX}{nonce.upper()}"+ auxiliary: JsonObject = {+ task: _auxiliary_task_config(task) for task in _AUXILIARY_TASKS+ }+ config: JsonObject = {+ "providers": {+ provider_key: {+ "name": "Free Claude Code",+ "api": proxy_v1_url(proxy_root_url),+ "key_env": key_env,+ "transport": "codex_responses",+ "default_model": active_model,+ "models": {wire_slug: {} for wire_slug in wire_slugs},+ "discover_models": False,+ }+ },+ "model": {+ "provider": provider_ref,+ "default": active_model,+ "base_url": "",+ "api_key": "",+ "api_mode": "codex_responses",+ },+ "fallback_providers": [],+ "fallback_model": [],+ "auxiliary": auxiliary,+ }+ return HermesManagedConfig(+ config=config,+ provider_key=provider_key,+ provider_ref=provider_ref,+ key_env=key_env,+ selected_model=active_model,+ )+++def _auxiliary_task_config(task: str) -> JsonObject:+ config: JsonObject = {+ "provider": "main",+ "model": "",+ "base_url": "",+ "api_key": "",+ "extra_body": {},+ "fallback_chain": [],+ }+ if task == "title_generation":+ config["prefer_fast_model"] = False+ return configdiff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.pyindex 66ac8049..3be18e28 100644--- a/tests/cli/test_entrypoints.py+++ b/tests/cli/test_entrypoints.py@@ -66,6 +66,7 @@ def test_cli_scripts_are_registered() -> None:"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",+ "fcc-hermes": "free_claude_code.cli.launchers.hermes:launch",}assert pyproject["project"]["gui-scripts"] == {"fcc-desktop": "free_claude_code.cli.desktop_entrypoint:launch",diff --git a/tests/cli/test_hermes_config.py b/tests/cli/test_hermes_config.pynew file mode 100644index 00000000..3d0b23d5--- /dev/null+++ b/tests/cli/test_hermes_config.py@@ -0,0 +1,148 @@+"""Contracts for the process-local Hermes configuration."""++import json++import pytest++from free_claude_code.cli.launchers.hermes_config import (+ build_hermes_managed_config,+)+from free_claude_code.cli.launchers.model_catalog import ClientModel+++def _models() -> tuple[ClientModel, ...]:+ return (+ 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,+ ),+ )+++def test_hermes_config_pins_responses_catalog_and_fallbacks() -> None:+ managed = build_hermes_managed_config(+ _models(),+ proxy_root_url="http://127.0.0.1:9191/",+ nonce="a1b2c3",+ selected_model="claude-3-freecc-no-thinking/open_router/plain-model",+ )++ assert managed.provider_key == "fcc-a1b2c3"+ assert managed.provider_ref == "custom:fcc-a1b2c3"+ assert managed.key_env == "FCC_HERMES_A1B2C3"+ assert managed.selected_model == (+ "claude-3-freecc-no-thinking/open_router/plain-model"+ )+ assert managed.config["providers"] == {+ "fcc-a1b2c3": {+ "name": "Free Claude Code",+ "api": "http://127.0.0.1:9191/v1",+ "key_env": "FCC_HERMES_A1B2C3",+ "transport": "codex_responses",+ "default_model": "claude-3-freecc-no-thinking/open_router/plain-model",+ "models": {+ "nvidia_nim/vendor/model": {},+ "claude-3-freecc-no-thinking/open_router/plain-model": {},+ },+ "discover_models": False,+ }+ }+ assert managed.config["model"] == {+ "provider": "custom:fcc-a1b2c3",+ "default": "claude-3-freecc-no-thinking/open_router/plain-model",+ "base_url": "",+ "api_key": "",+ "api_mode": "codex_responses",+ }+ assert managed.config["fallback_providers"] == []+ assert managed.config["fallback_model"] == []++ auxiliary = managed.config["auxiliary"]+ assert isinstance(auxiliary, dict)+ assert set(auxiliary) == {+ "vision",+ "web_extract",+ "compression",+ "skills_hub",+ "approval",+ "mcp",+ "title_generation",+ "memory_query_rewrite",+ "tts_audio_tags",+ "triage_specifier",+ "kanban_decomposer",+ "profile_describer",+ "goal_judge",+ "curator",+ "monitor",+ "background_review",+ "moa_reference",+ "moa_aggregator",+ }+ for task, task_config in auxiliary.items():+ assert isinstance(task_config, dict)+ expected = {+ "provider": "main",+ "model": "",+ "base_url": "",+ "api_key": "",+ "extra_body": {},+ "fallback_chain": [],+ }+ if task == "title_generation":+ expected["prefer_fast_model"] = False+ assert task_config == expected++ serialized = json.dumps(managed.config)+ assert "proxy-token" not in serialized+ assert "transient_retries" not in serialized+ assert "timeout" not in serialized+++def test_hermes_config_uses_first_model_by_default() -> None:+ managed = build_hermes_managed_config(+ _models(),+ proxy_root_url="http://127.0.0.1:9191",+ nonce="ABC123",+ )++ assert managed.selected_model == "nvidia_nim/vendor/model"+ assert managed.provider_key == "fcc-abc123"+ assert managed.key_env == "FCC_HERMES_ABC123"+++def test_hermes_config_rejects_empty_catalog() -> None:+ with pytest.raises(ValueError, match="at least one"):+ build_hermes_managed_config(+ (),+ proxy_root_url="http://127.0.0.1:9191",+ nonce="abc123",+ )+++def test_hermes_config_rejects_unknown_model() -> None:+ with pytest.raises(ValueError, match="not in the FCC catalog"):+ build_hermes_managed_config(+ _models(),+ proxy_root_url="http://127.0.0.1:9191",+ nonce="abc123",+ selected_model="missing/model",+ )++[email protected]("nonce", ["", "not-valid", "spaces here"])+def test_hermes_config_rejects_unsafe_nonce(nonce: str) -> None:+ with pytest.raises(ValueError, match="alphanumeric"):+ build_hermes_managed_config(+ _models(),+ proxy_root_url="http://127.0.0.1:9191",+ nonce=nonce,+ )diff --git a/tests/cli/test_hermes_launcher.py b/tests/cli/test_hermes_launcher.pynew file mode 100644index 00000000..c3b6138d--- /dev/null+++ b/tests/cli/test_hermes_launcher.py@@ -0,0 +1,608 @@+"""Contract tests for the installed `fcc-hermes` launcher."""++import json+import os+import subprocess+from pathlib import Path+from types import SimpleNamespace+from unittest.mock import patch++import pytest++from free_claude_code.cli.launchers.hermes_config import (+ build_hermes_managed_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 _models() -> tuple[ClientModel, ...]:+ return (+ ClientModel(+ wire_slug="nvidia_nim/vendor/model",+ provider_model_ref="nvidia_nim/vendor/model",+ display_name="Nested model",+ allows_reasoning=True,+ ),+ )+++ "argv",+ [+ [],+ ["chat"],+ ["-z", "hello"],+ ["--oneshot=hello"],+ ["--tui"],+ ["--resume", "session-id"],+ ["-c"],+ ["-c", "session name"],+ ["--profile", "coder", "chat", "--query", "hello"],+ ],+)+def test_hermes_attached_surfaces_are_routed(argv: list[str]) -> None:+ from free_claude_code.cli.launchers import hermes++ assert not hermes.is_hermes_passthrough(argv)+ assert not hermes.detached_hermes_surface(argv)+++ "argv",+ [+ ["--help"],+ ["chat", "--help"],+ ["--version"],+ ["setup"],+ ["auth", "list"],+ ["update"],+ ["config", "show"],+ ["model"],+ ["profile", "list"],+ ["sessions", "list"],+ ["plugin-command"],+ ],+)+def test_hermes_management_surfaces_are_native_passthrough(argv: list[str]) -> None:+ from free_claude_code.cli.launchers import hermes++ assert hermes.is_hermes_passthrough(argv)+++ "argv",+ [+ ["acp"],+ ["rl"],+ ["gateway"],+ ["cron"],+ ["serve"],+ ["dashboard"],+ ["gui"],+ ["desktop"],+ ["proxy"],+ ["mcp", "serve"],+ ],+)+def test_hermes_detached_surfaces_are_rejected(argv: list[str]) -> None:+ from free_claude_code.cli.launchers import hermes++ assert hermes.detached_hermes_surface(argv)+ assert not hermes.is_hermes_passthrough(argv)+++ ("argv", "expected"),+ [+ (["--profile", "coder", "chat"], ("--profile", "coder")),+ (["chat", "-p", "coder"], ("-p", "coder")),+ (["--profile=coder", "-z", "hello"], ("--profile=coder",)),+ (["-m", "provider/model", "chat"], ()),+ (["--", "--profile", "not-hermes"], ()),+ ],+)+def test_hermes_profile_selector_matches_upstream_preparse(+ argv: list[str], expected: tuple[str, ...]+) -> None:+ from free_claude_code.cli.launchers.hermes import hermes_profile_args++ assert hermes_profile_args(argv) == expected+++ ("output", "return_code", "expected"),+ [+ ("Hermes Agent v0.20.4 (2026-08-19)\n", 0, (0, 20, 4)),+ ("0.21.0\n", 0, (0, 21, 0)),+ ("Hermes Agent v0.20.3\n", 0, (0, 20, 3)),+ ("not a version\n", 0, None),+ ("Hermes Agent v0.20.4\n", 1, None),+ ],+)+def test_hermes_version_parsing(+ output: str, return_code: int, expected: tuple[int, int, int] | None+) -> None:+ from free_claude_code.cli.launchers import hermes++ with patch.object(+ hermes.subprocess,+ "run",+ return_value=SimpleNamespace(returncode=return_code, stdout=output),+ ):+ assert hermes.hermes_binary_version("resolved-hermes") == expected+++def test_hermes_version_timeout_is_incompatible() -> None:+ from free_claude_code.cli.launchers import hermes++ with patch.object(+ hermes.subprocess, "run", side_effect=subprocess.TimeoutExpired("hermes", 5)+ ):+ assert hermes.hermes_binary_version("resolved-hermes") is None+++def test_hermes_old_version_is_rejected_before_proxy(+ capsys: pytest.CaptureFixture[str],+) -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "hermes_binary_version", return_value=(0, 20, 3)),+ patch.object(hermes, "get_settings") as get_settings,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch([])++ assert exc_info.value.code == 126+ assert "at least version 0.20.4" in capsys.readouterr().err+ get_settings.assert_not_called()+++def test_hermes_management_passthrough_needs_no_proxy() -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "get_settings") as get_settings,+ patch.object(hermes, "require_compatible_hermes") as require_version,+ patch.object(hermes, "run_client_process") as run_client_process,+ ):+ hermes.launch(["config", "show"])++ run_client_process.assert_called_once_with(+ command=["resolved-hermes", "config", "show"],+ env=os.environ,+ binary_name="hermes",+ display_name="Hermes Agent",+ install_hint="Install Hermes Agent from: "+ "https://hermes-agent.nousresearch.com/docs/installation",+ )+ get_settings.assert_not_called()+ require_version.assert_not_called()+++def test_hermes_detached_surface_fails_before_proxy(+ capsys: pytest.CaptureFixture[str],+) -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "get_settings") as get_settings,+ patch.object(hermes, "run_client_process") as run_client_process,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch(["gateway"])++ assert exc_info.value.code == 2+ assert "ordinary hermes" in capsys.readouterr().err+ get_settings.assert_not_called()+ run_client_process.assert_not_called()+++ "argv",+ [+ ["--provider", "openrouter"],+ ["--provider=openrouter"],+ ["chat", "--provider", "openrouter"],+ ],+)+def test_hermes_provider_override_is_rejected(argv: list[str]) -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "get_settings") as get_settings,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch(argv)++ assert exc_info.value.code == 2+ get_settings.assert_not_called()++[email protected]("argv", [["--model"], ["--model="], ["-m"]])+def test_hermes_missing_model_value_is_rejected(argv: list[str]) -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch(argv)++ assert exc_info.value.code == 2+++def test_hermes_duplicate_model_override_is_rejected() -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch(["-m", "one/model", "chat", "--model=two/model"])++ assert exc_info.value.code == 2+++def test_hermes_launch_prepares_validated_catalog_and_selected_model() -> None:+ from free_claude_code.cli.launchers import hermes++ settings = _settings()+ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "require_compatible_hermes"),+ patch.object(hermes, "_system_policy_exists", return_value=False),+ patch.object(hermes, "get_settings", return_value=settings),+ patch.object(hermes, "preflight_proxy", return_value=None),+ patch.object(+ hermes, "fetch_proxy_models_response", return_value=_models_payload()+ ) as fetch_models,+ patch.object(hermes.secrets, "token_hex", return_value="a1b2c3"),+ patch.object(hermes, "_run_with_managed_config") as run_managed,+ ):+ hermes.launch(+ [+ "--profile",+ "coder",+ "chat",+ "--model",+ "nvidia_nim/vendor/model",+ "--query",+ "hello",+ ]+ )++ fetch_models.assert_called_once_with("http://127.0.0.1:9191", "proxy-token")+ call = run_managed.call_args.kwargs+ assert call["binary_path"] == "resolved-hermes"+ assert call["args"] == ["--profile", "coder", "chat", "--query", "hello"]+ assert call["profile_args"] == ("--profile", "coder")+ assert call["managed"].provider_ref == "custom:fcc-a1b2c3"+ assert call["managed"].selected_model == "nvidia_nim/vendor/model"+ assert call["auth_token"] == "proxy-token"+++def test_hermes_unknown_model_fails_before_child(+ capsys: pytest.CaptureFixture[str],+) -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "require_compatible_hermes"),+ patch.object(hermes, "_system_policy_exists", return_value=False),+ patch.object(hermes, "get_settings", return_value=_settings()),+ patch.object(hermes, "preflight_proxy", return_value=None),+ patch.object(+ hermes, "fetch_proxy_models_response", return_value=_models_payload()+ ),+ patch.object(hermes, "_run_with_managed_config") as run_managed,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch(["--model", "missing/model"])++ assert exc_info.value.code == 1+ run_managed.assert_not_called()+ assert "not in the FCC catalog" in capsys.readouterr().err+++def test_hermes_proxy_failure_does_not_fetch_catalog(+ capsys: pytest.CaptureFixture[str],+) -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "require_compatible_hermes"),+ patch.object(hermes, "_system_policy_exists", return_value=False),+ patch.object(hermes, "get_settings", return_value=_settings()),+ patch.object(hermes, "preflight_proxy", return_value="connection refused"),+ patch.object(hermes, "fetch_proxy_models_response") as fetch_models,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch([])++ assert exc_info.value.code == 1+ fetch_models.assert_not_called()+ assert "fcc-server" in capsys.readouterr().err+++def test_hermes_empty_proxy_token_fails_before_health_check(+ capsys: pytest.CaptureFixture[str],+) -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "require_compatible_hermes"),+ patch.object(hermes, "_system_policy_exists", return_value=False),+ patch.object(+ hermes,+ "get_settings",+ return_value=SimpleNamespace(proxy_auth_token=" "),+ ),+ patch.object(hermes, "preflight_proxy") as preflight,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch([])++ assert exc_info.value.code == 1+ preflight.assert_not_called()+ assert "authentication token is empty" in capsys.readouterr().err+++def test_hermes_catalog_failure_never_starts_child(+ capsys: pytest.CaptureFixture[str],+) -> None:+ from free_claude_code.cli.launchers import hermes++ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "require_compatible_hermes"),+ patch.object(hermes, "_system_policy_exists", return_value=False),+ patch.object(hermes, "get_settings", return_value=_settings()),+ patch.object(hermes, "preflight_proxy", return_value=None),+ patch.object(+ hermes,+ "fetch_proxy_models_response",+ side_effect=RuntimeError("catalog unavailable"),+ ),+ patch.object(hermes, "_run_with_managed_config") as run_managed,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch([])++ assert exc_info.value.code == 1+ run_managed.assert_not_called()+ assert "catalog unavailable" in capsys.readouterr().err+++def test_hermes_existing_managed_policy_is_not_shadowed(+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]+) -> None:+ from free_claude_code.cli.launchers import hermes++ monkeypatch.setenv("HERMES_MANAGED_DIR", "administrator-policy")+ with (+ patch.object(hermes, "resolve_client_binary", return_value="resolved-hermes"),+ patch.object(hermes, "get_settings") as get_settings,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes.launch([])++ assert exc_info.value.code == 2+ get_settings.assert_not_called()+ assert "managed policy" in capsys.readouterr().err+++def test_hermes_child_environment_preserves_native_state_and_replaces_owned_keys(+ tmp_path: Path,+) -> None:+ from free_claude_code.cli.launchers.hermes import build_hermes_launcher_env++ env = build_hermes_launcher_env(+ managed_directory=tmp_path,+ key_env="FCC_HERMES_FRESH",+ auth_token="proxy-token",+ proxy_root_url="http://127.0.0.1:9191",+ base_env={+ "PATH": "keep",+ "HERMES_HOME": "native-home",+ "OPENROUTER_API_KEY": "native-key",+ "FCC_HERMES_STALE": "stale",+ "HERMES_MANAGED_DIR": "stale-policy",+ "HERMES_INFERENCE_MODEL": "stale-model",+ "HERMES_INFERENCE_PROVIDER": "stale-provider",+ "NO_PROXY": "example.com",+ },+ )++ assert env["PATH"] == "keep"+ assert env["HERMES_HOME"] == "native-home"+ assert env["OPENROUTER_API_KEY"] == "native-key"+ assert env["HERMES_MANAGED_DIR"] == str(tmp_path)+ assert env["FCC_HERMES_FRESH"] == "proxy-token"+ assert "FCC_HERMES_STALE" not in env+ assert "HERMES_INFERENCE_MODEL" not in env+ assert "HERMES_INFERENCE_PROVIDER" not in env+ assert env["NO_PROXY"] == "example.com,127.0.0.1,localhost,::1"+ assert env["no_proxy"] == env["NO_PROXY"]+++def test_hermes_temporary_overlay_is_verified_and_removed(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from free_claude_code.cli.launchers import hermes++ monkeypatch.setenv("HERMES_HOME", "native-home")+ managed = build_hermes_managed_config(+ _models(),+ proxy_root_url="http://127.0.0.1:9191",+ nonce="abc123",+ )+ observed_directory: Path | None = None++ def fake_run_process(**kwargs: object) -> None:+ nonlocal observed_directory+ command = kwargs["command"]+ env = kwargs["env"]+ assert isinstance(command, list)+ assert isinstance(env, dict)+ assert command == [+ "resolved-hermes",+ "--provider",+ "custom:fcc-abc123",+ "--model",+ "nvidia_nim/vendor/model",+ "--profile",+ "coder",+ "-z",+ "hello",+ ]+ observed_directory = Path(env["HERMES_MANAGED_DIR"])+ config_path = observed_directory / "config.yaml"+ assert config_path.exists()+ if os.name != "nt":+ assert observed_directory.stat().st_mode & 0o777 == 0o700+ assert config_path.stat().st_mode & 0o777 == 0o600+ assert json.loads(config_path.read_text(encoding="utf-8")) == managed.config+ assert "proxy-token" not in config_path.read_text(encoding="utf-8")+ assert env["FCC_HERMES_ABC123"] == "proxy-token"+ assert env["HERMES_HOME"] == "native-home"+ raise SystemExit(0)++ with (+ patch.object(+ hermes.subprocess,+ "run",+ return_value=SimpleNamespace(+ returncode=0,+ stdout='"custom:fcc-abc123"\n',+ stderr="",+ ),+ ) as probe,+ patch.object(+ hermes, "run_client_process", side_effect=fake_run_process+ ) as run_process,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes._run_with_managed_config(+ binary_path="resolved-hermes",+ args=["--profile", "coder", "-z", "hello"],+ profile_args=["--profile", "coder"],+ managed=managed,+ proxy_root_url="http://127.0.0.1:9191",+ auth_token="proxy-token",+ )++ assert exc_info.value.code == 0+ probe.assert_called_once()+ assert probe.call_args.args[0] == [+ "resolved-hermes",+ "--profile",+ "coder",+ "config",+ "get",+ "model.provider",+ "--json",+ ]+ run_process.assert_called_once()+ assert observed_directory is not None+ assert not observed_directory.exists()+++ "probe_result",+ [+ SimpleNamespace(returncode=1, stdout="", stderr="failure"),+ SimpleNamespace(returncode=0, stdout="not-json\n", stderr=""),+ SimpleNamespace(returncode=0, stdout='"custom:other"\n', stderr=""),+ ],+)+def test_hermes_overlay_activation_failure_never_starts_child(+ probe_result: SimpleNamespace,+) -> None:+ from free_claude_code.cli.launchers import hermes++ managed = build_hermes_managed_config(+ _models(),+ proxy_root_url="http://127.0.0.1:9191",+ nonce="abc123",+ )+ with (+ patch.object(hermes.subprocess, "run", return_value=probe_result),+ patch.object(hermes, "run_client_process") as run_process,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes._run_with_managed_config(+ binary_path="resolved-hermes",+ args=[],+ profile_args=[],+ managed=managed,+ proxy_root_url="http://127.0.0.1:9191",+ auth_token="proxy-token",+ )++ assert exc_info.value.code == 1+ run_process.assert_not_called()+++def test_hermes_overlay_activation_timeout_never_starts_child() -> None:+ from free_claude_code.cli.launchers import hermes++ managed = build_hermes_managed_config(+ _models(),+ proxy_root_url="http://127.0.0.1:9191",+ nonce="abc123",+ )+ with (+ patch.object(+ hermes.subprocess,+ "run",+ side_effect=subprocess.TimeoutExpired("hermes", 15),+ ),+ patch.object(hermes, "run_client_process") as run_process,+ pytest.raises(SystemExit) as exc_info,+ ):+ hermes._run_with_managed_config(+ binary_path="resolved-hermes",+ args=[],+ profile_args=[],+ managed=managed,+ proxy_root_url="http://127.0.0.1:9191",+ auth_token="proxy-token",+ )++ assert exc_info.value.code == 1+ run_process.assert_not_called()diff --git a/tests/scripts/test_installers.py b/tests/scripts/test_installers.pyindex 27a48e56..a2ab700a 100644--- a/tests/scripts/test_installers.py+++ b/tests/scripts/test_installers.py@@ -19,6 +19,7 @@ FCC_COMMANDS = ("fcc-pi","fcc-opencode","fcc-cline",+ "fcc-hermes","fcc-init","free-claude-code",)@@ -49,7 +50,16 @@ def _braced_body(text: str, declaration: str) -> str:def _posix_command(name: str) -> str:- version = {"opencode": "1.18.18", "cline": "3.0.55"}.get(name, "1.0.0")+ version = {+ "opencode": "1.18.18",+ "cline": "3.0.55",+ "hermes": "0.20.4",+ }.get(name, "1.0.0")+ version_output = (+ f"Hermes Agent v{version} (test build)"+ if name == "hermes"+ else f"{name} {version}"+ )help_output = (' echo " --extension, -e <path> Load an extension"\n'' echo " --models <patterns> Scope models"'@@ -62,7 +72,7 @@ if [ "$FAIL_STEP" = "{name}-verify" ]; thenexit 31fiif [ "${{1:-}}" = "--version" ]; then- echo "{name} {version}"+ echo "{version_output}"fiif [ "${{1:-}}" = "--help" ]; then{help_output}@@ -116,6 +126,7 @@ if [ "${{1:-}}" = "tool" ] && [ "${{2:-}}" = "install" ]; thencp "$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"+ cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-hermes"if [ "$FAIL_STEP" != "fcc-missing" ]; thencp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-codex"fi@@ -305,7 +316,7 @@ while [ "$#" -gt 0 ]; dodoneecho "download:$url" >> "$CALL_LOG"case "$url:$FAIL_STEP" in- *claude.ai*:claude-download|*chatgpt.com*:codex-download|*pi.dev*:pi-download|*opencode.ai*:opencode-download|*rtk-ai*:rtk-download|*astral.sh*:uv-download)+ *claude.ai*:claude-download|*chatgpt.com*:codex-download|*pi.dev*:pi-download|*opencode.ai*:opencode-download|*hermes-agent.nousresearch.com*:hermes-download|*rtk-ai*:rtk-download|*astral.sh*:uv-download)exit 41;;esac@@ -314,6 +325,7 @@ case "$url" in*chatgpt.com*) source="$FAKE_FIXTURES/codex-installer.sh" ;;*pi.dev*) source="$FAKE_FIXTURES/pi-installer.sh" ;;*opencode.ai*) source="$FAKE_FIXTURES/opencode-installer.sh" ;;+ *hermes-agent.nousresearch.com*) source="$FAKE_FIXTURES/hermes-installer.sh" ;;*rtk-ai*)if [ "$FAIL_STEP" = "rtk-install" ]; thenprintf 'invalid archive\n' > "$output"@@ -371,6 +383,16 @@ echo "opencode-install" >> "$CALL_LOG"mkdir -p "$HOME/.opencode/bin"cp "$FAKE_FIXTURES/opencode-command.sh" "$HOME/.opencode/bin/opencode"chmod +x "$HOME/.opencode/bin/opencode"+""",+ )+ _write_executable(+ fixtures / "hermes-installer.sh",+ """#!/bin/sh+echo "hermes-install:$*" >> "$CALL_LOG"+[ "$FAIL_STEP" = "hermes-install" ] && exit 26+mkdir -p "$HOME/.local/bin"+cp "$FAKE_FIXTURES/hermes-command.sh" "$HOME/.local/bin/hermes"+chmod +x "$HOME/.local/bin/hermes"""",)_write_executable(@@ -388,6 +410,7 @@ chmod +x "$HOME/.local/bin/uv"_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"))+ _write_executable(fixtures / "hermes-command.sh", _posix_command("hermes"))rtk_command = _posix_rtk_command().encode()with tarfile.open(fixtures / "rtk-x86_64-unknown-linux-musl.tar.gz", "w:gz"@@ -474,6 +497,9 @@ def test_install_sh_fresh_install_is_verified(posix_harness: PosixHarness) -> Noassert 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("hermes-install:--non-interactive --skip-setup") < calls.index(+ "hermes:--version"+ )assert calls.index("uv-install") < calls.index("uv:--version")assert any(call.startswith(@@ -489,6 +515,65 @@ def test_install_sh_fresh_install_is_verified(posix_harness: PosixHarness) -> No"uv:tool dir --bin","fcc-server:--version",]+ assert not any("hermes:setup" in call for call in calls)+++def test_install_sh_installs_selected_hermes_without_setup(+ posix_harness: PosixHarness,+) -> None:+ result = posix_harness.run_interactive("n\nn\nn\nn\nn\ny\nn\n")++ assert result.returncode == 0, result.stdout+ calls = posix_harness.calls()+ assert "download:https://hermes-agent.nousresearch.com/install.sh" in calls+ assert "hermes-install:--non-interactive --skip-setup" in calls+ assert calls.index("hermes-install:--non-interactive --skip-setup") < calls.index(+ "hermes:--version"+ )+ assert "Run Hermes Agent with: fcc-hermes" in result.stdout+ assert not any("hermes:setup" in call for call in calls)+ assert not any(call.startswith("rtk:init") for call in calls)++[email protected]("failure", ["hermes-download", "hermes-install"])+def test_install_sh_stops_when_selected_hermes_install_fails(+ posix_harness: PosixHarness,+ failure: str,+) -> None:+ result = posix_harness.run_interactive("n\nn\nn\nn\nn\ny\nn\n", fail_step=failure)++ assert result.returncode != 0+ assert "Free Claude Code is installed and verified." not in result.stdout+ assert not any("astral.sh" in call for call in posix_harness.calls())+++def test_install_sh_rejects_unsupported_hermes_platform_before_download(+ posix_harness: PosixHarness,+) -> None:+ posix_harness.env["FAKE_UNAME"] = "Darwin"+ posix_harness.env["FAKE_UNAME_MACHINE"] = "x86_64"++ result = posix_harness.run_interactive("n\nn\nn\nn\nn\ny\nn\n")++ assert result.returncode != 0+ assert "does not provide a supported release for Darwin x86_64" in result.stdout+ assert not any(+ "hermes-agent.nousresearch.com" in call for call in posix_harness.calls()+ )+++def test_install_sh_preserves_compatible_existing_hermes(+ posix_harness: PosixHarness,+) -> None:+ posix_harness.add_client("hermes")++ result = posix_harness.run()++ assert result.returncode == 0, result.stderr+ assert "Hermes Agent 0.20.4 already satisfies >=0.20.4" in result.stdout+ assert not any(+ "hermes-agent.nousresearch.com" in call for call in posix_harness.calls()+ )def test_install_sh_installs_and_configures_rtk_for_selected_agents(@@ -577,7 +662,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\nn\ny\n")+ result = posix_harness.run_interactive("n\ny\nn\nn\nn\nn\ny\n")assert result.returncode == 0, result.stdoutassert "verifying it without updating it" in result.stdout@@ -624,7 +709,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\nn\ny\nn\nn\nn\nn\n")+ result = posix_harness.run_interactive("n\nn\nn\nn\nn\nn\nn\ny\nn\nn\nn\nn\nn\n")assert result.returncode == 0, result.stdoutassert "Select at least one coding agent." in result.stdout@@ -643,7 +728,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\nn\n", fail_step="pi-skip")+ result = posix_harness.run_interactive("n\nn\ny\nn\nn\nn\nn\n", fail_step="pi-skip")assert result.returncode != 0assert "No selected coding agent was installed." in result.stdout@@ -744,6 +829,7 @@ def test_install_sh_preserves_valid_existing_tools(posix_harness.add_client("codex")posix_harness.add_client("pi")posix_harness.add_client("cline")+ posix_harness.add_client("hermes")posix_harness.add_uv(uv_version)result = posix_harness.run()@@ -1182,7 +1268,16 @@ def _windows_shortcut_icon(def _batch_client(name: str) -> str:- version = {"opencode": "1.18.18", "cline": "3.0.55"}.get(name, "1.0.0")+ version = {+ "opencode": "1.18.18",+ "cline": "3.0.55",+ "hermes": "0.20.4",+ }.get(name, "1.0.0")+ version_output = (+ f"Hermes Agent v{version} (test build)"+ if name == "hermes"+ else f"{name} {version}"+ )help_output = ("echo --extension, -e ^<path^> Load an extension\n""echo --models ^<patterns^> Scope models"@@ -1192,7 +1287,7 @@ def _batch_client(name: str) -> str:return f"""@echo offecho {name}:%*>>"%CALL_LOG%"if "%FAIL_STEP%"=="{name}-verify" exit /b 51-if "%1"=="--version" echo {name} {version}+if "%1"=="--version" echo {version_output}if "%1"=="--help" ({help_output})@@ -1237,6 +1332,7 @@ copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-claude.cmd" >nulcopy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-pi.cmd" >nulcopy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-opencode.cmd" >nulcopy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-cline.cmd" >nul+copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-hermes.cmd" >nulif not "%FAIL_STEP%"=="fcc-missing" copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-codex.cmd" >nulexit /b 0:update_shell@@ -1364,6 +1460,9 @@ def powershell_harness((fixtures / "cline-command.cmd").write_text(_batch_client("cline"), encoding="utf-8")+ (fixtures / "hermes-command.cmd").write_text(+ _batch_client("hermes"), 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(@@ -1409,6 +1508,19 @@ $bin = if ($env:FAKE_NPM_PREFIX) { $env:FAKE_NPM_PREFIX } else { Join-Path $env:New-Item -ItemType Directory -Force -Path $bin | Out-NullCopy-Item (Join-Path $env:FAKE_FIXTURES "pi-command.cmd") (Join-Path $bin "pi.cmd") -ForceAdd-Content -LiteralPath $env:CALL_LOG -Value "pi-install"+""",+ encoding="utf-8",+ )+ (fixtures / "hermes-installer.ps1").write_text(+ r"""param(+ [switch] $NonInteractive,+ [switch] $SkipSetup+)+if ($env:FAIL_STEP -eq "hermes-install") { exit 65 }+$bin = Join-Path $env:LOCALAPPDATA "hermes\hermes-agent\bin"+New-Item -ItemType Directory -Force -Path $bin | Out-Null+Copy-Item (Join-Path $env:FAKE_FIXTURES "hermes-command.cmd") (Join-Path $bin "hermes.cmd") -Force+Add-Content -LiteralPath $env:CALL_LOG -Value "hermes-install:${NonInteractive}:${SkipSetup}"""",encoding="utf-8",)@@ -1454,6 +1566,7 @@ function Invoke-RestMethod {($env:FAIL_STEP -eq "codex-download" -and $Uri.Contains("chatgpt.com")) -or($env:FAIL_STEP -eq "pi-download" -and $Uri.Contains("pi.dev")) -or($env:FAIL_STEP -eq "opencode-download" -and $Uri.Contains("anomalyco/opencode")) -or+ ($env:FAIL_STEP -eq "hermes-download" -and $Uri.Contains("hermes-agent.nousresearch.com")) -or($env:FAIL_STEP -eq "rtk-download" -and $Uri.Contains("rtk-ai/rtk")) -or($env:FAIL_STEP -eq "uv-download" -and $Uri.Contains("astral.sh"))) {@@ -1468,6 +1581,9 @@ function Invoke-RestMethod {elseif ($Uri.Contains("pi.dev")) {$source = Join-Path $env:FAKE_FIXTURES "pi-installer.ps1"}+ elseif ($Uri.Contains("hermes-agent.nousresearch.com")) {+ $source = Join-Path $env:FAKE_FIXTURES "hermes-installer.ps1"+ }elseif ($Uri.Contains("opencode-windows-")) {if ($env:FAIL_STEP -eq "opencode-archive") {Set-Content -LiteralPath $OutFile -Value "not a zip"@@ -1566,6 +1682,9 @@ def test_install_ps1_fresh_install_is_verified(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 any("hermes-agent.nousresearch.com/install.ps1" in call for call in calls)+ assert "hermes-install:True:True" in calls+ assert not any("hermes:setup" in call for call in calls)assert calls.index("uv-install") < calls.index("uv:--version")assert any(call.startswith(@@ -1607,6 +1726,84 @@ def test_install_ps1_fresh_install_is_verified().is_file()+def test_install_ps1_preserves_compatible_existing_hermes(+ powershell_harness: PowerShellHarness,+) -> None:+ powershell_harness.add_client("hermes")++ result = powershell_harness.run()++ assert result.returncode == 0, result.stderr+ assert "Hermes Agent 0.20.4 already satisfies >=0.20.4" in result.stdout+ assert not any(+ "hermes-agent.nousresearch.com" in call for call in powershell_harness.calls()+ )+++def test_install_ps1_upgrades_old_hermes_with_noninteractive_setup_skipped(+ powershell_harness: PowerShellHarness,+) -> None:+ hermes_bin = (+ Path(powershell_harness.env["LOCALAPPDATA"]) / "hermes" / "hermes-agent" / "bin"+ )+ hermes_bin.mkdir(parents=True)+ (hermes_bin / "hermes.cmd").write_text(+ _batch_client("hermes").replace("v0.20.4", "v0.19.9"),+ encoding="utf-8",+ )++ result = powershell_harness.run()++ assert result.returncode == 0, result.stderr+ calls = powershell_harness.calls()+ assert any("hermes-agent.nousresearch.com/install.ps1" in call for call in calls)+ assert "hermes-install:True:True" in calls+ assert not any("hermes:setup" in call for call in calls)+ assert not any(call.startswith("rtk:init") for call in calls)+++def test_install_ps1_stops_when_hermes_upgrade_fails(+ powershell_harness: PowerShellHarness,+) -> None:+ hermes_bin = (+ Path(powershell_harness.env["LOCALAPPDATA"]) / "hermes" / "hermes-agent" / "bin"+ )+ hermes_bin.mkdir(parents=True)+ (hermes_bin / "hermes.cmd").write_text(+ _batch_client("hermes").replace("v0.20.4", "v0.19.9"),+ encoding="utf-8",+ )++ result = powershell_harness.run(fail_step="hermes-install")++ assert result.returncode != 0+ assert "Free Claude Code is installed and verified." not in result.stdout+ assert not any("astral.sh" in call for call in powershell_harness.calls())+++def test_install_ps1_rejects_unsupported_hermes_architecture_before_download(+ powershell_harness: PowerShellHarness,+) -> None:+ hermes_bin = (+ Path(powershell_harness.env["LOCALAPPDATA"]) / "hermes" / "hermes-agent" / "bin"+ )+ hermes_bin.mkdir(parents=True)+ (hermes_bin / "hermes.cmd").write_text(+ _batch_client("hermes").replace("v0.20.4", "v0.19.9"),+ encoding="utf-8",+ )+ powershell_harness.env["PROCESSOR_ARCHITECTURE"] = "MIPS"+ powershell_harness.env["PROCESSOR_ARCHITEW6432"] = "MIPS"++ result = powershell_harness.run()++ assert result.returncode != 0+ assert "does not provide a supported Windows release" in result.stderr+ assert not any(+ "hermes-agent.nousresearch.com" in call for call in powershell_harness.calls()+ )++def test_install_ps1_selects_official_opencode_arm64_archive(powershell_harness: PowerShellHarness,) -> None:@@ -1803,6 +2000,7 @@ def test_install_ps1_preserves_valid_existing_tools(powershell_harness.add_client("codex")powershell_harness.add_client("pi")powershell_harness.add_client("cline")+ powershell_harness.add_client("hermes")powershell_harness.add_uv(uv_version)result = powershell_harness.run()@@ -2158,8 +2356,8 @@ Invoke-DownloadedPowerShellInstaller `("answers", "expected", "expected_messages"),[(- ("", "", "", "", "", ""),- "True,True,True,True,False,False",+ ("", "", "", "", "", "", ""),+ "True,True,True,True,False,True,False",(),),(@@ -2171,13 +2369,15 @@ Invoke-DownloadedPowerShellInstaller `"n","n","n",+ "n","y","n","n","n",+ "n","y",),- "False,True,False,False,False,True",+ "False,True,False,False,False,False,True",("Please answer Y or N.", "Select at least one coding agent."),),],@@ -2201,6 +2401,7 @@ $script:InstallCodex = $true$script:InstallPi = $true$script:InstallOpenCode = $true$script:InstallCline = $false+$script:InstallHermes = $true$script:EnableRtk = $falsefunction Read-Host {{param([string] $Prompt)@@ -2211,7 +2412,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:InstallCline),$($script:EnableRtk)"+Write-Output "selection:$($script:InstallClaudeCode),$($script:InstallCodex),$($script:InstallPi),$($script:InstallOpenCode),$($script:InstallCline),$($script:InstallHermes),$($script:EnableRtk)""""result = subprocess.run(@@ -2238,6 +2439,7 @@ $script:InstallCodex = $true$script:InstallPi = $false$script:InstallOpenCode = $false$script:InstallCline = $false+$script:InstallHermes = $false$script:PiAvailable = $false$script:Calls = @()function Write-Step {{ param([string] $Message) }}@@ -2246,6 +2448,7 @@ 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-Hermes {{ $script:Calls += "hermes" }}function Ensure-SelectedCodingAgents {{{body}}}Ensure-SelectedCodingAgentsWrite-Output "calls:$($script:Calls -join ',')"@@ -2276,6 +2479,7 @@ $script:InstallCodex = $true$script:InstallPi = $true$script:InstallOpenCode = $false$script:InstallCline = $false+$script:InstallHermes = $false$script:PiAvailable = $false$script:Calls = @()function Write-Step {{ param([string] $Message) }}@@ -2311,6 +2515,7 @@ $script:InstallCodex = $false$script:InstallPi = $true$script:InstallOpenCode = $false$script:InstallCline = $false+$script:InstallHermes = $false$script:PiAvailable = $falsefunction Write-Step {{ param([string] $Message) }}function Ensure-ClaudeCode {{ }}@@ -2318,6 +2523,7 @@ function Ensure-Codex {{ }}function Ensure-Pi {{ }}function Ensure-OpenCode {{ }}function Ensure-Cline {{ }}+function Ensure-Hermes {{ }}function Ensure-SelectedCodingAgents {{{body}}}Ensure-SelectedCodingAgents"""diff --git a/tests/scripts/test_uninstallers.py b/tests/scripts/test_uninstallers.pyindex 0f0c7880..9953ff8a 100644--- a/tests/scripts/test_uninstallers.py+++ b/tests/scripts/test_uninstallers.py@@ -14,6 +14,7 @@ FCC_COMMANDS = ("fcc-pi","fcc-opencode","fcc-cline",+ "fcc-hermes","fcc-init","free-claude-code",)@@ -136,6 +137,10 @@ def posix_uninstall_harness(tmp_path: Path) -> PosixUninstallHarness:_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 / "hermes", "#!/bin/sh\nexit 0\n")+ hermes_state = home / ".hermes" / "sessions" / "state.json"+ hermes_state.parent.mkdir(parents=True)+ hermes_state.write_text('{"native": true}\n', encoding="utf-8")_write_executable(bin_dir / "pgrep","""#!/bin/sh@@ -167,7 +172,7 @@ if [ "${1:-}" = "tool" ] && [ "${2:-}" = "uninstall" ]; thenecho 'Tool `free-claude-code` is not installed' >&2exit 2fi- for name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline fcc-init free-claude-code; do+ for name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-cline fcc-hermes fcc-init free-claude-code; do/bin/rm -f "$FAKE_TOOL_BIN/$name"doneecho "Uninstalled free-claude-code"@@ -238,6 +243,10 @@ def test_uninstall_sh_removes_and_verifies_only_fcc(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.bin_dir / "hermes").exists()+ assert (+ posix_uninstall_harness.home / ".hermes" / "sessions" / "state.json"+ ).read_text(encoding="utf-8") == '{"native": true}\n'assert posix_uninstall_harness.calls() == ["uv:tool dir --bin","uv:tool uninstall free-claude-code",@@ -475,16 +484,20 @@ def powershell_uninstall_harness(tool_bin = tmp_path / "tool-bin"fcc_home = home / ".fcc"app_data = tmp_path / "app-data"+ local_app_data = tmp_path / "local-app-data"log = tmp_path / "calls.log"- for path in (bin_dir, tool_bin, fcc_home, app_data):+ for path in (bin_dir, tool_bin, fcc_home, app_data, local_app_data):path.mkdir(parents=True)(fcc_home / "config.json").write_text("{}", encoding="utf-8")for name in FCC_COMMANDS:(tool_bin / f"{name}.cmd").write_text("@echo off\nexit /b 0\n", encoding="utf-8")- for name in ("claude", "codex", "pi", "opencode", "cline"):+ for name in ("claude", "codex", "pi", "opencode", "cline", "hermes"):(bin_dir / f"{name}.cmd").write_text("@echo off\nexit /b 0\n", encoding="utf-8")+ hermes_state = local_app_data / "hermes" / "state.json"+ hermes_state.parent.mkdir(parents=True)+ hermes_state.write_text('{"native": true}\n', encoding="utf-8")uv_commands = " ".join(FCC_COMMANDS)(bin_dir / "uv.cmd").write_text(@@ -579,6 +592,7 @@ else {"HOME": str(home),"USERPROFILE": str(home),"APPDATA": str(app_data),+ "LOCALAPPDATA": str(local_app_data),"CALL_LOG": str(log),"FAKE_TOOL_BIN": str(tool_bin),"FCC_UNINSTALLER": str(_repo_root() / "scripts" / "uninstall.ps1"),@@ -610,6 +624,10 @@ def test_uninstall_ps1_removes_and_verifies_only_fcc(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.bin_dir / "hermes.cmd").exists()+ assert (+ Path(powershell_uninstall_harness.env["LOCALAPPDATA"]) / "hermes" / "state.json"+ ).read_text(encoding="utf-8") == '{"native": true}\n'assert powershell_uninstall_harness.calls() == ["uv:tool dir --bin","uv:tool uninstall free-claude-code",diff --git a/uv.lock b/uv.lockindex 812c9ba8..9893439d 100644--- a/uv.lock+++ b/uv.lock@@ -607,7 +607,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "5.8.2"+version = "5.9.0"source = { editable = "." }dependencies = [{ name = "aiohttp" },