cmux

This repository now uses the VTE backend on Linux and includes the first functional v0 shell.

• cmux-ghostty-gate captures the Ghostty go/no-go decision for Linux.
• cmux is a GTK4 + libadwaita app with a workspace sidebar, per-workspace tabs, recursive split panes, and JSON session persistence.
• Ghostty remains probed and documented, but the Linux delivery backend is currently VTE.

Current Decision

The Linux delivery path pivots to VTE unless Ghostty's public C API exposes a Linux GTK embedding surface and the embed proves stable. The current probe inspects ghostty.h rather than assuming parity with Ghostty's internal GTK app runtime.

Build

cmux currently targets Linux. You need CMake 3.25 or newer, a C11 compiler, pkg-config, GTK4, libadwaita, and json-glib. Install VTE as well if you want an interactive terminal instead of the fallback status page.

On Arch Linux:

sudo pacman -S --needed base-devel cmake pkgconf gtk4 libadwaita json-glib vte4

On Debian or Ubuntu:

sudo apt install build-essential cmake pkg-config libgtk-4-dev \
  libadwaita-1-dev libjson-glib-dev libvte-2.91-gtk4-dev

From a clean checkout, configure and build with:

cmake -S . -B build
cmake --build build

The configure step prints whether VTE was found. If you install VTE after configuring, rerun cmake -S . -B build before rebuilding.

Install the binaries under a prefix:

cmake --install build --prefix ~/.local

That install now also drops a desktop launcher into ~/.local/share/applications, so after installing you can open cmux from your desktop app launcher like a normal terminal app.

Make sure ~/.local/bin is on PATH so the installed cmux command and the desktop launcher can find it:

export PATH="$HOME/.local/bin:$PATH"

To verify the installation before opening the desktop launcher:

command -v cmux
cmux --help

To inspect the upstream Ghostty API during configure, point the build at a checkout or let CMake fetch one:

cmake -B build -DCMUX_GHOSTTY_SOURCE_DIR=/path/to/ghostty
cmake -B build -DCMUX_FETCH_GHOSTTY=ON

Run

Print the Ghostty gate decision:

./build/cmux-ghostty-gate

Run the host directly from the build tree:

./build/cmux
./build/cmux --backend=vte
./build/cmux --backend=ghostty

For normal day-to-day use, install it once and then launch cmux from your desktop launcher. If your desktop menu does not refresh right away, log out and back in once or run:

update-desktop-database ~/.local/share/applications

If VTE was found during configuration, the VTE backend launches the interactive app shell. Without VTE, the app still builds but shows a truthful status page instead of providing a usable terminal. The desktop launcher explicitly requests the VTE backend, so install VTE and reconfigure if that is the behavior you want.

If configuration fails with a missing pkg-config module, install the corresponding development package listed above and rerun the configure command. Run the automated Session, Terminal Backend, and Session Change suites with:

ctest --test-dir build --output-on-failure

A successful configure, build, and test run are the current validation steps.

Arch Linux Releases

Tagged releases include an Arch Linux package and an x86_64 binary bundle. The package is the recommended option because pacman installs the required runtime dependencies and the desktop launcher:

sudo pacman -U cmux-0.2.0-1-x86_64.pkg.tar.zst
cmux

The package targets 64-bit Arch Linux (x86_64). Because Arch is rolling, release artifacts should be used on a reasonably up-to-date Arch system. The binary bundle is useful when you want to unpack it manually, but it still requires the same runtime libraries:

tar -xzf cmux-0.2.0-x86_64.tar.gz
sudo pacman -S --needed gtk4 libadwaita json-glib vte4

Releases are built in a clean Arch Linux environment from version tags such as v0.2.0. To build the package locally from a release source archive:

makepkg -p packaging/PKGBUILD --syncdeps --cleanbuild

Current Features

• Workspace sidebar with switching, rename, duplicate, pin, drag-reorder, and delete controls
• Per-workspace tab strip with create, switch, and close
• Horizontal and vertical split panes
• Keyboard navigation for workspaces, tabs, and pane focus
• Session save and restore to ~/.config/cmux/session.json
• Live workspace cwd/git-branch and tab-title updates from VTE terminal metadata

Shortcuts

• Ctrl+Shift+N: new workspace
• Ctrl+Shift+R: rename active workspace
• Ctrl+Shift+T: new tab
• Ctrl+Shift+D: split horizontally
• Ctrl+Shift+Enter: split vertically
• Ctrl+Shift+W: close tab, or close workspace when it is down to its last tab
• Ctrl+Shift+B: toggle the workspace sidebar
• Ctrl+Shift+K: toggle the keyboard shortcuts dialog
• Ctrl+Shift+C / Ctrl+Shift+V: copy or paste in the active terminal
• Ctrl+Shift+[ / Ctrl+Shift+]: previous or next workspace
• Alt+Shift+1..8: jump to workspace 1 through 8
• Alt+Shift+9: jump to the last workspace
• Ctrl+Tab / Ctrl+Shift+Tab: next or previous tab
• Alt+1..9: jump to tab 1 through 9 in the active workspace
• Alt+Arrow: move focus between panes
• Shift+Enter: send Shift+Enter through to the active terminal
• Ctrl++ / Ctrl+- / Ctrl+0: increase, decrease, or reset UI scale

Known Gaps

• The Ghostty backend remains a documented probe path, not a usable Linux runtime