{"record":{"id":"f4cfd3a88e639351","repo":"headroomlabs-ai/headroom","slug":"error-claude-not-found-in-path","errorCode":null,"errorMessage":"Error: 'claude' not found in PATH.","messagePattern":"Error: 'claude' not found in PATH\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/wrap.py","lineNumber":4756,"sourceCode":"\n    \\b\n    Examples:\n        headroom wrap claude                    # Start everything (Serena code memory)\n        headroom wrap claude --memory           # With persistent memory\n        headroom wrap claude --resume <id>      # Resume a session\n        headroom wrap claude -- -p              # Claude in print mode\n        headroom wrap claude --no-mcp           # Skip MCP retrieve tool registration\n        headroom wrap claude --code-memory none # No code-memory MCP\n        headroom wrap claude --1m               # Preserve the 1M context window\n    \"\"\"\n    if prepare_only:\n        return\n\n    claude_bin = shutil.which(\"claude\")\n    if not claude_bin:\n        click.echo(\"Error: 'claude' not found in PATH.\")\n        click.echo(\"Install Claude Code: https://docs.anthropic.com/en/docs/claude-code\")\n        raise SystemExit(1)\n\n    # Validate --tool-search up front so a typo fails before we start the proxy.\n    if tool_search is not None:\n        tool_search = _normalize_tool_search_mode(tool_search)\n\n    proxy_holder: list[subprocess.Popen | None] = [None]\n    _saved_base_url: list[str | None] = [None]  # previous settings.json value for restore\n    _tool_search_not_written = object()\n    _saved_tool_search: list[object | str | None] = [_tool_search_not_written]\n    _settings_foundry: list[bool] = [False]\n    port_holder: list[int] = [port]\n    _settings_vertex: list[bool] = [False]\n    # Bind before the try so the finally can always reference it. It is otherwise\n    # only assigned inside the try (after _ensure_proxy, which can raise), so an\n    # early proxy-start failure would make the finally raise UnboundLocalError,\n    # masking the real error and skipping cleanup(). Mirrors the holders above.\n    _wrap_settings_path = Path.cwd() / \".claude\" / \"settings.local.json\"\n    _raise_on_claude_auth_conflict(","sourceCodeStart":4738,"sourceCodeEnd":4774,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L4738-L4774","documentation":"Before wrapping Claude Code, Headroom resolves the `claude` binary with shutil.which('claude'). If it is not on PATH, it prints this error plus the official install URL and raises SystemExit(1) — no proxy is started, nothing is modified. The check is skipped entirely when --prepare-only is passed.","triggerScenarios":"Running `headroom wrap claude` (without --prepare-only) on a machine where `claude` is not installed or not on PATH: Claude Code never installed, installed via a node version manager whose bin dir isn't in this shell's PATH, or installed only for a different user.","commonSituations":"Fresh machines; nvm/fnm users opening a shell without loading the node version that owns the global npm bin; installing Claude Code with a different package manager (native installer) that puts `claude` in a non-PATH location; CI images that install headroom but not claude.","solutions":["Install Claude Code: npm install -g @anthropic-ai/claude-code (or the official installer at docs.anthropic.com)","Verify resolution in the same shell: `which claude` — if empty, fix PATH to include the npm global bin dir","For nvm users, run `nvm use <version>` in the shell before `headroom wrap claude`","If you only want proxy/config preparation without launching, use `headroom wrap claude --prepare-only`"],"exampleFix":"# before\nheadroom wrap claude\n# Error: 'claude' not found in PATH.\n\n# after\nnpm install -g @anthropic-ai/claude-code\nwhich claude && headroom wrap claude","handlingStrategy":"type-guard","validationCode":"import shutil\n\nif not shutil.which(\"claude\"):\n    raise SystemExit(\"Install Claude Code first: npm install -g @anthropic-ai/claude-code\")","typeGuard":"import shutil\n\ndef claude_available() -> bool:\n    \"\"\"True when the Claude Code CLI is resolvable on PATH.\"\"\"\n    return shutil.which(\"claude\") is not None","tryCatchPattern":null,"preventionTips":["Run `which claude` in the same shell that launches headroom","For nvm users, load the node version owning the global install first","Automate the check in setup scripts before calling headroom wrap claude"],"tags":["path","installation","claude-code","cli","headroom"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}