Skip to content

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

Python

Add Hermes as an FCC-routed coding harness (#1484)

Ali Khokhar548c264949b0
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 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 Anthropic
Messages 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 messages
into managed client CLI sessions.
@@ -30,6 +31,8 @@ flowchart LR
Codex[Codex CLI, IDE, and App] --> ProxyAPI
Pi[Pi Coding Agent] --> ProxyAPI
OpenCode[OpenCode CLI] --> ProxyAPI
+ Cline[Cline CLI] --> ProxyAPI
+ Hermes[Hermes Agent] --> ProxyAPI
AdminUI[Local Admin UI] --> ProxyAPI
Bots[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 relies
on, including an FCC-scoped model catalog, attached local sessions, and
process-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/uni
and [scripts/uninstall.ps1](scripts/uninstall.ps1) remove those exact desktop
artifacts, the FCC uv tool, and the managed `~/.fcc/` tree from
[config/paths.py](src/free_claude_code/config/paths.py); they do not remove
-uv, Claude Code, Codex, Pi, OpenCode, 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 those
neutral 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 providers
inside 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 by
Discord and Telegram messaging. Managed task invocations extend the same proxy
environment only with non-interactive terminal settings, optional `--resume`,
@@ -1370,7 +1401,7 @@ reports a count-only failure, and leaves failures available for the next cleanup
attempt. Real-session registration is collision-safe and becomes durable tree
state only after the manager accepts it.
-Codex, Pi, OpenCode, and Cline are supported through their installed launchers. FCC
+Codex, Pi, OpenCode, Cline, and Hermes are supported through their installed launchers. FCC
does not keep internal managed session runners for them because no user-facing
messaging setting selects those clients for Discord or Telegram.
diff --git a/README.md b/README.md
index 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:
```bash
fcc-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 Client
For 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 entries
macOS/Linux:
diff --git a/pyproject.toml b/pyproject.toml
index 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.ps1
index 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 $commandName
if (-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.sh
index 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=0
voice_nim=0
@@ -27,6 +29,7 @@ install_codex=1
install_pi=1
install_opencode=1
install_cline=0
+install_hermes=1
enable_rtk=0
torch_backend=""
temporary_file=""
@@ -128,7 +131,18 @@ choose_coding_agents() {
install_cline=0
fi
- if [ "$install_claude" -eq 1 ] || [ "$install_codex" -eq 1 ] || [ "$install_pi" -eq 1 ] || [ "$install_opencode" -eq 1 ] || [ "$install_cline" -eq 1 ]; then
+ 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 ]; then
break
fi
printf 'Select at least one coding agent.\n\n' >&4
@@ -290,16 +304,26 @@ download_and_run() {
url=$1
interpreter=$2
label=$3
- non_interactive=${4:-0}
+ shift 3
+ non_interactive=0
+ if [ "$#" -gt 0 ]; then
+ non_interactive=$1
+ shift
+ fi
if [ "$dry_run" -eq 1 ]; then
print_command curl -fsSL "$url" -o "<temporary-script>"
if [ "$non_interactive" -eq 1 ]; then
printf '+ 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>" "$@"
fi
return 0
fi
@@ -322,16 +346,20 @@ download_and_run() {
quote_arg "$interpreter"
printf ' '
quote_arg "$temporary_file"
+ for arg in "$@"; do
+ printf ' '
+ quote_arg "$arg"
+ done
printf '\n'
- if CODEX_NON_INTERACTIVE=1 "$interpreter" "$temporary_file"; then
+ if CODEX_NON_INTERACTIVE=1 "$interpreter" "$temporary_file" "$@"; then
:
else
status=$?
fail "$label installation failed with exit code $status."
fi
else
- print_command "$interpreter" "$temporary_file"
- if "$interpreter" "$temporary_file"; then
+ print_command "$interpreter" "$temporary_file" "$@"
+ if "$interpreter" "$temporary_file" "$@"; then
:
else
status=$?
@@ -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 ]; then
step "Ensuring Claude Code is installed"
@@ -749,7 +859,12 @@ ensure_selected_coding_agents() {
ensure_cline
fi
- if [ "$install_claude" -eq 0 ] && [ "$install_codex" -eq 0 ] && [ "$pi_available" -eq 0 ] && [ "$install_opencode" -eq 0 ] && [ "$install_cline" -eq 0 ]; then
+ 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 ]; then
fail "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 ]; then
print_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 --version
return 0
fi
@@ -954,7 +1069,7 @@ configure_and_verify_free_claude_code() {
export PATH
hash -r 2>/dev/null || true
- for command_name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode 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_directories
if command -v cline >/dev/null 2>&1 || command -v npm >/dev/null 2>&1; then
install_cline=1
fi
+if ! command -v hermes >/dev/null 2>&1 && ! hermes_platform_is_supported; then
+ install_hermes=0
+fi
step "Checking for running Free Claude Code processes"
assert_no_fcc_processes_running
@@ -1067,7 +1185,7 @@ fi
step "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 ]; then
require_command bash
fi
require_command sh
@@ -1124,4 +1242,9 @@ else
else
printf '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'
+ fi
fi
diff --git a/scripts/uninstall.ps1 b/scripts/uninstall.ps1
index 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.sh
index 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=0
uv_tool_bin=""
@@ -298,5 +298,5 @@ if [ "$dry_run" -eq 1 ]; then
printf '\nDry run complete. No changes were made.\n'
else
printf '\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'
fi
diff --git a/smoke/README.md b/smoke/README.md
index 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.py
index 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.py
index 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.py
index 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 Path
import pytest
+from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.core.json_types import JsonObject, JsonValue
from smoke.lib.claude_cli_matrix import run_claude_cli
from smoke.lib.config import SmokeConfig
@@ -268,6 +269,122 @@ def test_cline_cli_prompt_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None
assert "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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 config
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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" ]; then
exit 31
fi
if [ "${{1:-}}" = "--version" ]; then
- echo "{name} {version}"
+ echo "{version_output}"
fi
if [ "${{1:-}}" = "--help" ]; then
{help_output}
@@ -116,6 +126,7 @@ if [ "${{1:-}}" = "tool" ] && [ "${{2:-}}" = "install" ]; then
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-pi"
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-opencode"
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-cline"
+ cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-hermes"
if [ "$FAIL_STEP" != "fcc-missing" ]; then
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-codex"
fi
@@ -305,7 +316,7 @@ while [ "$#" -gt 0 ]; do
done
echo "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" ]; then
printf '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) -> No
assert calls.index("pi-install") < calls.index("pi:--version")
assert calls.index("opencode-install") < calls.index("opencode:--version")
assert calls.index("npm:install -g cline") < calls.index("cline:--version")
+ assert calls.index("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.stdout
assert "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.stdout
assert "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 != 0
assert "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 off
echo {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" >nul
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-pi.cmd" >nul
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-opencode.cmd" >nul
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-cline.cmd" >nul
+copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-hermes.cmd" >nul
if not "%FAIL_STEP%"=="fcc-missing" copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-codex.cmd" >nul
exit /b 0
:update_shell
@@ -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-Null
Copy-Item (Join-Path $env:FAKE_FIXTURES "pi-command.cmd") (Join-Path $bin "pi.cmd") -Force
Add-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 = $false
function 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-SelectedCodingAgents
Write-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 = $false
function 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.py
index 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" ]; then
echo 'Tool `free-claude-code` is not installed' >&2
exit 2
fi
- for name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-opencode fcc-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"
done
echo "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.lock
index 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" },