cmux-linux

About

cmux for Linux is a full native port of cmux (originally a macOS Swift/AppKit app) rebuilt in Rust on GTK4. It provides the same experience — tabs, splits, workspaces, notifications, browser automation, and a scriptable socket API — running natively on Linux with GPU-accelerated terminal rendering via Ghostty.

Built for developers running multiple AI coding agents (Claude Code, Codex, etc.) in parallel who need visibility into which agent needs attention and the ability to script browser interactions alongside terminal sessions.

Features

• GPU-accelerated terminal — Powered by libghostty with GTK4 GtkGLArea rendering
• Workspaces, tabs, and split panes — Organize parallel agent sessions
• Notification system — Per-pane bell tracking, sidebar indicators, desktop notifications
• In-app browser — CDP-based browser automation with accessibility tree snapshots, element interaction, and JS evaluation via agent-browser
• Scriptable CLI — cmux CLI with 34+ subcommands for workspaces, panes, surfaces, and browser control
• Socket API — v2 JSON-RPC over Unix socket with SO_PEERCRED auth
• SSH remote workspaces — cmuxd-remote deployment with bidirectional PTY proxy and reconnect
• Ghostty compatible — Reads your existing ~/.config/ghostty/config for themes, fonts, and colors
• Session persistence — Atomic save/restore of full split tree topology with divider ratios

Install

Debian / Ubuntu (.deb)

sudo dpkg -i cmux_0.1.0_amd64.deb
sudo apt-get install -f  # install dependencies if needed

Fedora / RHEL (.rpm)

sudo rpm -i cmux-0.1.0-1.x86_64.rpm

Build from source

# Prerequisites:
#   - Rust toolchain (rustup)
#   - Zig 0.15.2 (mise/asdf, or download from ziglang.org)
#   - GTK4 + libclang + libc++ dev headers
#       Debian/Ubuntu:  sudo apt-get install libgtk-4-dev libclang-dev libc++-dev libc++abi-dev
#       Fedora/RHEL:    sudo dnf install gtk4-devel clang-devel libcxx-devel libcxxabi-devel
#       Arch:           sudo pacman -S gtk4 clang libc++ libc++abi
#
# setup-linux.sh runs `git submodule update --init --force ghostty` for you;
# the --force is required because the previously pinned ghostty SHA
# (4845e82d) is no longer reachable on manaflow-ai/ghostty.
./scripts/setup-linux.sh                      # builds ghostty-internal.a
cargo build --release                         # builds cmux-app, cmux, cmux-generate, agent-browser
./scripts/install-cmuxd-remote.sh             # builds + installs cmuxd-remote SSH helper

The agent-browser crate lives in the agent-browser/ submodule (vercel-labs/agent-browser) and is built as part of the workspace; cargo build --release produces it at target/release/agent-browser. Browser commands (cmux browser …) require this binary to be on $PATH or under ~/.local/share/cmux/bin/agent-browser.

Browser Automation

Agents running inside cmux can discover and use browser automation via the cmux browser CLI:

# Open a site (https:// auto-prepended if no scheme)
cmux browser open slashdot.org            # returns surface:1 handle

# Interact with the page
cmux browser surface:1 snapshot --interactive  # accessibility tree with element refs
cmux browser surface:1 click e3               # click element by ref
cmux browser surface:1 fill e5 "search term"  # fill input field
cmux browser surface:1 eval 'document.title'  # evaluate JavaScript

# Navigation
cmux browser surface:1 goto example.com
cmux browser surface:1 back
cmux browser surface:1 forward
cmux browser surface:1 reload

# Management
cmux browser list                          # list browser surfaces
cmux browser close --surface surface:1     # close a surface

Browser commands default to JSON output (agents are the primary consumers). Use --no-json for human-readable output.

CLI Reference

cmux --help                    # all commands
cmux browser --help            # browser subcommands

# Terminal management
cmux list-workspaces           # list all workspaces
cmux new-workspace             # create workspace
cmux list-surfaces             # list terminal surfaces
cmux split --direction horizontal  # split current pane
cmux list-panes                # list all panes

# System
cmux identify                  # instance info (version, platform, pid)
cmux ping                      # check connectivity
cmux raw <method> --params '{}' # send arbitrary JSON-RPC

Socket Path

The cmux socket is at $XDG_RUNTIME_DIR/cmux/cmux.sock (typically /run/user/$UID/cmux/cmux.sock).

Override with CMUX_SOCKET environment variable or --socket flag.

Agent Skills

When installed via .deb or .rpm, agent skills are available at /usr/share/cmux/skills/:

• cmux — Core terminal multiplexer skill (workspaces, panes, surfaces, socket CLI)
• cmux-browser — Browser automation skill (open sites, interact with pages, extract data)

A CLAUDE.md at /usr/share/cmux/CLAUDE.md references skill paths so Claude Code discovers them automatically.

Architecture

• Language: Rust
• UI toolkit: GTK4 via gtk4-rs
• Terminal engine: Ghostty (manaflow-ai fork) via libghostty C FFI
• Async runtime: tokio + glib spawn_local bridge
• Browser automation: agent-browser daemon with CDP protocol
• Remote sessions: Go daemon (cmuxd-remote) reused from macOS codebase
• Socket protocol: v2 JSON-RPC, wire-compatible with macOS cmux

Keyboard Shortcuts

Shortcuts are configurable via TOML config file.

Building Packages

# Build all release binaries
cargo build --release --bin cmux --bin cmux-app
# agent-browser is an external sidecar binary (not in this repo). Build it
# from https://github.com/vercel-labs/agent-browser and drop the binary at
# ~/.local/share/cmux/bin/agent-browser, or `cp` it next to your packaging
# inputs before running build-deb.sh / build-rpm.sh.

# Build .deb
./packaging/scripts/build-deb.sh

# Build .rpm
./packaging/scripts/build-rpm.sh

# Validate packages
./packaging/scripts/validate-deb.sh
./packaging/scripts/validate-rpm.sh

License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

See LICENSE for the full text.

Upstream

Linux port of cmux by manaflow-ai.