Installation

Precompiled packages published on GitHub Releases:

Target Package Dependencies
macOS Apple Silicon muxterm-macos-arm64.dmg macOS 13+
Linux x86_64 muxterm-gtk-linux-x86_64.tar.gz GTK4, vte4, OpenSSL, tmux 3.x

Quickstart

Launch the GUI with muxterm gui or the terminal UI with muxterm tui. Press Alt+P on Linux or Cmd+P on macOS to open QuickConnect.

Existing tmux sessions, Herdr workspaces, projects and worktrees appear as workspace candidates. Switching between open workspaces carries no core lock delay.

A workbench of workspaces

tmux and Herdr are not wrapped in a fake terminal. Each tmux session or Herdr workspace enters the pool as a first-class workspace:

Workspace = Runtime(Transport) + path
  Runtime:   shell / tmux / herdr
  Transport: local / ssh
  Structure: Tab to Pane

Control lane: topology and native scenes
Render lane: raw PTY bytes to native surfaces
Activity lane: agents, commands and attention

Ports and forwarding

For SSH workspaces, Muxterm scans TCP listening ports on the remote host through the existing SSH connection. The macOS status bar lists detected ports and lets you:

  • forward a remote port to a local port;
  • enable explicit LAN access for a forwarded port;
  • open the local or remote address, ignore a port, or stop forwarding.

Scanning uses ss or lsof on the target and runs away from the frontend thread. The Core APIs are exposed through FFI; the current port picker UI is in the macOS frontend.

Configuration contract

Stored at ~/.config/muxterm/config.toml with strict schema validation:

config_version = 1

[font]
family = "JetBrains Mono"
size = 13.0

[statusbar]
mode = "tmux"

[pool]
max_slots = 20

[theme]
name = "system"
light = "white"
dark = "black"

[shortcuts]
preset = "qwerty"
primary_key = "auto" # Alt on Linux, Command on macOS

[[projects]]
id = "muxterm@local"
name = "Muxterm"
path = "~/Developer/self/muxterm"

CLI reference

The thin binary works without launching a GUI:

# List open workspaces
muxterm list-workspaces

# Isolated tmux socket
muxterm -L muxterm-test list-workspaces

# Send keys to the active pane
muxterm send-keys "cargo test"

# Inspect configuration
muxterm config show --resolved
muxterm config doctor

Building from source

Build scripts output into ./build/<os>/:

git clone https://github.com/wlingze/muxterm.git
cd muxterm
./scripts/build-tui.sh --release
./scripts/build-linux.sh --release
./scripts/build-macos.sh --release