gmux

Routing terminal multiplexer that owns its window, uses libghostty-vt for inner-terminal state, and renders through its own ghostty-native backend (vendored in-repo at crates/ratatui-ghostty). Chrome (tab bar, status) is authored with ratatui.

Status: pre-alpha. Multiple shells in top-row tabs, each a libghostty-vt Terminal fed by its own PTY, rendered via the owned GhosttyBackend. Pending: session persistence / host-client split, and passthrough fidelity (kitty graphics, OSC 52 clipboard, palette/theme, OSC 133). Work is tracked in this repo's own bd database under epic gmux-io8.

Why this exists

This is the Path A pivot from a planned tmux-CC ↔ ghostty bridge. See docs/research/ghostty-tmux-cc-bridge/synthesis.md.

The headline finding: bridging tmux -CC into ghostty's native tabs is blocked by tmux #4302, ghostty #1935, and ghostty #12136. Owning the window and embedding libghostty-vt is the cleaner path.

Build & run

Requires Zig 0.15.2 (pinned via .mise.toml — installed automatically if you use mise).

mise install            # picks up zig 0.15.2 from .mise.toml
cargo build --release   # builds libghostty-vt-sys (vendors ghostty + zig build)
cargo run --release     # launches gmux (must run inside an outer terminal)

The resulting binary is self-contained (~7.5 MB stripped): libghostty-vt is statically linked, so there is no libghostty-vt.so to ship, no rpath, and no LD_LIBRARY_PATH wrapper. This relies on a local fork of libghostty-vt-sys at ../libghostty-vt-sys (wired via [patch.crates-io]) that emits a static archive and merges in the zig-built C++ deps + libc++/libc++abi. ldd on the output shows only glibc + libgcc_s. See gmux-io8.20 for the upstream PR to drop the fork.

Controls

• Type into the active shell — keystrokes flow through (kitty keyboard).
• Mouse, bracketed paste, and focus events are forwarded to the active pane.
• Scroll wheel scrolls the inner terminal's scrollback (1000-line default).
• Ctrl-T new tab · Ctrl-W close tab · Ctrl-PgUp/PgDn cycle · Ctrl-1..9 jump to tab · Ctrl-Q exit gmux.

Architecture

gmux (host process)
├── crates/ratatui-ghostty — owned GhosttyBackend (ghostty-native output +
│     EventStream input: kitty keyboard, OSC 8/52/133, undercurl, sync output)
├── libghostty-vt — one Terminal per pane, parses inner PTY output into cells
├── portable-pty — forks the shell, plumbs the PTY master fd
└── ratatui frame — top-row tab bar + active pane blitted into the body

crates/ratatui-ghostty was absorbed from a former standalone repo so gmux owns its renderer outright; the next step is to generalize it past ghostty-only (capability negotiation) — see gmux-io8.2.

Known limitations

• Kitty graphics: renderer is text-cells only (gmux-io8.13).
• Premium passthrough not wired yet: inner OSC 52 clipboard, palette/theme changes, and OSC 133 semantic prompts are currently dropped rather than forwarded to the outer terminal (gmux-io8.10 / .11 / .12).
• libghostty-vt stderr noise: redirected to /tmp/gmux.log at startup.
• Working name: gmux is provisional.

License

Dual-licensed under MIT or Apache-2.0.