chenhg5/cc-connect · error

claudecode: %q CLI not found in PATH, please install it firs

Error message

claudecode: %q CLI not found in PATH, please install it first

What it means

Pre-flight validation in the claudecode agent factory: exec.LookPath cannot find the configured claude binary in the supervisor's PATH. The %q is the command name looked up. Skipped when run_as_user is set, since the target user's PATH is what matters there.

Source

Thrown at agent/claudecode/claudecode.go:235

	// the project-level config field by cmd/cc-connect/main.go.
	spawnOpts := core.SpawnOptions{}
	spawnOpts.RunAsUser, _ = opts["run_as_user"].(string)
	if env, ok := opts["run_as_env"].([]any); ok {
		for _, v := range env {
			if s, ok := v.(string); ok {
				spawnOpts.EnvAllowlist = append(spawnOpts.EnvAllowlist, s)
			}
		}
	} else if env, ok := opts["run_as_env"].([]string); ok {
		spawnOpts.EnvAllowlist = append(spawnOpts.EnvAllowlist, env...)
	}

	// When run_as_user is set, the target user's PATH is what matters;
	// skip the supervisor-side LookPath check and let spawn fail loudly
	// at runtime if the target doesn't have claude installed.
	if !spawnOpts.IsolationMode() {
		if _, err := exec.LookPath(cmd); err != nil {
			return nil, fmt.Errorf("claudecode: %q CLI not found in PATH, please install it first", 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.
	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 Claude Code CLI (npm i -g @anthropic-ai/claude-code)
2. Put the binary's directory on the daemon's PATH
3. Or set the agent cmd option to the binary's absolute path

When it happens

Trigger: Thrown at agent/claudecode/claudecode.go:235 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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