feat(multi): tmux keys to toggle broadcast and exclude single panes

In windows opened by netssh multi, prefix S toggles broadcast for all
panes and prefix e excludes the current pane (a pane-level
synchronize-panes off, shown as [SOLO] in the border) or includes it
again. netssh sync --pane does the same from a shell.

S and e are unbound in a default tmux (E would be "spread evenly").
netssh writes the bindings to a small tmux config and sources it, binds
a key only if the user's tmux.conf does not use it (netssh's own earlier
binding is refreshed), and the bindings act only in windows marked
@netssh. multi.sync_key and multi.solo_key change the keys or turn them
off (none); also in the configurator. zellij syncs whole tabs only, so
excluding a pane is tmux-only.

testenv: the render test presses the keys through the xterm client
(send-keys -K) and checks [SOLO], that broadcast skips the excluded
pane, that S toggles, and that other windows are unaffected. The client
gets GNU grep: BusyBox grep -oF counted only one match per line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/multiplex/multiplex.go

@@ -22,7 +22,10 @@ type Options struct {
 	Label     string // window, session, and tab name
 	Sync      bool   // type into all panes of a window at once
 	PerWindow int    // panes per tmux window or zellij tab
-	LayoutDir string // where zellij layout files are written
+	LayoutDir string // where zellij layout files and tmux key bindings are written
+	// SyncKey and SoloKey are tmux prefix keys that toggle broadcast for the
+	// window and exclude the current pane from it; empty means no binding.
+	SyncKey, SoloKey string
 	// Hint receives notes for the user before the process is replaced.
 	Hint func(string)
 }
@@ -98,8 +101,30 @@ func Open(kind string, panes []Pane, opts Options, r Runner) error {
 	return fmt.Errorf("unknown multiplexer %q", kind)
 }
 
-// ToggleSync switches broadcast input in the current tmux window or zellij tab.
-func ToggleSync(r Runner) (string, error) {
+// ToggleSync switches broadcast input in the current tmux window or zellij
+// tab; with pane it excludes the current tmux pane from it or includes it again.
+func ToggleSync(r Runner, pane bool) (string, error) {
+	if pane {
+		if r.Getenv("TMUX") == "" {
+			if r.Getenv("ZELLIJ") != "" {
+				return "", errors.New("zellij broadcasts to a whole tab; single panes cannot be excluded")
+			}
+			return "", errors.New("netssh sync --pane works inside tmux")
+		}
+		solo, err := r.Output("tmux", "display-message", "-p", "#{@netssh_solo}")
+		if err != nil {
+			return "", err
+		}
+		for _, argv := range soloToggle(solo == "1") {
+			if _, err := r.Output(argv...); err != nil {
+				return "", err
+			}
+		}
+		if solo == "1" {
+			return "pane included in broadcast", nil
+		}
+		return "pane excluded from broadcast", nil
+	}
 	switch {
 	case r.Getenv("TMUX") != "":
 		current, err := r.Output("tmux", "show-window-options", "-v", "synchronize-panes")

internal/multiplex/multiplex_test.go

@@ -16,6 +16,8 @@ type fake struct {
 	exec      []string
 	files     map[string]string
 	syncState string
+	keys      map[string]string // existing prefix bindings by key
+	solo      string
 	n         int
 }
 
@@ -42,6 +44,10 @@ func (f *fake) Output(argv ...string) (string, error) {
 		return "", errors.New("can't find session")
 	case "show-window-options":
 		return f.syncState, nil
+	case "list-keys":
+		return f.keys[argv[4]], nil
+	case "display-message":
+		return f.solo, nil
 	}
 	return "", nil
 }
@@ -94,7 +100,7 @@ func TestDetect(t *testing.T) {
 
 func TestTmuxInside(t *testing.T) {
 	f := newFake(map[string]string{"TMUX": "/tmp/tmux-1/default"}, "tmux")
-	if err := Open(Tmux, panes("a", "b", "c"), Options{Label: "pve", Sync: true}, f); err != nil {
+	if err := Open(Tmux, panes("a", "b", "c"), Options{Label: "pve", Sync: true, SyncKey: "S", SoloKey: "e", LayoutDir: "/tmp/l"}, f); err != nil {
 		t.Fatal(err)
 	}
 	script := "sh -c " + paneScript + " netssh-pane /usr/bin/netssh "
@@ -107,9 +113,14 @@ func TestTmuxInside(t *testing.T) {
 		"tmux set-option -p -t %1 @netssh_host a",
 		"tmux set-option -p -t %2 @netssh_host b",
 		"tmux set-option -p -t %4 @netssh_host c",
+		"tmux set-window-option -t @1 @netssh 1",
 		"tmux set-window-option -t @1 pane-border-status top",
-		"tmux set-window-option -t @1 pane-border-format  #{@netssh_host}#{?pane_synchronized, [SYNC],} ",
+		"tmux set-window-option -t @1 pane-border-format  #{@netssh_host}#{?pane_synchronized, [SYNC],#{?@netssh_solo, [SOLO],}} ",
 		"tmux set-window-option -t @1 synchronize-panes on",
+		"tmux show-options -gv prefix",
+		"tmux list-keys -T prefix S",
+		"tmux list-keys -T prefix e",
+		"tmux source-file /tmp/l/netssh-multi.tmux.conf",
 		"tmux select-window -t @1",
 	}
 	if strings.Join(f.calls, "\n") != strings.Join(want, "\n") {
@@ -195,18 +206,76 @@ func TestZellijInsideAddsTabs(t *testing.T) {
 
 func TestToggleSync(t *testing.T) {
 	f := newFake(map[string]string{"TMUX": "x"})
-	if state, err := ToggleSync(f); err != nil || state != "broadcast on" || f.calls[1] != "tmux set-window-option synchronize-panes on" {
+	if state, err := ToggleSync(f, false); err != nil || state != "broadcast on" || f.calls[1] != "tmux set-window-option synchronize-panes on" {
 		t.Fatalf("%q %v %v", state, err, f.calls)
 	}
 	f.syncState = "on"
-	if state, _ := ToggleSync(f); state != "broadcast off" {
+	if state, _ := ToggleSync(f, false); state != "broadcast off" {
 		t.Fatalf("%q", state)
 	}
 	z := newFake(map[string]string{"ZELLIJ": "0"})
-	if _, err := ToggleSync(z); err != nil || z.calls[0] != "zellij action toggle-active-sync-tab" {
+	if _, err := ToggleSync(z, false); err != nil || z.calls[0] != "zellij action toggle-active-sync-tab" {
 		t.Fatalf("%v %v", err, z.calls)
 	}
-	if _, err := ToggleSync(newFake(nil)); err == nil {
+	if _, err := ToggleSync(newFake(nil), false); err == nil {
 		t.Fatal("outside a multiplexer accepted")
 	}
 }
+
+func TestTmuxKeyBindings(t *testing.T) {
+	f := newFake(map[string]string{"TMUX": "x"}, "tmux")
+	var hint string
+	if err := Open(Tmux, panes("a"), Options{SyncKey: "S", SoloKey: "e", LayoutDir: "/tmp/l", Hint: func(s string) { hint = s }}, f); err != nil {
+		t.Fatal(err)
+	}
+	conf := f.files["/tmp/l/netssh-multi.tmux.conf"]
+	for _, want := range []string{"bind-key -T prefix S if-shell -F '#{@netssh}'", "bind-key -T prefix e if-shell", "set-option -p synchronize-panes off"} {
+		if !strings.Contains(conf, want) {
+			t.Errorf("conf lacks %q:\n%s", want, conf)
+		}
+	}
+	if hint != "keys: C-b S broadcast to all panes, C-b e exclude/include this pane" {
+		t.Errorf("hint %q", hint)
+	}
+
+	// A key bound in the user's tmux.conf is left alone; netssh's own is replaced.
+	f = newFake(map[string]string{"TMUX": "x"}, "tmux")
+	f.keys = map[string]string{"S": "bind-key -T prefix S kill-server", "e": "bind-key -T prefix e if-shell -F #{@netssh} …"}
+	if err := Open(Tmux, panes("a"), Options{SyncKey: "S", SoloKey: "e", LayoutDir: "/tmp/l", Hint: func(s string) { hint = s }}, f); err != nil {
+		t.Fatal(err)
+	}
+	conf = f.files["/tmp/l/netssh-multi.tmux.conf"]
+	if strings.Contains(conf, "prefix S ") || !strings.Contains(conf, "prefix e ") {
+		t.Errorf("user binding overwritten or own binding not refreshed:\n%s", conf)
+	}
+	if !strings.Contains(hint, "C-b S kept your own binding") {
+		t.Errorf("hint %q", hint)
+	}
+
+	// No keys configured: nothing is bound.
+	f = newFake(map[string]string{"TMUX": "x"}, "tmux")
+	if err := Open(Tmux, panes("a"), Options{LayoutDir: "/tmp/l"}, f); err != nil {
+		t.Fatal(err)
+	}
+	if len(f.files) != 0 || strings.Contains(strings.Join(f.calls, "\n"), "source-file") {
+		t.Errorf("bound keys although disabled: %v", f.calls)
+	}
+}
+
+func TestToggleSyncPane(t *testing.T) {
+	f := newFake(map[string]string{"TMUX": "x"})
+	if state, err := ToggleSync(f, true); err != nil || state != "pane excluded from broadcast" {
+		t.Fatalf("%q %v", state, err)
+	}
+	if got := strings.Join(f.calls[1:], "; "); got != "tmux set-option -p synchronize-panes off; tmux set-option -p @netssh_solo 1" {
+		t.Fatalf("exclude: %s", got)
+	}
+	f = newFake(map[string]string{"TMUX": "x"})
+	f.solo = "1"
+	if state, _ := ToggleSync(f, true); state != "pane included in broadcast" || f.calls[1] != "tmux set-option -pu synchronize-panes" {
+		t.Fatalf("include: %q %v", state, f.calls)
+	}
+	if _, err := ToggleSync(newFake(map[string]string{"ZELLIJ": "0"}), true); err == nil || !strings.Contains(err.Error(), "whole tab") {
+		t.Fatalf("zellij: %v", err)
+	}
+}

internal/multiplex/tmux.go

@@ -1,6 +1,8 @@
 package multiplex
 
 import (
+	"fmt"
+	"path/filepath"
 	"strconv"
 	"strings"
 )
@@ -70,8 +72,9 @@ func openTmux(panes []Pane, opts Options, r Runner) error {
 			_, _ = r.Output("tmux", "set-option", "-p", "-t", id, "@netssh_host", group[j].Title)
 		}
 		windowOptions := [][]string{
+			{"@netssh", "1"}, // the key bindings act only in these windows
 			{"pane-border-status", "top"},
-			{"pane-border-format", " #{@netssh_host}#{?pane_synchronized, [SYNC],} "},
+			{"pane-border-format", " #{@netssh_host}#{?pane_synchronized, [SYNC],#{?@netssh_solo, [SOLO],}} "},
 		}
 		if opts.Sync {
 			windowOptions = append(windowOptions, []string{"synchronize-panes", "on"})
@@ -82,14 +85,103 @@ func openTmux(panes []Pane, opts Options, r Runner) error {
 			}
 		}
 	}
+	keys, err := bindKeys(r, opts)
+	if err != nil {
+		return err
+	}
+	if keys != "" {
+		opts.Hint(keys)
+	}
 	if inside {
 		_, err := r.Output("tmux", "select-window", "-t", first)
 		return err
 	}
-	opts.Hint("toggle broadcast with: netssh sync (or Ctrl+b :setw synchronize-panes)")
 	return r.Exec("tmux", "attach-session", "-t", session)
 }
 
+// soloToggle excludes the current pane from broadcast (a pane-level
+// synchronize-panes off) or includes it again by removing that override.
+func soloToggle(solo bool) [][]string {
+	if solo {
+		return [][]string{
+			{"tmux", "set-option", "-pu", "synchronize-panes"},
+			{"tmux", "set-option", "-pu", "@netssh_solo"},
+		}
+	}
+	return [][]string{
+		{"tmux", "set-option", "-p", "synchronize-panes", "off"},
+		{"tmux", "set-option", "-p", "@netssh_solo", "1"},
+	}
+}
+
+// keyBindings toggle broadcast in netssh multi windows; elsewhere they only
+// show a message, so they do not change what the keys mean to other windows.
+const syncBinding = `bind-key -T prefix %s if-shell -F '#{@netssh}' {
+  set-window-option synchronize-panes
+  display-message 'netssh: broadcast #{?synchronize-panes,on,off}'
+} {
+  display-message 'netssh: not a netssh multi window'
+}
+`
+
+const soloBinding = `bind-key -T prefix %s if-shell -F '#{@netssh}' {
+  if-shell -F '#{@netssh_solo}' {
+    set-option -pu synchronize-panes
+    set-option -pu @netssh_solo
+    display-message 'netssh: pane included in broadcast'
+  } {
+    set-option -p synchronize-panes off
+    set-option -p @netssh_solo 1
+    display-message 'netssh: pane excluded from broadcast'
+  }
+} {
+  display-message 'netssh: not a netssh multi window'
+}
+`
+
+// bindKeys installs the broadcast keys in the tmux server unless the user's
+// own configuration already uses them, and returns a hint naming the keys.
+func bindKeys(r Runner, opts Options) (string, error) {
+	prefix, err := r.Output("tmux", "show-options", "-gv", "prefix")
+	if err != nil || prefix == "" {
+		prefix = "C-b"
+	}
+	var conf strings.Builder
+	var hints, taken []string
+	for _, key := range []struct{ key, binding, what string }{
+		{opts.SyncKey, syncBinding, "broadcast to all panes"},
+		{opts.SoloKey, soloBinding, "exclude/include this pane"},
+	} {
+		if key.key == "" {
+			continue
+		}
+		// An existing binding is replaced only if netssh made it.
+		if existing, _ := r.Output("tmux", "list-keys", "-T", "prefix", key.key); existing != "" && !strings.Contains(existing, "@netssh") {
+			taken = append(taken, prefix+" "+key.key)
+			continue
+		}
+		fmt.Fprintf(&conf, key.binding, key.key)
+		hints = append(hints, prefix+" "+key.key+" "+key.what)
+	}
+	if conf.Len() > 0 {
+		path := filepath.Join(opts.LayoutDir, "netssh-multi.tmux.conf")
+		if err := r.WriteFile(path, []byte(conf.String())); err != nil {
+			return "", err
+		}
+		if _, err := r.Output("tmux", "source-file", path); err != nil {
+			return "", err
+		}
+	}
+	hint := "keys: " + strings.Join(hints, ", ")
+	if len(hints) == 0 {
+		hint = "toggle broadcast with: netssh sync, netssh sync --pane"
+	}
+	if len(taken) > 0 {
+		hint += "; " + strings.Join(taken, " and ") + " kept your own binding (use netssh sync)"
+	}
+	return hint, nil
+}
+
 // freeSession returns name, or name-2, name-3, … if a session already uses it.
 func freeSession(r Runner, name string) string {
 	candidate := name