A modern multiplexer alternative.

ttmux runs many terminals in one window, like tmux or screen. It adds floating panes, real mouse support, curved borders, and a settings screen that you open inside the app.

With Homebrew, on macOS or Linux:

brew install statico/tap/ttmux

Or build it from source, which needs Rust 1.82 or later:

cargo install --git https://github.com/statico/ttmux

Then start it:

ttmux

Prebuilt binaries for macOS and Linux are also on the releases page.

tmux works well and has decades of muscle memory behind it. But a fresh tmux needs a .tmux.conf and plugins like tmux-sensible before it stops getting in the way. ttmux ships with those defaults.

On first start ttmux asks which keymap you want: Modern, tmux, or screen. Change it later in settings or with general.keys-preset, and rebind any key under [keys].

Press the prefix and ? in the app for the full list.

Hold the prefix and a popup lists what can follow it, like which-key in neovim. Turn it off with general.which-key = false.

The prefix and : open a command line for the scripting commands below. Tab completes a command or a flag, and the row above shows the usage of the command you are typing.

A name you type is yours. A program can set a title with an escape sequence, but that title never replaces a name you set, and it names the pane, not the tab. The tab takes the title only while it holds one pane.

Every text field takes the readline keys, including ctrl+a, ctrl+e, ctrl+w, ctrl+k, ctrl+u, ctrl+y, alt+b, and alt+f. Lists move with ctrl+n and ctrl+p, and ctrl+g cancels.

ctrl+alt+f turns the grid of panes into a window manager. Drag a title bar to move a pane. Drag any corner to resize it. Click to raise it. Tiling mode gets the same mouse support for dividers. Grab the line between two panes and drag it.

ttmux works like tmux. The server keeps your panes alive after you detach.

ttmux                       # attach to the default session, or start it
ttmux new -d -s work        # start a session in the background
ttmux attach -t work        # attach to a named session
ttmux ls                    # list the sessions
ttmux kill-session -t work  # stop one

ctrl+t d detaches. A new binary starts a new server, so an upgrade never kills a running session. Detach, install, then attach again with the old binary until you are ready to move.

Every pane can drive the session it lives in. The commands are tmux's, so a tmux script mostly runs unchanged.

ttmux send-keys -t %2 "make test" Enter   # type into a pane
ttmux split-window -h                     # split side by side, prints %2
ttmux capture-pane -t %2 -S -             # read a pane, scrollback and all
ttmux new-window                          # open a tab, prints its number
ttmux select-pane -t %2                   # or -L -R -U -D
ttmux list-panes                          # %2: [80x24] zsh (active)
ttmux list-windows                        # 1:build (2 panes) (active)
ttmux rename-window build                 # name a window
ttmux display-message "done"              # show text in the status bar
ttmux join-pane -s %3 -t 2                # move a pane into window 2
ttmux break-pane                          # and back out into its own
ttmux run toggle-zoom                     # any key-binding action

A target is a pane id from list-panes, or a window number counted from 1. With no target the command acts on the pane it was run from, or the focused pane outside ttmux. The session is the one $TTMUX_SESSION names, which every pane already has set. ttmux --help prints the full list.

API.md is the full reference: every command, every flag, the exit codes, and recipes. ttmux <command> --help prints one command, and ttmux list-commands --json prints the whole API for an agent to read.

The file is ~/.config/ttmux/ttmux.toml. ttmux writes it for you on the first save. Every key in it is also in the settings screen, so the file is for version control and the screen is for changes.

After you edit the file, press the prefix and r to reload it. ttmux does not reload it on its own, because widget commands in it run as you, and a program that writes the file should not get them run unasked.

[general]
mouse = true
scrollback = 10000
free-mode = false
keys-preset = "vim"          # vim | tmux | screen
passthrough-images = true    # kitty, iTerm2, and sixel inline images
clipboard = true             # programs may copy with OSC 52
notifications = true         # programs may send OSC 9, 99, and 777

[appearance]
border-style = "curved"      # curved | square | heavy | double | dashed | divider | none
border-focused = "#7aa2f7"
gap = 0

[status.footer]
enabled = true
left = ["session", "mode"]
center = ["tabs"]
right = ["agents", "time"]

[agents]
enabled = true
bell-on-attention = true

# Overrides on top of the preset. "none" unbinds a key.
[keys]
"ctrl+t v" = "split right"
"ctrl+t &" = "none"

A widget runs a shell command and shows what it prints. Give it a name under [status.widgets], then put that name in a row.

[status.footer]
enabled = true
right = ["disk", "time"]

[status.widgets.disk]
command = "df -h / | awk 'NR==2 {print $5}'"
interval = 60               # seconds between runs, 0 runs it once

A pane that runs a coding agent gets a mark: ◐ for busy, ● for wants you, and ✓ for done. The status bar counts the panes that wait on you, and ctrl+alt+n goes to the next one. The patterns live under [agents], so this works with any agent.

ttmux is built against Ghostty and iTerm2. Any terminal with 24-bit color and SGR mouse reporting works, including Alacritty, kitty, WezTerm, and Terminal.app.

keybind = alt+left=unbind
keybind = alt+right=unbind

What programs inside a pane can count on:

• Truecolor, and undercurl, dotted, dashed and double underlines in color
• Emoji with skin tones, flags and ZWJ sequences as one wide cell
• Kitty keyboard protocol and modifyOtherKeys, so shift+enter works
• Kitty, iTerm2 and sixel images, including mpv --vo=kitty video
• Synchronized output, so redraws do not tear
• Focus events, and a cursor shape per pane
• OSC 52 copy to your clipboard, and OSC 9, 99 and 777 notifications, each of which can be turned off
• Answers to cursor position, device attributes, window size, mode, color and XTGETTCAP queries, so fzf, neovim and fish do not stall
• Dark or light theme reports (CSI ?996n, mode 2031)
• Scrollback that keeps output scrolled under a fixed footer, as Claude Code and Codex draw, and CSI 3J to clear it
• Pastes that cannot close their own bracket early
• No accidental nesting: attaching from inside a pane is refused, as in tmux

macOS on Apple silicon and Intel, and Linux on x86_64 and aarch64. CI builds and tests all three.

SECURITY.md describes the threat model, the hardening, how ttmux compares with tmux, and how to report a vulnerability.

make check      # format, lint, and test, the same as CI
make help       # all the targets

MIT licensed.