sshmx - SSH Session Manager for tmux

sshmx is a lightweight Bash utility that helps you manage and launch SSH sessions inside tmux.
It integrates with your existing ~/.ssh/config or lets you add/remove sessions interactively, and provides handy tmux key bindings to quickly open SSH connections in popup windows.

✨ Features

Interactive SSH session selector using fzf with multi-select and preview
Automatic JSON session store (~/.sshmx/sessions.json)
Import from ~/.ssh/config or create sessions manually
tmux integration:
- New SSH sessions open in dedicated tmux windows
- Permanent popup window shortcuts (customizable via ~/.tmux.conf)
- Automatic fingerprint acceptance (no host key verification prompts)
Interactive SSH key picker with preview, fingerprint display, and file browser
Jump host (ProxyJump) support
Password and private key support (passwords stored encrypted with GPG; sshpass used for authentication)
Group support: Organize and connect to all sessions in a group at once
Tag support: Connect to sessions by comma-separated tags
Custom color system: User-configurable color mappings (e.g., map "blue" → "colour17")
Export/Import sessions for backups and sharing
Optional colored output with chromaterm
Host IP resolution using getent (if available)
Self-installing script – just run once and it sets itself up
Sync with ~/.ssh/config preserving encrypted passwords and groups
Logging for debugging parsing issues
Session notes: Add, view, and delete per-session notes
Favorites: Mark and quickly access favorite sessions
Templates: Create reusable session templates for quick setup
Health checks: Verify host connectivity with nc or TCP
Statistics: View session counts, usage, and most-connected hosts
Bulk edit: Update groups, jumps, tags, and colors across multiple sessions
Search: Fuzzy search by name, host, group, tags, or description
Quick connect: Partial name matching for fast access
Exports: To SSH config, Ansible inventory, or CSV
Automatic daily backups with retention
Full bash completion for all commands and options

📦 Requirements

tmux
fzf
jq
gpg (for password encryption)
sshpass (optional, for password auth)
chromaterm (optional, for colored output)
getent (optional, for hostname to IP resolution; usually available on Linux)
nc (optional, for health checks)

🚀 Installation

Clone the repository and run the script with the --install flag:

git clone https://github.com/mrbooshehri/sshmx.git
cd sshmx
./sshmx --install

This will:

Create a symlink to ~/.local/bin/sshmx
Add keybindings to your ~/.tmux.conf (or create one if missing)
Add bash completion for all commands
Add ~/.local/bin to your PATH (via ~/.bashrc or ~/.zshrc)
Initialize color mapping configuration

Reload tmux:

tmux source-file ~/.tmux.conf

And source your shell RC file:

source ~/.bashrc  # or ~/.zshrc

🔑 Usage

Basic Commands

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx | Launch interactive session selector with fzf (multi-select, preview) | | sshmx --add / sshmx -a | Add a new SSH session interactively | | sshmx --edit / sshmx -e | Edit an existing session interactively | | sshmx --remove / sshmx -r | Remove one or more sessions interactively (with backup) | | sshmx --clone | Clone an existing session | | sshmx --bulk-edit | Bulk-edit multiple sessions (groups, jumps, tags, colors) |

Installation & Configuration

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --install / sshmx -i | Install script, create symlink, add tmux bindings, bash completion | | sshmx --sync / sshmx -s | Sync ~/.sshmx/sessions.json with ~/.ssh/config (preserves passwords/groups) | | sshmx --configure-colors | Configure color name to tmux color mappings (with 256-color palette preview) | | sshmx --validate-config | Validate SSH config syntax |

Search & Navigation

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --search | Search sessions by name/host/group/tags/description | | sshmx --quick / sshmx -q | Quick connect by partial name match | | sshmx --history / sshmx -h | Show connection history (most recent first) |

Groups & Tags

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --groups / sshmx -g | Select and connect to all sessions in chosen group(s) | | sshmx --tags | Connect to all sessions with selected tag(s) | | sshmx --list-groups | List all sessions organized by group |

Favorites & Templates

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --favorites | Show and connect to favorite sessions | | sshmx --add-favorite | Add sessions to favorites | | sshmx --templates | List available templates | | sshmx --add-template | Create new session template | | sshmx --use-template | Create session from template |

Notes & Documentation

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --add-note | Add note to a session | | sshmx --view-notes | View notes for a session | | sshmx --delete-note | Delete a note from a session |

Health & Statistics

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --check | Check connectivity of selected sessions | | sshmx --check-all | Check connectivity of all sessions | | sshmx --stats | Show session statistics and usage |

Multiplex Operations

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --multiplex / sshmx -m | Combine windows into synchronized pane for multi-host commands | | sshmx --demultiplex / sshmx -d | Restore multiplexed windows to separate panes |

Import/Export

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --export [file] | Export sessions.json to a backup file | | sshmx --import [file] | Import sessions from a JSON file (backs up existing) | | sshmx --export-config [file] | Export to SSH config format | | sshmx --export-ansible [file] | Export to Ansible inventory format | | sshmx --export-csv [file] | Export to CSV format |

Other

| Command | Description | | ------------------------------ | ----------------------------------------------------------------- | | sshmx --completion | Generate bash completion script | | sshmx --debug | Debug sessions.json structure | | sshmx --help | Show help message |

🎨 Color Configuration

The script supports a user-configurable color mapping system that lets you use friendly color names (like "blue", "white") that map to actual tmux color values (like "colour17", "colour7").

Configure Colors

sshmx --configure-colors

This opens an interactive menu where you can:

Edit a color mapping - Map friendly names to tmux col

Sshmx

Install / Use

README