headroomlabs-ai/headroom · error · SystemExit

Error: 'codex' not found in PATH.

Error message

Error: 'codex' not found in PATH.

What it means

Before wrapping OpenAI Codex CLI, Headroom resolves the `codex` binary with shutil.which('codex'). If it is not on PATH, it prints this error, suggests the npm install command, and raises SystemExit(1) before touching Codex config (~/.codex/config.toml) or starting the proxy. An earlier branch delegates to shared preparation when prepare_only is set, bypassing this check.

Source

Thrown at headroom/cli/wrap.py:5821

        ensure_proxy_dependencies()

    if prepare_only:
        _prepare_codex_wrap_state(
            port=port,
            no_mcp=no_mcp,
            no_tokensave=no_tokensave,
            serena=serena,
            no_serena=no_serena,
            memory=memory,
            verbose=verbose,
        )
        return

    codex_bin = shutil.which("codex")
    if not codex_bin:
        click.echo("Error: 'codex' not found in PATH.")
        click.echo("Install Codex CLI: npm install -g @openai/codex")
        raise SystemExit(1)

    active_codex_home = _codex_home_dir()
    _offer_dangling_codex_recovery(active_codex_home)
    _prepare_codex_wrap_state(
        port=port,
        no_mcp=no_mcp,
        no_tokensave=no_tokensave,
        serena=serena,
        no_serena=no_serena,
        memory=memory,
        verbose=verbose,
        persistent_routing=False,
    )

    env, env_vars_display = _build_codex_launch_env(port, os.environ)
    env["CODEX_HOME"] = str(active_codex_home)

    def configure_codex_launch(

View on GitHub (pinned to 322425c43b)

Solutions

1. Install Codex CLI: npm install -g @openai/codex
2. Run `nvm use <version>` (or ensure the npm global bin dir is on PATH) in the launching shell
3. Verify resolution first: `which codex && codex --version`
4. Use `headroom wrap codex --prepare-only` if you only want config/MCP preparation without launching Codex

Example fix

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

# after
npm install -g @openai/codex
which codex && headroom wrap codex

import shutil

if not shutil.which("codex"):
    raise SystemExit("Install Codex CLI first: npm install -g @openai/codex")

import shutil

def codex_available() -> bool:
    """True when the OpenAI Codex CLI is resolvable on PATH."""
    return shutil.which("codex") is not None

When it happens

Trigger: Running `headroom wrap codex` (without --prepare-only) where `codex` is not installed or not resolvable on PATH: never installed, installed under a node version manager's bin dir absent from PATH, or installed via a package that names the binary differently.

Common situations: nvm/fnm shells without `nvm use` loading the version that owns the global install; installing @openai/codex for a different user; CI images with headroom but not codex; stale shell after install.

Related errors

• Error: 'claude' not found in PATH.
• Error: 'copilot' not found in PATH.
• Error: 'aider' not found in PATH.
• Error: 'openclaude' 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/c67c631ec9c3b985. Report an issue: GitHub.