---

name: multiplexing description: Native windows/splits/panes (absorb tmux). Load when touching multiplex module, keybinds, or session persistence. triggers:

• tmux
• multiplex
• split
• pane
• "copy mode"
• session
• "Ctrl+Space"
• workspace

---

Multiplexing

Goal: absorb tmux into the core. Users on this stack today run Ghostty → tmux → shell. We collapse that to nyxterm → shell.

Keybind defaults

• Prefix: Ctrl+Space. Configurable. (Matches the user's tmux config.)
• Splits: prefix | = vertical, prefix - = horizontal. (Match tmux convention.)
• Pane nav: Ctrl+Shift+h/j/k/l (no prefix needed, like vim-tmux-navigator).
• Pane resize: prefix H/J/K/L.
• Zoom pane: prefix z.
• New window: prefix c.
• Window nav: prefix 0..9, prefix n/p.
• Session picker: prefix s.
• Kill pane: prefix x (with confirm).
• Detach: prefix d.
• Copy mode: prefix [. Vi keys. v = visual, y = yank to system clipboard (via wl-copy or platform equivalent).

Critical: NO keybinds may shadow xterm escape sequences (e.g., Ctrl+M is Enter, can't be rebound). Validate at config-load.

Session persistence

• Autosave layout (tree of panes + cwd per pane + scrollback head per pane) every 60 s.
• Save on graceful shutdown.
• Persistence backend: Engram (preferred), local SQLite fallback.
• Don't persist: secrets in scrollback, pty fds, in-flight AI requests.

Reference: tmux-resurrect + tmux-continuum behavior, reimplemented natively.

Pane grid model

Window
└── PaneTree (binary tree)
    ├── Split (vertical | horizontal, ratio: f32)
    │   ├── PaneTree (left/top)
    │   └── PaneTree (right/bottom)
    └── Leaf (Pane)
        ├── PtySession id
        ├── cwd
        ├── title
        └── ...

Leaf panes can be:

• PTY (default, terminal)
• Webview (Phase 3)
• mpv (Phase 3)

The grid logic is content-type agnostic. Only the leaf knows what it is.

Vi copy-mode

State machine:

• prefix [ enters copy mode → buffer cursor at last line.
• Vi motion: h/j/k/l, w/b/e, 0/$, gg/G, /? search.
• v = char-visual, V = line-visual, Ctrl+v = block-visual.
• y = yank to system clipboard (wl-clipboard on Wayland, xclip on X11, OSC 52 fallback).
• q or Esc = exit copy mode.

Tab title and statusline

• Tab title = window name OR auto-renamed from active pane's cwd (basename).
• Statusline (per window): branch (cached, see git-status epic), pane index, active count.
• Sessions list: shown in prefix s picker (fuzzy-filterable).

Persistence-on-Engram topic keys

• nyxterm/session/<session-id>/layout — pane tree snapshot
• nyxterm/session/<session-id>/cwd-map — pane → cwd
• nyxterm/session/<session-id>/last-active — timestamp

Sessions are user-named (prefix S to rename) and survive restarts.

What we DON'T copy from tmux

• The control mode / tmux-cli external scripting → use the Tauri command surface directly.
• Plugin manager (TPM) → plugins live in nyxterm's plugin API (epic #21), not tmux.
• Status-bar plugin ecosystem → native modules instead.