mux-sesh

A beautiful, fast tmux session manager built with OpenTUI and TypeScript

Features

• Fuzzy search - Find sessions and projects instantly
• Lightning fast - Built with Bun and OpenTUI
• Beautiful UI - Catppuccin-themed interface
• Vim keybindings - Navigate with j/k or arrow keys
• Project scanning - Browse and create sessions from local directories
• GitHub integration - Clone repos directly from URLs
• Quick select - Use number keys (1-9) for instant switching
• Session management - Create, switch, kill, and rename sessions

Installation

Prerequisites

• Bun - JavaScript runtime (required)
• Zig - Required for building OpenTUI
• tmux - Terminal multiplexer
• git - For GitHub cloning feature

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Install Zig (macOS)
brew install zig

# Install Zig (Linux - check https://ziglang.org/download/)

Install from npm/Bun

bun install -g mux-sesh

# Then run
mux-sesh

Install from Source

git clone https://github.com/quiet-ghost/mux-sesh.git
cd mux-sesh
git checkout opentui-convert

# Install dependencies
bun install

# Build standalone executable
bun run build

# Install globally
sudo cp dist/mux-sesh /usr/local/bin/
# or
cp dist/mux-sesh ~/.local/bin/

Keybindings

Normal Mode

| Key | Action | |-----|--------| | j / k or ↑ / ↓ | Navigate up/down | | 1-9 | Quick select session/project | | Enter | Switch to session / Create from project | | i | Enter search mode | | n | Create new session | | d | Kill selected session | | r | Rename selected session | | R | Refresh list | | s | Switch to sessions view | | p | Switch to projects view | | q or Esc | Quit |

Search Mode

| Key | Action | |-----|--------| | Type to search | Filter sessions/projects | | Enter | Select first result | | ↑ / ↓ | Navigate results | | Esc | Cancel search |

New Session Mode

| Key | Action | |-----|--------| | Type project name | Filter projects | | Paste GitHub URL | Clone and create session | | Type custom name | Create named session | | Enter | Confirm selection | | Esc | Cancel |

Configuration

Configuration is stored at ~/.config/mux-sesh/config.json:

{
  "project_paths": ["~/dev", "~/personal", "~/work"],
  "repos_path": "~/dev/repos",
  "editor": "nvim",
  "editor_cmd": "nvim -c \"lua vim.defer_fn(function() if pcall(require, 'telescope') then vim.cmd('Telescope find_files') end end, 100)\"",
  "keybind_mode": "vim", #other option is 'standard'
  "start_in_search_mode": false
}

Configuration Options

• project_paths - Array of directories to scan for projects
• repos_path - Directory where GitHub repositories will be cloned
• editor - Default editor to use
• editor_cmd - Command to run when opening editor
• keybind_mode - alternative keybinds for those who do not want vim like binds
• start_in_search_mode - Start in search mode by default

tmux Integration

For the best experience, bind mux-sesh to a global tmux keybinding. Add this to your ~/.tmux.conf:

# Open mux-sesh in a popup with Alt+w (no prefix required)
bind-key -n M-w popup -E -w 62% -h 70% "mux-sesh"

After adding the binding, reload your tmux config:

tmux source-file ~/.tmux.conf

Now you can press Alt+w from anywhere in tmux (including inside nvim) to launch mux-sesh.

Alternative Integration:

• From Neovim: Use mux-manager - a Telescope-based tmux session manager that integrates directly into Neovim
• With prefix: Use bind-key f popup -E -w 80% -h 80% "mux-sesh" if you prefer requiring the tmux prefix key first

Usage Examples

Quick Session Switching

# Open mux-sesh
mux-sesh

# Press 1-9 to instantly switch to that session
# Or use j/k to navigate and Enter to select

Create Session from Project

mux-sesh

# Press 'n' for new session
# Type project name to filter
# Press Enter to create session in that directory

Clone from GitHub

mux-sesh

# Press 'n' for new session
# Paste GitHub URL:
#   https://github.com/user/repo
#   or
#   [email protected]:user/repo.git
# Press Enter to clone and create session

Search Existing Sessions

mux-sesh

# Press 'i' to search
# Type to filter sessions
# Press Enter to switch to first match

Color Scheme

mux-sesh uses the beautiful Catppuccin color scheme with the following palette:

• Primary: #f38ba8 (Pink)
• Active: #a6e3a1 (Green)
• Inactive: #6c7086 (Gray)
• Border: #89b4fa (Blue)
• Key: #f9e2af (Yellow)
• Action: #cba6f7 (Mauve)

Cross-Platform - Works on Linux, macOS, Windows

Development

# Install dependencies
bun install

# Run in dev mode (with hot reload)
bun run dev

# Type check
bun run typecheck

# Build for production
bun run build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

• Inspired by ThePrimeagen's tmux-sessionizer
• Built with OpenTUI
• UI design inspired by nvim telescope plugin

Related Projects

• mux-manager - Telescope-based tmux session manager for Neovim