mux-sesh

Fast tmux session and Herdr workspace switching from a polished terminal UI.

Why mux-sesh

• Switch between live tmux sessions or Herdr workspaces without leaving the keyboard.
• Launch local projects from a single, searchable picker.
• Keep reusable project rules in config instead of shell scripts.
• Stay inside your multiplexer with previews, quick actions, and lightweight workflows.

Quick Start

mux-sesh runs on Bun and talks directly to tmux or Herdr. Herdr needs no mux-sesh plugin.

Prerequisites:

• Bun
• tmux or Herdr 0.7.5
• git for cloning GitHub repositories from the new-session flow

Install globally:

bun install -g mux-sesh

Run it:

mux-sesh

Recommended tmux binding:

bind-key -n M-w popup -E -w 62% -h 70% "mux-sesh"

Reload tmux after adding the binding:

tmux source-file ~/.tmux.conf

How It Works

• Sessions view shows live tmux sessions or Herdr workspaces.
• Projects view shows scanned or configured directories.
• Selecting a project attaches to an existing session or workspace when possible, or creates one.
• The new-session flow searches files and directories under project_paths as you type, powered by fff.
• Selecting a file creates a session in the file's directory and opens it in your editor.
• Newly created Herdr workspaces and tabs are focused automatically when launching a project or editor.
• The Agents section shows Herdr workspaces with detected native agent status alongside tmux agent sessions and tui_chat; Herdr unknown status and age are hidden.
• The new-session flow can also clone a GitHub repository into your configured repos directory.

Herdr concepts map directly into the UI:

| mux-sesh | Herdr | | -------- | --------- | | Session | Workspace | | Window | Tab | | Pane | Pane |

Backend detection uses HERDR_ENV, then TMUX, then an explicit backend, then running servers. Auto detection chooses tmux when both run and defaults to installed tmux when neither runs.

{ "backend": "herdr" }

Explicit Herdr selection is strict: its server must already run, and mux-sesh never starts it or falls back. Config changes apply on the next mux-sesh launch.

Minimal Configuration

Config lives at ~/.config/mux-sesh/config.json.

{
  "project_paths": ["~/dev"],
  "repos_path": "~/dev/repos",
  "keybind_mode": "vim",
  "prefix_key": "ctrl+x",
  "theme": "rosepine",
  "default_session": {
    "startup_command": "nvim"
  }
}

Full configuration reference: docs/configuration.md

Essential Keys

Default mode is vim.

| Key | Action | | ----------- | --------------------- | | j / k | Move | | Enter | Attach or create | | i | Search | | n | New session | | d | Kill selected session | | 1-9 | Quick select | | Ctrl+P | Open command palette | | q / Esc | Quit |

With the default prefix key, secondary actions live behind ctrl+x:

• ctrl+x s sessions
• ctrl+x p projects
• ctrl+x l last session (tmux only)
• ctrl+x g git root session
• ctrl+x r rename session
• ctrl+x e edit configured target
• ctrl+x Shift+R refresh

In vim mode, s and p are also available as direct view switches.

Full keybinding reference: docs/keybindings.md

Crash recovery

mux-sesh disables OpenTUI's automatic error console so a crash cannot trap the terminal. React UI failures show a recovery screen with these controls:

• c copies the complete diagnostics report with OSC 52 (including tmux passthrough)
• o opens a prefilled GitHub issue for review
• r retries the application UI
• q, Esc, or Ctrl+C restores the terminal and exits
• ↑/↓, j/k, PgUp/PgDn, Home, and End scroll long diagnostics

Uncaught process-level failures restore the terminal first, then print the diagnostics and report URL to normal terminal scrollback before exiting with status 1. Prefilled issues are never submitted automatically; review the report before sending it.

Docs

• Configuration
• Keybindings
• Workflows

Development

bun install
bun run typecheck
bun test

Use bun run build only when you need the compiled binary in dist/mux-sesh.

License

MIT. See LICENSE.

Related

• mux-manager for Telescope-based tmux session management inside Neovim
• Built with OpenTUI