chenhg5/cc-connect · error

tmux: 'session' option is required (name of the tmux session

Error message

tmux: 'session' option is required (name of the tmux session to attach)

What it means

tmux agent's New() validates its options map and refuses to construct the agent when the required 'session' option is absent or empty. The agent attaches to a named tmux session, so without it no target can be determined. This is a constructor-time configuration validation error, not a runtime tmux error.

Source

Thrown at agent/tmux/tmux.go:46

	shell           string
	initCmd         string // command to run once after a new session is created (e.g. "claude")
	startupWaitMs   int    // milliseconds to wait after init_command before accepting messages
	promptPat       string
	pollMs          int
	stripInputBlock bool     // strip the ───/❯/─── input area block from output
	stripPatterns   []string // per-line regex patterns to strip from output
	// windowPerSession, when true, gives each cc-connect session its own tmux
	// window (and thus its own init_command/agent instance) instead of sharing
	// the single session:pane target. Required for true per-session isolation
	// (e.g. session_scope = "thread" on the platform).
	windowPerSession bool
	mu               sync.RWMutex
}

func New(opts map[string]any) (core.Agent, error) {
	sessionName, _ := opts["session"].(string)
	if sessionName == "" {
		return nil, fmt.Errorf("tmux: 'session' option is required (name of the tmux session to attach)")
	}

	pane, _ := opts["pane"].(string)
	if pane == "" {
		pane = "0"
	}

	workDir, _ := opts["work_dir"].(string)
	if workDir == "" {
		workDir = "."
	}

	autoCreate := true
	if v, ok := opts["auto_create"].(bool); ok {
		autoCreate = v
	}

	shell, _ := opts["shell"].(string)

View on GitHub (pinned to 4000b2338a)

Solutions

1. Add options.session = "<tmux-session-name>" to the tmux agent's config block
2. Ensure the value is non-empty after any variable interpolation
3. See agent/tmux docs for the full options set (pane, work_dir, auto_create, shell, window_per_session)

Example fix

// before (config.toml)
[[agents]]
type = "tmux"
[agents.options]
pane = "0"

// after
[[agents]]
type = "tmux"
[agents.options]
session = "my-session"
pane = "0"

func validateTmuxOpts(opts map[string]any) error {
    s, _ := opts["session"].(string)
    if strings.TrimSpace(s) == "" { return errors.New("tmux agent requires options.session") }
    return nil
}

func sessionOpt(opts map[string]any) (string, bool) {
    s, ok := opts["session"].(string)
    return s, ok && s != ""
}

a, err := tmux.New(opts)
if err != nil && strings.Contains(err.Error(),"'session' option is required") {
    return fmt.Errorf("config: tmux agent block missing options.session: %w", err)
}

When it happens

Trigger: Creating the agent via core.CreateAgent("tmux", opts) (or directly New(opts)) with opts missing the 'session' key, or with session set to "" (e.g. empty TOML value in config.toml).

Common situations: config.toml [[agents]] block for the tmux agent missing options.session; session name interpolated from an unset env var resulting in ""; copy-pasting an example config that omitted the field.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• tmux: session %q does not exist and auto_create is disabled
• tmux: create session %q: %w
• config: relay.visibility must be "full", "summary", or "none
• config: at least one [[projects]] entry is required
• config: %s.name is required

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