NousResearch/hermes-agent · error · RuntimeError

Could not start Copilot ACP command '{self._acp_command}'. I

Error message

Could not start Copilot ACP command '{self._acp_command}'. Install GitHub Copilot CLI or set HERMES_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH.

What it means

Hermes failed to spawn the GitHub Copilot ACP process because the configured command binary does not exist (subprocess.Popen raised FileNotFoundError). The command comes from HERMES_COPILOT_ACP_COMMAND / COPILOT_CLI_PATH or the default 'copilot' resolution. The message tells you to install the new GitHub Copilot CLI or point Hermes at it explicitly.

Source

Thrown at agent/copilot_acp_client.py:522

    def _run_prompt(self, prompt_text: str, *, timeout_seconds: float) -> tuple[str, str]:
        try:
            # Hide the console the CLI child would otherwise flash on Windows
            # (#56747). Hide-only — stdio pipes stay intact for the ACP wire.
            from hermes_cli._subprocess_compat import windows_hide_flags

            proc = subprocess.Popen(
                [self._acp_command] + self._acp_args,
                stdin=subprocess.PIPE,
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
                text=True, encoding='utf-8', errors='replace',
                bufsize=1,
                cwd=self._acp_cwd,
                env=_build_subprocess_env(),
                creationflags=windows_hide_flags(),
            )
        except FileNotFoundError as exc:
            raise RuntimeError(
                f"Could not start Copilot ACP command '{self._acp_command}'. "
                "Install GitHub Copilot CLI or set HERMES_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH."
            ) from exc

        if proc.stdin is None or proc.stdout is None:
            proc.kill()
            raise RuntimeError("Copilot ACP process did not expose stdin/stdout pipes.")

        self.is_closed = False
        with self._active_process_lock:
            self._active_process = proc

        inbox: queue.Queue[dict[str, Any]] = queue.Queue()
        stderr_tail: deque[str] = deque(maxlen=40)

        def _stdout_reader() -> None:
            if proc.stdout is None:
                return

View on GitHub (pinned to c896c09c42)

Solutions

Install the new CLI: npm install -g @github/copilot, then verify with copilot --help.
If installed but not found, set export HERMES_COPILOT_ACP_COMMAND=/path/to/copilot (or COPILOT_CLI_PATH).
Confirm the command is executable (which copilot; chmod +x if needed).
Alternatively switch to the non-ACP 'copilot' provider via hermes setup, which hits the Copilot API directly with a subscription token.

Example fix

# before
# copilot not installed → FileNotFoundError at spawn
# after
npm install -g @github/copilot
copilot --help   # verify
# or pin explicitly:
export HERMES_COPILOT_ACP_COMMAND=/usr/local/bin/copilot

Defensive patterns

Strategy: validation

Validate before calling

import shutil

def copilot_available(command: str = 'copilot') -> bool:
    return shutil.which(command) is not None

Try / catch

try:
    client = CopilotACPClient(...)
except RuntimeError as e:
    if 'Could not start Copilot ACP command' in str(e):
        # install CLI or set HERMES_COPILOT_ACP_COMMAND, then retry
        ...

Prevention

Verify 'copilot' resolves on PATH before selecting the copilot_acp provider
Pin HERMES_COPILOT_ACP_COMMAND to the absolute binary path in automation environments
Install via npm install -g @github/copilot and confirm with copilot --help

When it happens

Trigger: Starting Copilot ACP mode (provider copilot_acp) when 'copilot' is not on PATH, or HERMES_COPILOT_ACP_COMMAND points to a nonexistent or non-executable file. Popen raises FileNotFoundError and this RuntimeError wraps it.

Common situations: Copilot CLI not installed; installed locally via npm but not on the shell PATH Hermes sees; HERMES_COPILOT_ACP_COMMAND set to a stale path after an upgrade; using the deprecated `gh copilot` extension name.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/726729a01bb3f5c5. Report an issue: GitHub.