mux

Switch between AI CLI sessions without breaking your flow.

Running Claude in one session, Codex in another, and a dev server in a third? Switching between them means detaching, listing sessions, remembering which is which, and reattaching. mux eliminates that friction — see every session's live output at a glance, spot which AI tools are active, and switch in a keystroke.

한국어

The Problem

In the age of AI-powered development, a typical workflow looks like:

• Session 1: Claude Code working on your feature
• Session 2: Codex reviewing your test suite
• Session 3: Dev server running your app
• Session 4: Another Claude session refactoring a different module

tmux's built-in choose-session shows you a list of names — but which session has Claude waiting for your input? Which one is still running? You end up cycling through sessions blindly.

How mux solves it

Live preview — every window and pane

See the actual terminal output of any session before you switch. Press Tab to expand a session into its windows, expand again to peek into individual panes — preview each one without attaching.

AI CLI detection

claude, codex, aider, gemini are automatically detected and highlighted with badges — instantly find the right session.

Git branch & worktree display

Each session shows its current git branch. Linked worktrees are visually distinguished so you can tell at a glance which sessions are working on isolated branches.

Cost & token tracking

For Claude Code sessions, mux reads session logs to display real-time token usage and estimated cost — no configuration needed.

Popup overlay

Press one key to summon mux on top of whatever you're doing — even mid-conversation with an AI CLI. Pick a session and you're there.

Vim-style navigation

j/k to browse, / to filter, Enter to attach. No mouse needed.

Quick Start

# One-line interactive installer (recommended)
curl -sSL https://raw.githubusercontent.com/lunemis/mux/main/install.sh | bash

# Or install manually
brew install lunemis/tap/mux   # or: go install github.com/lunemis/mux/cmd/mux@latest
mux                             # launch the session manager

For the best experience, set up popup mode (opens mux as a floating overlay):

mux setup-keybind               # binds prefix + m
tmux source-file ~/.tmux.conf   # reload config

Now press Ctrl+b then m anywhere in tmux to open mux.

Installation

Interactive installer (recommended)

The installer guides you through binary installation and keybinding setup:

curl -sSL https://raw.githubusercontent.com/lunemis/mux/main/install.sh | bash

Homebrew

brew install lunemis/tap/mux

From source

git clone https://github.com/lunemis/mux.git
cd mux
make install   # builds and installs to /usr/local/bin

Go install

go install github.com/lunemis/mux/cmd/mux@latest

Usage

Basic

Run mux to open the session manager. Use j/k to navigate, Enter to attach, q to quit.

The left panel shows your sessions with AI badges and git branches. The right panel shows a live preview of the selected session's terminal output, updated every 500ms.

Popup mode (recommended)

Open mux as a floating overlay inside tmux — works even while AI CLIs are running in the foreground.

# Set up the keybinding (one-time)
mux setup-keybind          # prefix + m (default)
mux setup-keybind Space    # or use a different key

# Reload tmux config
tmux source-file ~/.tmux.conf

You can also open the popup manually with mux popup.

Note: Popup mode requires tmux 3.2+

Statusbar widget

Show AI session icons in your tmux status bar without opening the TUI:

# Add to ~/.tmux.conf
set -g status-right '#(mux status)'

This runs mux status which outputs a compact summary like ✦ ◈ when AI sessions are active.

Works with skimd

Pair with skimd to review AI-generated markdown docs without leaving tmux.

• prefix+m → mux — switch sessions
• prefix+v → skimd — skim documents

Keybindings

Key	Action
j / k	Move down / up
g / G	Jump to first / last
Tab / → / l	Expand session → windows → panes
Shift+Tab / ← / h	Collapse one level
Enter	Attach (focuses the selected window/pane)
n	Create new session
r	Rename session
x	Delete session (with confirmation)
/	Filter sessions by name or path
Esc	Clear filter / cancel
q	Quit

Requirements

• tmux (popup mode requires 3.2+)
• Linux or macOS

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT