{"record":{"id":"7e48b79d007a0216","repo":"headroomlabs-ai/headroom","slug":"error-openclaude-not-found-in-path","errorCode":null,"errorMessage":"Error: 'openclaude' not found in PATH.","messagePattern":"Error: 'openclaude' not found in PATH\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/wrap.py","lineNumber":6117,"sourceCode":"\n    \\b\n    OpenClaude is a prose-format coding CLI (like Aider / Cline); it speaks\n    OpenAI- and Anthropic-compatible HTTP, so wrap routes both base URLs\n    through the local proxy — same env shape as `wrap aider`.\n\n    \\b\n    Examples:\n        headroom wrap openclaude                         # Start proxy + openclaude\n        headroom wrap openclaude -- --model gpt-4o       # Pass args to openclaude\n    \"\"\"\n    if prepare_only:\n        return\n\n    openclaude_bin = shutil.which(\"openclaude\")\n    if not openclaude_bin:\n        click.echo(\"Error: 'openclaude' not found in PATH.\")\n        click.echo(\"Install OpenClaude before running `headroom wrap openclaude`.\")\n        raise SystemExit(1)\n\n    env, env_vars_display = _build_aider_launch_env(\n        port, os.environ, project=_project_name_from_cwd()\n    )\n\n    _launch_tool(\n        binary=openclaude_bin,\n        args=openclaude_args,\n        env=env,\n        port=port,\n        no_proxy=no_proxy,\n        tool_label=\"OPENCLAUDE\",\n        env_vars_display=env_vars_display,\n        learn=learn,\n        memory=memory,\n        agent_type=\"openclaude\",\n        code_graph=code_graph,\n        backend=backend,","sourceCodeStart":6099,"sourceCodeEnd":6135,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L6099-L6135","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install OpenClaude using its project's official method so the `openclaude` binary lands on PATH","Verify resolution: `which openclaude` in the same shell that runs headroom","Add the tool's install bin dir to PATH (e.g. ~/.cargo/bin, ~/.local/bin) and re-export in the current shell","If you only need proxy preparation, use --prepare-only which skips the binary check"],"exampleFix":"# before\nheadroom wrap openclaude\n# Error: 'openclaude' not found in PATH.\n\n# after\n# install per OpenClaude's docs, then:\nexport PATH=\"$HOME/.cargo/bin:$PATH\"\nwhich openclaude && headroom wrap openclaude -- --model gpt-4o","handlingStrategy":"type-guard","validationCode":"import shutil\n\nif not shutil.which(\"openclaude\"):\n    raise SystemExit(\"Install OpenClaude before running `headroom wrap openclaude`\")","typeGuard":"import shutil\n\ndef openclaude_available() -> bool:\n    \"\"\"True when the openclaude binary is resolvable on PATH.\"\"\"\n    return shutil.which(\"openclaude\") is not None","tryCatchPattern":null,"preventionTips":["Install OpenClaude so a real executable named `openclaude` is on PATH","Include language-tool bin dirs (~/.cargo/bin, dev containers' paths) in PATH","Verify with `which openclaude` before wrapping"],"tags":["path","installation","openclaude","cli","headroom"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}