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