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/config/multi.go

@@ -2,6 +2,7 @@ package config
 
 import (
 	"fmt"
+	"regexp"
 	"sort"
 	"strings"
 )
@@ -12,8 +13,34 @@ type MultiConfig struct {
 	Multiplexer string `mapstructure:"multiplexer"`
 	// PanesPerWindow splits larger host lists into more windows or tabs; 0 = 9.
 	PanesPerWindow int `mapstructure:"panes_per_window"`
+	// SyncKey and SoloKey are tmux prefix keys for broadcast to all panes and
+	// for excluding the current pane; empty = default (S, e), "none" = off.
+	SyncKey string `mapstructure:"sync_key"`
+	SoloKey string `mapstructure:"solo_key"`
 }
 
+// Default tmux keys: unbound in a stock tmux (E would be "spread evenly").
+const (
+	DefaultSyncKey = "S"
+	DefaultSoloKey = "e"
+)
+
+// Keys returns the tmux keys to bind; "" for a disabled one.
+func (m MultiConfig) Keys() (sync, solo string) {
+	pick := func(key, fallback string) string {
+		switch key {
+		case "":
+			return fallback
+		case "none":
+			return ""
+		}
+		return key
+	}
+	return pick(m.SyncKey, DefaultSyncKey), pick(m.SoloKey, DefaultSoloKey)
+}
+
+var tmuxKey = regexp.MustCompile(`^([CMS]-)*([A-Za-z0-9]|F[0-9]{1,2}|[-_=+!@#$%^&*,./?<>\[\]]|Tab|Space|Enter|BSpace|Up|Down|Left|Right|Home|End|PPage|NPage)$`)
+
 // DefaultPanesPerWindow keeps panes readable on a normal screen (3×3).
 const DefaultPanesPerWindow = 9
 
@@ -27,6 +54,14 @@ func (c *Config) ValidateMulti() error {
 	if c.Multi.PanesPerWindow < 0 || c.Multi.PanesPerWindow > 64 {
 		return fmt.Errorf("multi.panes_per_window must be between 1 and 64")
 	}
+	for name, key := range map[string]string{"sync_key": c.Multi.SyncKey, "solo_key": c.Multi.SoloKey} {
+		if key != "" && key != "none" && !tmuxKey.MatchString(key) {
+			return fmt.Errorf("multi.%s %q is not a tmux key (e.g. S, e, C-s, F5) or none", name, key)
+		}
+	}
+	if sync, solo := c.Multi.Keys(); sync != "" && sync == solo {
+		return fmt.Errorf("multi.sync_key and multi.solo_key must differ")
+	}
 	names := make([]string, 0, len(c.Groups))
 	for name := range c.Groups {
 		names = append(names, name)

internal/config/ssh_test.go

@@ -196,7 +196,15 @@ func TestMultiConfig(t *testing.T) {
 	if err != nil || len(cfg.Groups["k8s"]) != 2 || cfg.Multi.Multiplexer != "zellij" || cfg.Multi.PanesPerWindowOrDefault() != 9 {
 		t.Fatalf("%+v %v", cfg, err)
 	}
-	for _, bad := range []string{"multi: {multiplexer: screen}", "multi: {panes_per_window: 100}", "groups: {web: []}", "groups: {web: [\"a b\"]}"} {
+	if sync, solo := cfg.Multi.Keys(); sync != "S" || solo != "e" {
+		t.Fatalf("default keys %q %q", sync, solo)
+	}
+	custom, err := loadYAML(t, "multi: {sync_key: C-s, solo_key: none}\n")
+	if sync, solo := custom.Multi.Keys(); err != nil || sync != "C-s" || solo != "" {
+		t.Fatalf("custom keys %q %q %v", sync, solo, err)
+	}
+	for _, bad := range []string{"multi: {multiplexer: screen}", "multi: {panes_per_window: 100}", "groups: {web: []}", "groups: {web: [\"a b\"]}",
+		"multi: {sync_key: \"x y\"}", "multi: {sync_key: \"{\"}", "multi: {sync_key: e}"} {
 		if _, err := loadYAML(t, bad+"\n"); err == nil {
 			t.Errorf("%s accepted", bad)
 		}

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

internal/setup/multi.go

@@ -22,6 +22,18 @@ func editMulti(cfg *config.Config) error {
 		perWindow = strconv.Itoa(cfg.Multi.PanesPerWindow)
 	}
 	groups := formatGroups(cfg.Groups)
+	syncKey, soloKey := cfg.Multi.SyncKey, cfg.Multi.SoloKey
+	validKey := func(field string) func(string) error {
+		return func(s string) error {
+			candidate := config.Config{Multi: cfg.Multi}
+			if field == "sync" {
+				candidate.Multi.SyncKey = strings.TrimSpace(s)
+			} else {
+				candidate.Multi.SoloKey = strings.TrimSpace(s)
+			}
+			return candidate.ValidateMulti()
+		}
+	}
 	err := huh.NewForm(huh.NewGroup(
 		huh.NewSelect[string]().
 			Title("Multiplexer").
@@ -41,6 +53,18 @@ func editMulti(cfg *config.Config) error {
 				}
 				return nil
 			}),
+		huh.NewInput().
+			Title("tmux key: broadcast to all panes").
+			Description(fmt.Sprintf("Pressed after the tmux prefix. Empty = %s, none = no key.", config.DefaultSyncKey)).
+			Placeholder(config.DefaultSyncKey).
+			Value(&syncKey).
+			Validate(validKey("sync")),
+		huh.NewInput().
+			Title("tmux key: exclude/include this pane").
+			Description(fmt.Sprintf("Pressed after the tmux prefix. Empty = %s, none = no key.", config.DefaultSoloKey)).
+			Placeholder(config.DefaultSoloKey).
+			Value(&soloKey).
+			Validate(validKey("solo")),
 		huh.NewText().
 			Title("Groups").
 			Description("One per line: NAME: host, tag:TAG, cluster:NAME, @other — open with netssh multi @NAME.").
@@ -59,6 +83,8 @@ func editMulti(cfg *config.Config) error {
 		cfg.Multi.Multiplexer = ""
 	}
 	cfg.Multi.PanesPerWindow, _ = strconv.Atoi(strings.TrimSpace(perWindow))
+	cfg.Multi.SyncKey = strings.TrimSpace(syncKey)
+	cfg.Multi.SoloKey = strings.TrimSpace(soloKey)
 	cfg.Groups, _ = parseGroups(groups)
 	return nil
 }

internal/setup/wizard.go

@@ -482,7 +482,7 @@ func save(cfg config.Config) error {
 			fmt.Fprintf(&b, "  %s: [%s]\n", name, strings.Join(quoted, ", "))
 		}
 	}
-	if cfg.Multi.Multiplexer != "" || cfg.Multi.PanesPerWindow > 0 {
+	if cfg.Multi != (config.MultiConfig{}) {
 		b.WriteString("\nmulti:\n")
 		if cfg.Multi.Multiplexer != "" {
 			fmt.Fprintf(&b, "  multiplexer: %s\n", cfg.Multi.Multiplexer)
@@ -490,6 +490,11 @@ func save(cfg config.Config) error {
 		if cfg.Multi.PanesPerWindow > 0 {
 			fmt.Fprintf(&b, "  panes_per_window: %d\n", cfg.Multi.PanesPerWindow)
 		}
+		for _, key := range [][2]string{{"sync_key", cfg.Multi.SyncKey}, {"solo_key", cfg.Multi.SoloKey}} {
+			if key[1] != "" {
+				fmt.Fprintf(&b, "  %s: %q\n", key[0], key[1])
+			}
+		}
 	}
 
 	if cfg.Completion.MaxResults > 0 {