chenhg5/cc-connect · error

codex: %q CLI not found in PATH, install with: npm install -

Error message

codex: %q CLI not found in PATH, install with: npm install -g @openai/codex

What it means

The codex agent constructor validates at creation time that the `codex` CLI binary exists on PATH via exec.LookPath. If the binary cannot be found (or the configured command name resolves to nothing), New() refuses to build the agent and returns this error instead of failing later at session start. It exists so misconfiguration surfaces immediately with an actionable install hint.

Source

Thrown at agent/codex/codex.go:75

	if workDir == "" {
		workDir = "."
	}
	model, _ := opts["model"].(string)
	reasoningEffort, _ := opts["reasoning_effort"].(string)
	mode, _ := opts["mode"].(string)
	backend, _ := opts["backend"].(string)
	appServerURL, _ := opts["app_server_url"].(string)
	codexHome, _ := opts["codex_home"].(string)
	systemPrompt, _ := opts["system_prompt"].(string)
	appendPrompt, _ := opts["append_system_prompt"].(string)
	mode = normalizeMode(mode)
	backend = normalizeBackend(backend)
	appServerURL = normalizeAppServerURL(appServerURL)

	cmd, cliExtraArgs := core.ParseCmdOpts(opts, "codex")

	if _, err := exec.LookPath(cmd); err != nil {
		return nil, fmt.Errorf("codex: %q CLI not found in PATH, install with: npm install -g @openai/codex", cmd)
	}

	// Parse project-level env from opts["env"] (set via [projects.agent.options.env] in config.toml).
	// Stored separately from runtime sessionEnv so SetSessionEnv calls cannot overwrite it.
	// MergeEnv semantics ensure these override any same-named keys inherited from os.Environ()
	// when the codex subprocess is spawned (e.g. user-scoped HTTPS_PROXY leaking into the agent).
	var configEnv []string
	if envMap, ok := opts["env"].(map[string]string); ok {
		for k, v := range envMap {
			configEnv = append(configEnv, k+"="+v)
		}
	} else if envMap, ok := opts["env"].(map[string]any); ok {
		for k, v := range envMap {
			if s, ok := v.(string); ok {
				configEnv = append(configEnv, k+"="+s)
			}
		}
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Install the CLI: npm install -g @openai/codex, then verify with `which codex`.
2. If codex is installed but not found, add its directory (e.g. $(npm config get prefix)/bin) to PATH for the process running cc-connect.
3. If you use a custom binary name/path, set opts["cmd"] in [projects.agent.options] to an executable that exists and is executable.
4. For daemons, ensure the systemd/launchd unit environment includes the PATH entry containing codex.

Example fix

// before
agent, err := codex.New(core.AgentOptions{}) // fails: CLI not found
// after
// config.toml
[projects.agent.options]
cmd = "/usr/local/bin/codex"  # or install: npm install -g @openai/codex

cmd := "codex" // or opts["cmd"]
if _, err := exec.LookPath(cmd); err != nil {
    return fmt.Errorf("codex CLI %q not installed; run: npm install -g @openai/codex", cmd)
}
agent, err := codex.New(opts)

When it happens

Trigger: Calling core.CreateAgent("codex", opts) / New() when opts["cmd"] names an executable absent from PATH, or when the default "codex" command is not installed. Also triggered in tests that construct the agent without a stub binary on PATH.

Common situations: Fresh machines or CI containers where npm global bin is not on PATH; user installed codex under a different name or via a version manager not sourced in the service environment; config sets cmd to a custom wrapper that does not exist; systemd/daemon environments with a restricted PATH missing ~/.npm-global/bin.

Related errors

• claudecode: 'claude' CLI not found in PATH
• copilot: %q CLI not found in PATH, please install it first
• gemini: %q CLI not found in PATH, install with: npm i -g @go
• kimi: %q CLI not found in PATH, install with: pip install ki
• opencode: %q CLI not found in PATH, install from: https://gi

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/20543b2222a3f9de. Report an issue: GitHub.