openmux

A terminal multiplexer with master-stack layout (Zellij-style), built with:

• Bun - Fast JavaScript runtime
• OpenTUI - Terminal UI library with SolidJS reconciler
• SolidJS - Reactive UI framework
• zig-pty - PTY support for Bun (pure Zig implementation)
• libghostty-vt - Native terminal emulation (VT parser/state)

Features

• Master-stack tiling layout (like Zellij)
• i3-gaps style gaps and borders
• Vim-style hjkl navigation
• Tmux-style Ctrl+b prefix key
• 9 workspaces with isolated pane layouts
• Session persistence and management
• Detach/attach (leave sessions running in background)
• Pane zoom (fullscreen focused pane)
• Aggregate view for browsing/filtering PTYs across workspaces
• Mouse tracking (click to focus, tabbed pane switching)
• Scrollback support with mouse wheel and scrollbar
• Kitty graphics protocol support (image rendering, pixel sizing, SSH-aware offloading)

Installation

⚠️ Important Update Note for v0.3.0 Users

openmux v0.3.0 contains a quirky bug that prevents openmux update from working correctly. If you're on v0.3.0, please update manually using one of the following methods:

# Option 1: Reinstall via install script
curl -fsSL https://raw.githubusercontent.com/monotykamary/openmux/main/scripts/install.sh | bash

# Option 2: Update via package manager
bun update -g openmux
# or
npm update -g openmux

Quick Install (curl)

curl -fsSL https://raw.githubusercontent.com/monotykamary/openmux/main/scripts/install.sh | bash

npm / bun

npm install -g openmux
# or
bun add -g openmux

From Source

git clone https://github.com/monotykamary/openmux.git
cd openmux
bun install
bun run build --install

GitHub Releases

Download prebuilt binaries from GitHub Releases.

Available platforms:

• macOS (Apple Silicon)
• Linux (x64 / arm64)

Usage

openmux

For development:

bun start      # Run from source
bun dev        # Run with watch mode

CLI

openmux ships a headless-style CLI that talks to the running UI for pane/layout operations and uses on-disk session metadata for session listing/creation.

openmux --help
openmux pane --help
openmux pane capture --help

Examples:

openmux session list --json
openmux session create dev
openmux attach --session dev
openmux update
openmux update --yes
openmux pane split --direction vertical --workspace 2
openmux pane send --pane focused --text "npm test\n"
openmux pane capture --pane focused --lines 200 --format ansi

Notes:

• Pane commands require a running UI (control socket available).
• pane send supports C-style escapes like \n, \t, \xNN, \uXXXX.
• See docs/guides/cli.md for the full spec and exit codes.

Architecture (High Level)

┌─────────────────────────┐
│  Host Terminal (TTY)    │
└────────────┬────────────┘
             │ input/output
             v
┌─────────────────────────┐
│ openmux UI (client)     │  Solid + OpenTUI
└────────────┬────────────┘
             │ shim protocol (detach/attach)
             v
┌─────────────────────────┐
│ shim server (background)│
└────────────┬────────────┘
             │ PTY I/O + emulation
             v
┌─────────────────────────┐
│ zig-pty + libghostty-vt │
└─────────────────────────┘

Keyboard Shortcuts

Normal Mode (Alt shortcuts - no prefix needed)

• Alt+h/j/k/l - Navigate panes
• Alt+m - Enter move mode
• Alt+n - New pane
• Alt+s - Open session picker
• Alt+t - Open template overlay
• Alt+g - Open aggregate view (browse all PTYs)
• Alt+f - Open search
• Alt+p - Open command palette
• Alt+[ / Alt+] - Cycle layout mode (vertical → horizontal → stacked)
• Alt+z - Toggle zoom (fullscreen focused pane)
• Alt+x - Close pane
• Alt+- - Split pane horizontally
• Alt+\ - Split pane vertically
• Alt+1-9 - Switch to workspace 1-9

Mouse

• Click - Focus pane
• Click tab - Switch to stacked pane (in stacked mode)
• Scroll wheel - Scroll through terminal history (when not in alternate screen apps like vim)
• Click scrollbar - Jump to position in scrollback
• Drag scrollbar - Scroll through history by dragging

Prefix Mode (Ctrl+b, 2s timeout)

• 1-9 - Switch to workspace 1-9
• n or Enter - New pane
• h/j/k/l - Navigate panes
• m - Enter move mode
• \ - Split pane vertically
• - - Split pane horizontally
• v - Set layout mode: vertical
• H - Set layout mode: horizontal
• t - Set layout mode: stacked (tabbed)
• T - Open template overlay
• x - Close pane
• z - Toggle zoom
• s - Open session picker
• g - Open aggregate view (browse all PTYs)
• / - Open search
• : - Open command palette
• ] or p - Paste from clipboard
• ` - Toggle console overlay
• q - Quit openmux
• d - Detach (leave session running in background)
• Esc - Exit prefix mode

Move Mode

• h/j/k/l - Move focused pane west/south/north/east
• Esc - Exit move mode

Search Mode

• Ctrl+n - Next match
• Ctrl+p - Previous match
• Enter - Confirm selection and jump
• Esc - Cancel search
• Backspace - Delete last character

Command Palette

• ↑ / ↓ - Navigate commands
• Enter - Execute selected command
• Esc - Close command palette
• Backspace - Delete last character

Template Overlay

Apply Tab:

• ↑ / ↓ - Navigate templates
• Enter - Apply selected template
• Tab - Switch to save tab
• Ctrl+x / Ctrl+d - Delete template
• Esc - Close overlay

Save Tab:

• Enter - Save current layout as template
• Tab - Switch to apply tab
• Backspace - Delete last character
• Esc - Close overlay

Aggregate View

List:

• ↑ / ↓ - Navigate PTYs
• Enter - Preview selected PTY
• Tab - Jump to selected PTY and close view
• Alt+a - Toggle scope (all workspaces vs current)
• Alt+x - Kill selected PTY
• Backspace - Delete last filter character
• Alt+Esc - Close aggregate view

Preview:

• Alt+Esc - Return to list
• Alt+f - Open search in preview
• Alt+x - Kill current PTY
• Full keyboard/mouse support for terminal interaction

Search (in preview):

• Ctrl+n - Next match
• Ctrl+p - Previous match
• Enter - Jump to match
• Esc - Exit search
• Backspace - Delete last character

Prefix (in preview):

• q - Quit openmux
• d - Detach
• Esc - Return to list
• / - Open search

Session Picker

List Tab:

• ↑ / ↓ - Navigate sessions
• Enter - Select or create session
• Ctrl+n - Create new session
• Ctrl+r - Rename session
• Ctrl+x / Ctrl+d - Delete session
• Backspace - Delete last filter character
• Esc - Close picker

Rename Tab:

• Enter - Confirm new name
• Esc - Cancel rename
• Backspace - Delete last character

Confirmation Dialog

• h / ← or l / → - Focus confirm/cancel
• Tab - Toggle between confirm/cancel
• Enter - Confirm
• Esc - Cancel

Vim Mode (Overlays, opt-in)

Enable via the command palette ("Toggle overlay vim mode"), or in config.toml:

[keyboard]
vimMode = "overlays"
vimSequenceTimeoutMs = 1000

When enabled, overlays open in normal mode:

• j/k - Navigate lists
• gg / G - Jump to first/last item
• Enter - Confirm/preview
• q - Close overlay
• i - Enter insert mode
• Esc - Return to normal mode
• Search overlays: n / N for next/prev match

Concepts

Why openmux (vs tmux / zellij)

• Single-client steal/lock: predictable attach semantics; new client wins and old client detaches.
• UI binary swap: update the UI without touching running PTYs (shim stays alive).
• UI-first architecture: SolidJS/OpenTUI enables richer overlays and layout evolution.
• PTY state snapshots: fast attach with immediate state restore (no full redraw pipeline).
• Emulator ownership: aggregate previews, scrollback caching, and search are first-class.
• Lower client CPU: shim does emulation; client focuses on rendering updates.

Workspaces

Like i3/sway, openmux supports multiple workspaces (1-9). Each workspace has its own layout tree of panes. The status bar shows populated workspaces dynamically - empty workspaces don't appear unless active.

Layout Modes (Zellij-style)

Each workspace has a layout mode that determines how panes are arranged:

• Vertical (│): Main pane on left, stack panes split vertically on right
• Horizontal (─): Main pane on top, stack panes split horizontally on bottom
• Stacked (▣): Main pane on left, stack panes tabbed on right (only active visible)

Sessions

Sessions persist your workspace layouts and pane working directories. Sessions are auto-saved to ~/.config/openmux/sessions/ and can be switched via the session picker (Alt+s or Ctrl+b then s).

Configuration

openmux loads ~/.config/openmux/config.toml (or $XDG_CONFIG_HOME/openmux/config.toml). If the file is missing, a full default config is generated on startup. Deleting the file and restarting openmux will regenerate it.

Config changes are hot-reloaded while openmux is running (layout, theme, and keybindings update live).

See docs/guides/config.md for the full generated config.

Environment variables override the config file for layout values:

• OPENMUX_WINDOW_GAP
• OPENMUX_MIN_PANE_WIDTH
• OPENMUX_MIN_PANE_HEIGHT
• OPENMUX_STACK_RATIO (maps to layout.defaultSplitRatio)

To unbind a keybinding, set its value to null or "unbind".

Detach / Attach

Use Ctrl+b d to detach and leave the background shim running. Reattach by launching openmux again. Detach/attach uses a single-client lock; a new client steals the lock and the previous client detaches.

Aggregate View

A fullscreen overlay (Alt+g or Ctrl+b then g) that lets you browse all PTYs across all workspaces in one place. Features:

• Card-style PTY list showing directory, process name, and git branch
• Interactive terminal preview with full input support (keyboard + mouse)
• Filter by typing to search by process name, directory, or git branch
• Navigate with arrow keys (or j/k in overlay vim mode), Enter to interact, Prefix+Esc to return to list

Development Status

Current status:

• Master-stack layout with gaps
• OpenTUI component layer
• Keyboard navigation system
• PTY integration
• libghostty-vt native terminal emulation
• Workspaces (1-9)
• Layout modes (vertical/horizontal/stacked)
• Session persistence
• Pane zoom
• Mouse support
• Scrollback support
• Aggregate view (PTY browser)
• Attach/detach (steal + lock)
• Configurable keybindings
• Configurable settings and colors
• Kitty graphics protocol support

License

MIT