{"slug": "mux-a-tmux-overlay-for-managing-claude-code-sessions", "title": "Mux – A tmux overlay for managing Claude Code sessions", "summary": "Developer fashton28 released Mux, a tmux overlay that manages Claude Code sessions by displaying them in a floating, sorted list with live previews. The tool highlights sessions waiting for user input and allows instant jumping, aiming to streamline multi-session workflows for Claude Code users.", "body_md": "**A Claude Code session manager that lives in your terminal.**\n\nRunning several Claude Code sessions across tmux panes and windows? `mux`\n\nshows them all in one\nfloating overlay - sorted so the sessions **waiting on you** rise to the top - so you always know\nwhich one needs attention and how long it has been stuck. Pick one and you jump straight to it.\n\n```\n● waiting  work       ~/dev/api            2899m   │  <live preview of the\n● waiting  work       ~/dev/web             304m   │   highlighted session's\n● working  main       ~/dev/cli               0m   │   terminal screen>\n● idle     main       ~/dev/infra            12m   │\n○ ?        scratch    ~/dev/scratch          7m   │\nClaude sessions - j/k: move - J/K: scroll - enter: jump - ctrl-x: kill\n```\n\nEach row shows, left to right: a **status** dot/label, the **tmux session** the Claude session\nruns in, its **working directory**, and how long it has been in its current status. The pane on the\nright is a live preview of the highlighted session's screen.\n\n**Find the blocked one instantly**- sessions waiting for your input are colored and sorted first.** Jump in one keypress**-`Enter`\n\ntakes 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.\n\n| Tool | Version | Notes |\n|---|---|---|\n`tmux` |\n\n`fzf`\n\n**≥ 0.38**`become`\n\n, `reload`\n\n, `--track`\n\n`jq`\n\n`bash`\n\n, `ps`\n\nInstall the three tools with your package manager, e.g. `brew install tmux fzf jq`\n\n(macOS) or\n`sudo apt install tmux fzf jq`\n\n(Debian/Ubuntu).\n\nThroughout this README,\n\nmeans your tmux prefix key -`prefix`\n\n`Ctrl-b`\n\nby default. So \"`prefix + u`\n\n\" means press`Ctrl-b`\n\n, release, then press`u`\n\n.\n\n[TPM](https://github.com/tmux-plugins/tpm) (the Tmux Plugin Manager) is the easiest way to install\nand keep mux updated.\n\n-\n**Install TPM**(skip if you already have it):\n\n```\ngit clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm\n```\n\n-\n**Add mux to your** Put the plugin lines near the bottom, and keep the TPM`~/.tmux.conf`\n\n.`run`\n\nline as the very last line:\n\n```\nset -g @plugin 'tmux-plugins/tpm'\nset -g @plugin 'fashton28/mux'\n\nrun '~/.tmux/plugins/tpm/tpm'   # keep this last\n```\n\n-\n**Reload tmux and fetch the plugin.** From inside tmux, reload the config:\n\n```\ntmux source-file ~/.tmux.conf\n```\n\nthen press\n\n(capital`prefix + I`\n\n`I`\n\n) to download mux.\n\nThat's it. Press ** prefix + u** to open the overlay.\n\n`mux`\n\nis a single self-contained script. Clone the repo and source its tmux entrypoint from your\n`~/.tmux.conf`\n\n:\n\n```\ngit clone https://github.com/fashton28/mux ~/.tmux/plugins/mux\nrun-shell '~/.tmux/plugins/mux/mux.tmux'\n```\n\nReload (`tmux source-file ~/.tmux.conf`\n\n) and press ** prefix + u**.\n\nPrefer no tmux integration at all? The `mux`\n\nscript works on its own - put it on your `PATH`\n\n(`ln -s \"$PWD/mux\" /usr/local/bin/mux`\n\n) and bind it yourself, or just run `mux list`\n\n.\n\n- Start a few Claude Code sessions inside tmux - run\n`claude`\n\nin separate panes or windows. - Press\nfrom any tab. The overlay floats over your screen.`prefix + u`\n\n- Move through the list, watch the preview, and\n`Enter`\n\nto jump into a session.\n\nmux only lists Claude sessions on **your current tmux server** (so every row is one you can jump\nto). Sessions running outside tmux, in another tmux server, or already finished are not shown.\n\n| Key | Action |\n|---|---|\n`j` / `k` |\nmove selection down / up (vim) |\n`J` / `K` |\nscroll the preview pane down / up (Shift) |\n`↑` / `↓` |\nmove selection (preview follows) |\n`Enter` |\njump to the selected session and close the overlay |\n`ctrl-x` |\nterminate the selected session (SIGTERM; its pane stays, drops to a shell) |\n`Esc` |\nclose the overlay |\ntype |\nfuzzy-filter the list (any key except the navigation keys `j k J K` ) |\n\n| Dot | Status | Meaning |\n|---|---|---|\n| 🔵 | `waiting` |\nthe session needs your input - deal with these first |\n| 🟠 | `working` |\nactively running |\n| 🟢 | `idle` |\nfinished and ready |\n| ⚪ | `?` |\nstatus could not be determined |\n\nRows are sorted `waiting → working → idle → ?`\n\n, and within each group the session that has been in\nits status **longest** appears first - so a session that has been waiting on you for hours floats\nto the very top. The right-hand number is minutes since the status last changed.\n\nSet these tmux options **before** the TPM `run`\n\nline in `~/.tmux.conf`\n\n:\n\n```\nset -g @mux-key 'C'   # which prefix key opens mux (default: 'u')\n```\n\nThe overlay is the main interface, but the script exposes subcommands directly:\n\n```\nmux                                   # launch the fzf overlay (what the keybinding runs)\nmux list                              # print the formatted session list\nmux preview <pane>                    # print a tmux pane's live screen\nmux jump <pane> <window> <session>    # switch to a session's pane\nmux kill <pid>                        # SIGTERM a Claude session (guarded)\n```\n\nMake sure the config reloaded (`prefix + u`\n\ndoes nothing.`tmux source-file ~/.tmux.conf`\n\n) and, for TPM, that you pressed`prefix + I`\n\n. Check the key isn't already bound:`tmux list-keys | grep ' u '`\n\n.**The overlay opens but the list is empty.** mux only shows live Claude sessions on the current tmux server. Start`claude`\n\ninside a tmux pane, or check you're attached to the right server.Upgrade fzf (`mux: fzf >= 0.38 required`\n\n.`brew upgrade fzf`\n\n, or grab a release from the[fzf repo](https://github.com/junegunn/fzf/releases)).Pick a different key with`u`\n\ncollides with another binding.`set -g @mux-key '...'`\n\n.\n\nThe session-listing logic sits behind a single test seam: `mux list`\n\nreads its external inputs from\nenvironment variables, making it a pure, deterministic function you can drive with fixtures - no live\ntmux server or real Claude processes required.\n\n```\nMUX_SESSIONS_DIR=tests/fixtures/sessions \\\nMUX_PANES_FILE=tests/fixtures/panes.txt \\\nMUX_PPID_FILE=tests/fixtures/ppids.txt \\\nMUX_NOW=1782657704 \\\n  mux list\n```\n\nRun the checks (needs [ bats](https://github.com/bats-core/bats-core) and\n\n`shellcheck`\n\n):\n\n```\nbats tests/\nshellcheck -s bash mux mux.tmux\n```\n\n", "url": "https://wpnews.pro/news/mux-a-tmux-overlay-for-managing-claude-code-sessions", "canonical_source": "https://github.com/fashton28/mux", "published_at": "2026-06-28 23:42:55+00:00", "updated_at": "2026-06-28 23:58:40.572029+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["fashton28", "Mux", "Claude Code", "tmux", "fzf", "jq", "TPM"], "alternates": {"html": "https://wpnews.pro/news/mux-a-tmux-overlay-for-managing-claude-code-sessions", "markdown": "https://wpnews.pro/news/mux-a-tmux-overlay-for-managing-claude-code-sessions.md", "text": "https://wpnews.pro/news/mux-a-tmux-overlay-for-managing-claude-code-sessions.txt", "jsonld": "https://wpnews.pro/news/mux-a-tmux-overlay-for-managing-claude-code-sessions.jsonld"}}