no agent CLI found: install claude, codebuddy, codex, copilo

Error message

no agent CLI found: install claude, codebuddy, codex, copilot, opencode, deveco, openclaw, hermes, pi, omp, cursor-agent, kimi, reasonix, dsh, kiro-cli, agy, qodercli, qoderclicn, traecli, grok, qwen, or qwenpaw and ensure it is on PATH

What it means

Daemon config load fails when probeAgentCLIs() finds none of the ~22 supported agent CLIs (claude, codex, opencode, qwen, ...) on PATH and AllowNoAgents is not set. The daemon refuses to start because it would have nothing to execute tasks with. The error doubles as installation guidance listing every recognized agent.

Source

Thrown at server/internal/daemon/config.go:240

		// Per-machine custom-runtime command path overrides (MUL-3284).
		// Copy into our own map so later mutation of the loaded config can't
		// alias daemon state, and so an empty map normalizes to nil.
		if len(cliCfg.ProfileCommandOverrides) > 0 {
			profileCommandOverrides = make(map[string]string, len(cliCfg.ProfileCommandOverrides))
			for id, path := range cliCfg.ProfileCommandOverrides {
				if id == "" || strings.TrimSpace(path) == "" {
					continue
				}
				profileCommandOverrides[id] = path
			}
		}
	}

	// Discover installed agent CLIs. Extracted so the periodic workspace sync
	// can re-run the same discovery on a live daemon (MUL-5439).
	agents := probeAgentCLIs()
	if len(agents) == 0 && !overrides.AllowNoAgents {
		return Config{}, fmt.Errorf("no agent CLI found: install claude, codebuddy, codex, copilot, opencode, deveco, openclaw, hermes, pi, omp, cursor-agent, kimi, reasonix, dsh, kiro-cli, agy, qodercli, qoderclicn, traecli, grok, qwen, or qwenpaw and ensure it is on PATH")
	}

	claudeArgs, err := shellArgsFromEnv("MULTICA_CLAUDE_ARGS")
	if err != nil {
		return Config{}, err
	}
	codexArgs, err := shellArgsFromEnv("MULTICA_CODEX_ARGS")
	if err != nil {
		return Config{}, err
	}
	codebuddyArgs, err := shellArgsFromEnv("MULTICA_CODEBUDDY_ARGS")
	if err != nil {
		return Config{}, err
	}
	qwenArgs, err := shellArgsFromEnv("MULTICA_QWEN_ARGS")
	if err != nil {
		return Config{}, err
	}

View on GitHub (pinned to 2c0912b6ec)

Solutions

Install any one listed agent CLI (e.g. npm i -g @anthropic-ai/claude-code) and confirm 'which claude' works in the same shell/user the daemon runs as
If the agent exists but the daemon can't see it, fix PATH for the daemon context (systemd Environment=, launchd plist, or wrapper script)
If you deliberately want an agent-less daemon, set the AllowNoAgents override in the daemon config
Use a profile command override (profileCommandOverrides) to point at an absolute agent path if PATH discovery is unreliable

Example fix

// before
agents := probeAgentCLIs()
if len(agents) == 0 && !overrides.AllowNoAgents {
    return Config{}, fmt.Errorf("no agent CLI found: install claude, ... or qwenpaw and ensure it is on PATH")
}

// after: allow explicit opt-out via env for headless/relay deployments
if len(agents) == 0 && !overrides.AllowNoAgents && os.Getenv("MULTICA_ALLOW_NO_AGENTS") != "1" {
    return Config{}, fmt.Errorf("no agent CLI found: install claude, ... or qwenpaw and ensure it is on PATH (or set MULTICA_ALLOW_NO_AGENTS=1 for agent-less mode)")
}

Defensive patterns

Strategy: fallback

Validate before calling

// Before daemon start, verify at least one known agent is resolvable.
executables := []string{"claude", "codex", "opencode", "qwen" /* ... */}
found := false
for _, name := range executables {
    if _, err := exec.LookPath(name); err == nil {
        found = true
        break
    }
}
if !found && !allowNoAgents {
    // fail with actionable message before the daemon starts
}

Try / catch

Not a catch-and-continue case: handle at startup orchestration — catch the config error, print install guidance, and exit; or set AllowNoAgents to explicitly enter agent-less mode.

Prevention

For service contexts, set explicit PATH including npm/pnpm global bin dirs
Use absolute-path profile overrides when PATH discovery is unreliable
Bake at least one agent CLI into container images used for the daemon

When it happens

Trigger: Starting the daemon on a machine with no agent CLI installed, with all of them installed outside PATH (npm global bins, ~/.local/bin not on PATH for the daemon's service context), or in a container/CI image that never installed one.

Common situations: Fresh machines, systemd/launchd services whose PATH is minimal (/usr/bin only, missing ~/.local/bin or nvm paths), devcontainers, and users who intentionally run daemon-only mode without agents.

Related errors

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/66a3b4750aeb12a1. Report an issue: GitHub.