# Mux – A tmux overlay for managing Claude Code sessions > Source: > Published: 2026-06-28 23:42:55+00:00 **A Claude Code session manager that lives in your terminal.** Running several Claude Code sessions across tmux panes and windows? `mux` shows them all in one floating overlay - sorted so the sessions **waiting on you** rise to the top - so you always know which one needs attention and how long it has been stuck. Pick one and you jump straight to it. ``` ● waiting work ~/dev/api 2899m │ ● idle main ~/dev/infra 12m │ ○ ? scratch ~/dev/scratch 7m │ Claude sessions - j/k: move - J/K: scroll - enter: jump - ctrl-x: kill ``` Each row shows, left to right: a **status** dot/label, the **tmux session** the Claude session runs in, its **working directory**, and how long it has been in its current status. The pane on the right is a live preview of the highlighted session's screen. **Find the blocked one instantly**- sessions waiting for your input are colored and sorted first.** Jump in one keypress**-`Enter` takes you straight to that session's pane, even across windows.**No setup per session**- it reads Claude Code's own status files; nothing to configure or wrap.** Live**- the list and timers refresh on their own while the overlay is open. | Tool | Version | Notes | |---|---|---| `tmux` | `fzf` **≥ 0.38**`become` , `reload` , `--track` `jq` `bash` , `ps` Install the three tools with your package manager, e.g. `brew install tmux fzf jq` (macOS) or `sudo apt install tmux fzf jq` (Debian/Ubuntu). Throughout this README, means your tmux prefix key -`prefix` `Ctrl-b` by default. So "`prefix + u` " means press`Ctrl-b` , release, then press`u` . [TPM](https://github.com/tmux-plugins/tpm) (the Tmux Plugin Manager) is the easiest way to install and keep mux updated. - **Install TPM**(skip if you already have it): ``` git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm ``` - **Add mux to your** Put the plugin lines near the bottom, and keep the TPM`~/.tmux.conf` .`run` line as the very last line: ``` set -g @plugin 'tmux-plugins/tpm' set -g @plugin 'fashton28/mux' run '~/.tmux/plugins/tpm/tpm' # keep this last ``` - **Reload tmux and fetch the plugin.** From inside tmux, reload the config: ``` tmux source-file ~/.tmux.conf ``` then press (capital`prefix + I` `I` ) to download mux. That's it. Press ** prefix + u** to open the overlay. `mux` is a single self-contained script. Clone the repo and source its tmux entrypoint from your `~/.tmux.conf` : ``` git clone https://github.com/fashton28/mux ~/.tmux/plugins/mux run-shell '~/.tmux/plugins/mux/mux.tmux' ``` Reload (`tmux source-file ~/.tmux.conf` ) and press ** prefix + u**. Prefer no tmux integration at all? The `mux` script works on its own - put it on your `PATH` (`ln -s "$PWD/mux" /usr/local/bin/mux` ) and bind it yourself, or just run `mux list` . - Start a few Claude Code sessions inside tmux - run `claude` in separate panes or windows. - Press from any tab. The overlay floats over your screen.`prefix + u` - Move through the list, watch the preview, and `Enter` to jump into a session. mux only lists Claude sessions on **your current tmux server** (so every row is one you can jump to). Sessions running outside tmux, in another tmux server, or already finished are not shown. | Key | Action | |---|---| `j` / `k` | move selection down / up (vim) | `J` / `K` | scroll the preview pane down / up (Shift) | `↑` / `↓` | move selection (preview follows) | `Enter` | jump to the selected session and close the overlay | `ctrl-x` | terminate the selected session (SIGTERM; its pane stays, drops to a shell) | `Esc` | close the overlay | type | fuzzy-filter the list (any key except the navigation keys `j k J K` ) | | Dot | Status | Meaning | |---|---|---| | 🔵 | `waiting` | the session needs your input - deal with these first | | 🟠 | `working` | actively running | | 🟢 | `idle` | finished and ready | | ⚪ | `?` | status could not be determined | Rows are sorted `waiting → working → idle → ?` , and within each group the session that has been in its status **longest** appears first - so a session that has been waiting on you for hours floats to the very top. The right-hand number is minutes since the status last changed. Set these tmux options **before** the TPM `run` line in `~/.tmux.conf` : ``` set -g @mux-key 'C' # which prefix key opens mux (default: 'u') ``` The overlay is the main interface, but the script exposes subcommands directly: ``` mux # launch the fzf overlay (what the keybinding runs) mux list # print the formatted session list mux preview # print a tmux pane's live screen mux jump # switch to a session's pane mux kill # SIGTERM a Claude session (guarded) ``` Make sure the config reloaded (`prefix + u` does nothing.`tmux source-file ~/.tmux.conf` ) and, for TPM, that you pressed`prefix + I` . Check the key isn't already bound:`tmux list-keys | grep ' u '` .**The overlay opens but the list is empty.** mux only shows live Claude sessions on the current tmux server. Start`claude` inside a tmux pane, or check you're attached to the right server.Upgrade fzf (`mux: fzf >= 0.38 required` .`brew upgrade fzf` , or grab a release from the[fzf repo](https://github.com/junegunn/fzf/releases)).Pick a different key with`u` collides with another binding.`set -g @mux-key '...'` . The session-listing logic sits behind a single test seam: `mux list` reads its external inputs from environment variables, making it a pure, deterministic function you can drive with fixtures - no live tmux server or real Claude processes required. ``` MUX_SESSIONS_DIR=tests/fixtures/sessions \ MUX_PANES_FILE=tests/fixtures/panes.txt \ MUX_PPID_FILE=tests/fixtures/ppids.txt \ MUX_NOW=1782657704 \ mux list ``` Run the checks (needs [ bats](https://github.com/bats-core/bats-core) and `shellcheck` ): ``` bats tests/ shellcheck -s bash mux mux.tmux ```