headroomlabs-ai/headroom · error · SystemExit

Error: 'grok' not found in PATH.

Error message

Error: 'grok' not found in PATH.

What it means

Before wrapping Grok CLI, Headroom resolves the `grok` binary with shutil.which('grok'). If missing, it prints this error with the x.ai docs URL and raises SystemExit(1). This happens after shared wrap-state preparation (_prepare_* with force=True) but before building the Grok launch environment, so some wrap state may already be prepared when this fires.

Source

Thrown at headroom/cli/wrap.py:6399

    _setup_coding_compressor(
        GrokRegistrar(),
        serena_context="grok",
        serena=serena,
        no_serena=no_serena,
        no_tokensave=no_tokensave,
        verbose=verbose,
        force=True,
    )

    if prepare_only:
        return

    grok_bin = shutil.which("grok")
    if not grok_bin:
        click.echo("Error: 'grok' not found in PATH.")
        click.echo("Install Grok CLI: https://docs.x.ai/docs/grok-cli")
        raise SystemExit(1)

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

    _launch_tool(
        binary=grok_bin,
        args=grok_args,
        env=env,
        port=port,
        no_proxy=no_proxy,
        tool_label="GROK",
        env_vars_display=env_vars_display,
        learn=learn,
        memory=memory,
        agent_type="grok",
        code_graph=code_graph,
        backend=backend,

View on GitHub (pinned to 322425c43b)

Solutions

1. Install Grok CLI per https://docs.x.ai/docs/grok-cli
2. Verify resolution: `which grok && grok --version` in the same shell
3. Export the install bin dir (e.g. export PATH="$HOME/.local/bin:$PATH") and `hash -r` before retrying
4. Use --prepare-only if you only need the proxy and config prepared without launching Grok

Example fix

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

# after
# install per docs.x.ai/docs/grok-cli, then:
which grok && headroom wrap grok

import shutil

if not shutil.which("grok"):
    raise SystemExit("Install Grok CLI first: https://docs.x.ai/docs/grok-cli")

import shutil

def grok_available() -> bool:
    """True when the Grok CLI binary is resolvable on PATH."""
    return shutil.which("grok") is not None

When it happens

Trigger: Running `headroom wrap grok` (without --prepare-only) where the `grok` executable is not installed or not on PATH — e.g. Grok CLI not installed, or installed under ~/.local/bin / a package-manager bin dir absent from the launching shell's PATH.

Common situations: Grok CLI not yet installed on the machine; installed via npm but the shell doesn't include the global bin dir; stale shell after install; CI containers with headroom but not grok.

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: 'openclaude' not found in PATH.

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