chenhg5/cc-connect · error

tmux: 'tmux' not found in PATH

Error message

tmux: 'tmux' not found in PATH

What it means

New() runs exec.LookPath("tmux") to verify the tmux binary is invocable and fails construction when it is not on PATH. This catches the missing external dependency at agent-creation time instead of failing later on every exec call.

Source

Thrown at agent/tmux/tmux.go:125

	var stripPatterns []string
	switch v := opts["strip_patterns"].(type) {
	case []string:
		stripPatterns = v
	case []any:
		for _, item := range v {
			if s, ok := item.(string); ok {
				stripPatterns = append(stripPatterns, s)
			}
		}
	case nil:
		// default: strip Claude Code's mode status line
		stripPatterns = []string{`⏵⏵.*\(shift\+tab to cycle\)`}
	}

	windowPerSession, _ := opts["window_per_session"].(bool)

	if _, err := exec.LookPath("tmux"); err != nil {
		return nil, fmt.Errorf("tmux: 'tmux' not found in PATH")
	}

	return &Agent{
		sessionName:      sessionName,
		pane:             pane,
		workDir:          workDir,
		autoCreate:       autoCreate,
		shell:            shell,
		initCmd:          initCmd,
		startupWaitMs:    startupWaitMs,
		promptPat:        promptPat,
		pollMs:           pollMs,
		stripInputBlock:  stripInputBlock,
		stripPatterns:    stripPatterns,
		windowPerSession: windowPerSession,
	}, nil
}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Install tmux (apt/brew/dnf install tmux)
2. Ensure the tmux binary's directory is in PATH for the cc-connect process; for systemd use Environment=PATH=... in the unit
3. Symlink tmux into a PATH directory: ln -s $(which tmux) /usr/local/bin/tmux
4. Verify with: sudo -u <cc-connect-user> which tmux

Example fix

// before
# systemd unit
eEnvironment omitted -> PATH=/usr/bin:/bin, tmux in /usr/local/bin not found

// after
# /etc/systemd/system/cc-connect.service
[Service]
Environment=PATH=/usr/local/bin:/usr/bin:/bin

if _, err := exec.LookPath("tmux"); err != nil {
    return errors.New("tmux binary required: install tmux or fix PATH for the cc-connect process")
}

_, err := tmux.New(opts)
if err != nil && strings.Contains(err.Error(), "not found in PATH") {
    slog.Error("tmux missing", "hint", "install tmux and ensure PATH includes it in daemon env")
    return err
}

When it happens

Trigger: core.CreateAgent("tmux", opts) on a machine where tmux is not installed or is outside PATH for the process running cc-connect (e.g. systemd/launchd service with a minimal PATH, or tmux installed via a package manager into a non-standard prefix).

Common situations: tmux never installed on the host; daemon environment has PATH=/usr/bin:/bin while tmux lives in /usr/local/bin or ~/.linuxbrew/bin; container image missing tmux.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• antigravitySession: start: %w
• 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

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