headroomlabs-ai/headroom · error · SystemExit

Error: 'openclaude' not found in PATH.

Error message

Error: 'openclaude' not found in PATH.

What it means

Before wrapping openclaude, Headroom resolves the `openclaude` binary with shutil.which('openclaude'). If missing, it prints this error with a generic 'install OpenClaude' hint (no URL) and raises SystemExit(1) before building the aider-style launch environment or starting the proxy. Guarded by the prepare_only early return.

Source

Thrown at headroom/cli/wrap.py:6117

    \b
    OpenClaude is a prose-format coding CLI (like Aider / Cline); it speaks
    OpenAI- and Anthropic-compatible HTTP, so wrap routes both base URLs
    through the local proxy — same env shape as `wrap aider`.

    \b
    Examples:
        headroom wrap openclaude                         # Start proxy + openclaude
        headroom wrap openclaude -- --model gpt-4o       # Pass args to openclaude
    """
    if prepare_only:
        return

    openclaude_bin = shutil.which("openclaude")
    if not openclaude_bin:
        click.echo("Error: 'openclaude' not found in PATH.")
        click.echo("Install OpenClaude before running `headroom wrap openclaude`.")
        raise SystemExit(1)

    env, env_vars_display = _build_aider_launch_env(
        port, os.environ, project=_project_name_from_cwd()
    )

    _launch_tool(
        binary=openclaude_bin,
        args=openclaude_args,
        env=env,
        port=port,
        no_proxy=no_proxy,
        tool_label="OPENCLAUDE",
        env_vars_display=env_vars_display,
        learn=learn,
        memory=memory,
        agent_type="openclaude",
        code_graph=code_graph,
        backend=backend,

View on GitHub (pinned to 322425c43b)

Solutions

1. Install OpenClaude using its project's official method so the `openclaude` binary lands on PATH
2. Verify resolution: `which openclaude` in the same shell that runs headroom
3. Add the tool's install bin dir to PATH (e.g. ~/.cargo/bin, ~/.local/bin) and re-export in the current shell
4. If you only need proxy preparation, use --prepare-only which skips the binary check

Example fix

# before
headroom wrap openclaude
# Error: 'openclaude' not found in PATH.

# after
# install per OpenClaude's docs, then:
export PATH="$HOME/.cargo/bin:$PATH"
which openclaude && headroom wrap openclaude -- --model gpt-4o

import shutil

if not shutil.which("openclaude"):
    raise SystemExit("Install OpenClaude before running `headroom wrap openclaude`")

import shutil

def openclaude_available() -> bool:
    """True when the openclaude binary is resolvable on PATH."""
    return shutil.which("openclaude") is not None

When it happens

Trigger: Running `headroom wrap openclaude` (without --prepare-only) where the `openclaude` executable is not installed or not on PATH. Headroom makes no assumptions about install method; the user must have built/installed it so the binary resolves.

Common situations: OpenClaude not yet installed on the machine; installed via a language-specific tool (cargo/npm/go) whose bin dir isn't on PATH in the launching shell; installed only in a container while Headroom runs on the host.

Related errors

• Error: 'claude' not found in PATH.
• Error: 'copilot' not found in PATH.
• Error: 'codex' not found in PATH.
• Error: 'aider' not found in PATH.
• Error: 'vibe' not found in PATH.

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/7e48b79d007a0216. Report an issue: GitHub.