diff --git a/README.md b/README.md index 6e919c1..2c23974 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,70 @@ --- CREATED : 2026-03-03 -UPDATED : +UPDATED : 2026-03-03 AUTHOR : chawley --- -# tmux-menu.sh +# TMUX Hack Session Launcher -A hack tmux menu script to manage multiple tmux sessions +A Bash script designed to manage and automate pre-defined tmux-sessions. This script allows you to launch complex development or administration environments - complete with multiple windows and SSH connections - using a single command. --- -REQ: tmux v3+ +## Features + +- **Automated Session Creation**: Checks if a session exists; if not, it creates it with your pre-defined windows and layouts. +- **Environment Nesting Protection**: Prevents launching a new session if you are already inside an active tmux environment. +- **Custom Configuration Support**: Automatically sources your `$HOME/.tmux.conf`. +- **Session Attaching**: If a requested session is already running, the script simply attaches you to it. +- **Fallback Discovery**: Provides an error message and lists all currently active sessions if an invalid name is provided. --- -## Need +## Prerequisites -After I discovered tmux I searched for a way to manage multiple groups of tmux sessions under one unified script. Not finding anything (or maybe just not looking well enough) I decided to write my own. It's not pretty, but I've been using for a couple of years now and it's become an integral part of my workflow. +- **tmux**: Ensure `tmux` is installed and available in your `$PATH`. +- **SSH Config (Optional)**: For windows that execute SSH commands, ensure your SSH keys or config are set up for seamless connections. -My setup works this way: +--- -Imagine you have multiple SSH connections +## Installation -- web-dev -- web-prod -- database-dev -- database-prod +1. Copy the script to a directory in your `$PATH` (e.g., `~/bin` or `/usr/local/bin`). +2. Rename it to something short, like `tm`. +3. Make the script executable: + ```bash + chmod +x ~/bin/tm + ``` -and you want to group them together in similar groups. +--- -With this script you can name collections of sessions and switch between them easily with just a few keystrokes. +## Usage -Let's see an example using the above connections: +Run the script followed by the name of the pre-defined session: ```bash -case $session in - web) - if [[ $tcheck == 0 ]]; then - tmux new-session -d -s web - tmux rename-window 'local' - tmux new-window -t 1 -n 'root@web-dev' 'exec ssh root@web-dev.example.org' - tmux new-window -t:2 -n 'user@web-prod' 'exec ssh user@webprod.example.org' - fi - tmux attach-session -t web -;; - -case $session in - database) - if [[ $tcheck == 0 ]]; then - tmux new-session -d -s database - tmux rename-window 'local' - tmux new-window -t 1 -n 'root@database-dev' 'exec ssh root@databasedev.example.org' - tmux new-window -t:2 -n 'user@database-prod' 'exec ssh user@wdatabase.example.org' - fi - tmux attach-session -t database -;; +tm mine ``` -Calling the script with a pre-determined session name (ex: `./tmux-menu.sh web` or `./tmux-menu.sh database`) firstchecks to see if there is already a session group with that name. If not, it creates a new group with the commands youspecify and names each connection in tmux. - -If the session group *does* already exist, it simply switches you to that group. - -If you alias `tmux-menu.sh` to something shorter (like `tm`), switching between active sessions is as easy as `Ctrl-A + d` (to detach) and `tm web` (to attach or create the web group). - -Killing session groups is as easy as `tmux-session kill -t web`. +If no session name is provided, or the name doesn't match a case in the script, it will display an error and list all currently active tmux sessions. --- -## Use +## Configuration -I've found that I use this script on different servers with different configurations. So I copy the `tmux-menu.template.sh` to `$HOME/tmux-menu.sh` and then alias that to `tm`. +To add a new session, add a new case stanza inside the `case $session in` block. -I also include my `.tmux.conf` file with comments about what does what. If you choose to use it, make sure to copy it to your home directory. +### Template +```bash + session_name) + if [[ $tcheck == 0 ]]; then + tmux -f "${TMUX_CONF}" new-session -d -s session_name + tmux -f "${TMUX_CONF}" rename-window 'initial_window' + tmux -f "${TMUX_CONF}" new-window -t:1 -n 'second_window' 'command_to_run' + fi + tmux attach-session -t session_name + ;; +``` + +### Script Variables +- `TMUX_CONF`: Defaults to `$HOME/.tmux.conf`. Modify this variable if your configuration file is located elsewhere.