mmux

A terminal workspace with batteries included.

mmux is a modern terminal multiplexer built in Rust. It provides session management, multiple panes with flexible layouts, Starlark scripting, and optional multi-server SSH support.

Quick Start

# Install
cargo install mmux

# Start a new session
mmux new

# Or attach to existing/create new
mmux

Features

Core

• Multiple panes with PTY-backed terminal emulation
• 5 layout modes: single, vertical stack, horizontal stack, grid, zoom
• Session management with attach/detach
• Daemon mode for persistent sessions
• Mouse support (click, drag, scroll)

Keyboard Navigation

• Ctrl+N enters command mode:
  • c - new pane
  • s - SSH prompt
  • x - kill pane
  • h/l or 0-9 - switch panes
• Alt+, / Alt+. - previous/next pane
• Alt+/ - command palette with fuzzy search
• Ctrl+N w - pane selector overlay

Configuration

• YAML configuration at ~/.mmux/config.yaml
• Starlark scripting for advanced customization
• Hot-reload on config changes
• Customizable keybindings and themes

Optional Features

• recording - TTYrec capture (default)
• scripting - Starlark runtime (default)
• ssh - SSH pane integration
• remote - Multi-server orchestration

Configuration

# ~/.mmux/config.yaml
schema_version: 1
shell: "/bin/zsh"
shell_args: ["-l"]
env:
  TERM: "xterm-256color"
startup_panes:
  - "htop"
status_bar:
  show_pane_list: true
  show_mode: true
layout:
  default_mode: "vstack"
idle:
  timeout: "30m"
  privacy_style: "matrix"  # matrix, clock, or train

When shell is omitted, mmux falls back to $MMUX_SHELL, $SHELL, or /bin/sh.

CLI Commands

# Session management
mmux new -n "work"        # Create named session
mmux list                 # List sessions
mmux attach -s 1           # Attach to session (by ID)
mmux kill -s 1             # Kill session

# Pane operations
mmux list-panes -s 1     # List panes in session
mmux exec -s 1 -i 0 ls   # Execute in pane
mmux capture-pane -s 1 -p 0 # Capture pane contents

# Daemon
mmux daemon               # Start daemon
mmux ping                 # Check connectivity

Environment Variables

Variable	Description
MMUX_SHELL	Override default shell
MMUX_SESSION_NAME	Session identifier
MMUX_DEFAULT_BEHAVIOR	Default action: attach, reattach, reuse, or new
MMUX_AUTO_START	Auto-start daemon (1/0)
MMUX	Set by mmux: <socket>,<pid>,<session>
MMUX_PANE	Current pane ID (e.g., %0)

Building

# Default (recording + scripting)
cargo build --release

# Minimal build
cargo build --release --no-default-features

# With SSH support
cargo build --release --features ssh

# Full remote support
cargo build --release --features remote

Architecture

mmux uses a daemon/client architecture with Unix socket IPC. Each pane runs in its own PTY with VT100 terminal emulation.

mmux/
├── src/                    # Main binary
├── crates/
│   ├── mmux-core/         # Window manager logic
│   ├── mmux-protocol/     # IPC protocol
│   ├── mmux-tui/          # TUI widgets
│   ├── mmux-state/        # State management
│   ├── mmux-ssh/          # SSH integration
│   ├── mmux-channel/      # Channel multiplexing
│   ├── mmux-spore/        # Session orchestration
│   └── mmux-orchestrator/ # Multi-agent coordination

Documentation

• Getting Started
• User Guide
• Configuration Reference
• CLI Reference
• Architecture
• Development
• Contributing

License

MIT