chenhg5/cc-connect · error

opencode: %q CLI not found in PATH, install from: https://gi

Error message

opencode: %q CLI not found in PATH, install from: https://github.com/opencode-ai/opencode

What it means

opencode.New validates that the configured opencode CLI binary exists via exec.LookPath before returning the Agent; if not found in PATH, construction fails with this message pointing at the project's install URL. It is a startup-time configuration error: the factory refuses to build an agent that could never launch a session.

Source

Thrown at agent/opencode/opencode.go:83

	workDir, _ := opts["work_dir"].(string)
	if workDir == "" {
		workDir = "."
	}
	model, _ := opts["model"].(string)
	mode, _ := opts["mode"].(string)
	mode = normalizeMode(mode)
	cmd, extraArgs := core.ParseCmdOpts(opts, "opencode")
	agentName, _ := opts["agent"].(string) // --agent flag for plugin-defined agents (#1210)
	ccDataDir, _ := opts["cc_data_dir"].(string)
	ccProject, _ := opts["cc_project"].(string)
	modelCachePath := opencodeProjectModelCachePath(ccDataDir, ccProject)
	persistentModelCache, err := loadOpencodePersistentModelCache(modelCachePath)
	if err != nil {
		slog.Warn("opencode: load persistent model cache failed", "path", modelCachePath, "err", err)
	}

	if _, err := exec.LookPath(cmd); err != nil {
		return nil, fmt.Errorf("opencode: %q CLI not found in PATH, install from: https://github.com/opencode-ai/opencode", cmd)
	}

	return &Agent{
		workDir:              workDir,
		model:                model,
		mode:                 mode,
		cmd:                  cmd,
		cliExtraArgs:         extraArgs,
		configEnv:            core.ParseConfigEnv(opts),
		agentName:            agentName,
		activeIdx:            -1,
		modelCachePath:       modelCachePath,
		persistentModelCache: persistentModelCache,
	}, nil
}

func opencodeProjectModelCachePath(dataDir, project string) string {
	if dataDir == "" || project == "" {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Install opencode (https://github.com/opencode-ai/opencode) e.g. `go install github.com/opencode-ai/opencode@latest` or grab a release binary.
2. Verify in the daemon's environment: `sudo -u <user> which opencode`; fix PATH in the service unit or set the absolute path in config.toml.
3. If the command is customized, set the agent's command config option to the full binary path.
4. Ensure the binary is executable: `chmod +x $(which opencode)`.

Example fix

// config.toml — before
[agents.opencode]
command = "opencode"  # not on the daemon's PATH

// after
[agents.opencode]
command = "/home/user/go/bin/opencode"

if _, err := exec.LookPath("opencode"); err != nil {
    // install or point config.toml at the absolute binary path before constructing the agent
    return fmt.Errorf("opencode CLI must be installed: https://github.com/opencode-ai/opencode")
}

agent, err := opencode.New(workDir, model, mode, opts)
if err != nil {
    if strings.Contains(err.Error(), "CLI not found in PATH") {
        return fmt.Errorf("please install opencode (see project README) or set the command path in config.toml")
    }
    return err
}

When it happens

Trigger: Calling New() (directly or via core.CreateAgent from config.toml) when the `opencode` binary is absent from the current process's PATH, or the configured command name/alias does not exist.

Common situations: opencode not installed at all; installed via npm/go-install into a bin dir not on the daemon's PATH under systemd; typo in the agent command config; container images that omit the CLI.

Related errors

• copilot: %q CLI not found in PATH, please install it first
• kimi: %q CLI not found in PATH, install with: pip install ki
• qoder: %q not found in PATH, install with: curl -fsSL https:
• acp: command %q not found in PATH: %w
• antigravitySession: start: %w

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