Adding Custom TMUX Entries

Overview

By default, the installation of Ste-Mux will include the deployment of the file .ste-mux-tmux-custom.sh. This is a script file that is intended to contain custom tmux commands that you can trigger from within Ste-Mux.

Rather than just starting a basic tmux session, the aim is to allow you to do things such as start a named session, run initial commands, and to choose whether to remain attached to the session or to automatically detach.

The standard file comes pre-configured with some example tmux commands, but these are commented out and you customise and add to them to create your own commands.

Editing the Custom TMUX Commands File

Because the file name begins with a period (".") it will be hidden in the file system by default. To view the file, you need to set Finder or your file management app of choice to show hidden files.

The file is purposefully set as hidden to stop SwiftBar identifying it as a plugin.

File Structure

The file structure consists of three sections.

The first section sets up ZSH as the shell of choice (the default shell on modern macOS), and includes some comments.

#!/bin/zsh
# This file gets executed by ste-mux.sh, so you can use it to add your own custom tmux commands
# There are two clearly marked sections. One you should leave alone, and one you can feel free to edit.

The next section, bounded by a couple of markers should be left alone. This section sets up the file to be used with Ste-Mux. The section begins with...

# -----------------------------------------------------
# ⬇ ⬇ ⬇ ⬇ ⬇ WARNING: DO NOT EDIT THIS SECTION ⬇ ⬇ ⬇ ⬇ ⬇
# ----------------------------------------------------

...and ends with...

# -----------------------------------------------------
# ⬆ ⬆ ⬆ ⬆ ⬆ WARNING: DO NOT EDIT THIS SECTION ⬆ ⬆ ⬆ ⬆ ⬆
# -----------------------------------------------------

Conversely, the section where tmux-related commands should be added is the third section and is clearly labelled. The section begins with...

# ---------------------------------------------
# ⬇ ⬇ ⬇ ⬇ ⬇ PLEASE EDIT THIS SECTION ⬇ ⬇ ⬇ ⬇ ⬇
# ---------------------------------------------

...and ends with...

# ---------------------------------------------
# ⬆ ⬆ ⬆ ⬆ ⬆ PLEASE EDIT THIS SECTION ⬆ ⬆ ⬆ ⬆ ⬆
# ---------------------------------------------

Menus

SwiftBar, and by extension Ste-Mux utilises a menu based system to access information and actions. If you are not already familiar with how menus are constructed, it may be worth familiarising yourself with the Menus page, which describes how to add items of information, sub menus, and menu separators.

Example TMUX Commands

The following examples are all available by default in the .ste-mux-tmux-custom.sh. "Please Edit Me" section. All of the commands are set to appear under the "TMUX" sub menu, after a menu spacer line (the uncommented echo "-----" at the start of the editable section).

Because tmux commands tend to be specific to the needs of the individual, all of the actionable entries in this file are commented out by default and are provided as examples that you can copy and customise to meet your own needs.

If you uncomment the commands, the entries would appear like this.

Generic TMUX Commands

Throughout these examples, you will see the use of the function namedSessionAddition. This function is defined in the Common Functions section, and is intended to make the definition of a tmux command to Ste-Mux/SwiftBar, easier.

The first parameter of namedSessionAddition is the path to the main plugin script being run by SwiftBar. This is accessible through the OSP (Original Script Path) variable, which by default is set to be equal to an environment variable STEMUX, which is set by the main script.

OSP was used rather than STEMUX as this helps with testing and debugging multiple script files.

Work

When uncommented, the example command below would set up an entry called "Start my work session ●" in the Ste-Mux TMUX sub menu. The ● is an indicator that this session will remain attached when set up is complete.

Triggering will create a new terminal tmux session called "DayJob". When the session is established, the date and time is displayed on two successive lines.

namedSessionAddition "$OSP" "my work" "DayJob" "date '+DATE: %Y-%m-%d%nTIME: %H:%M:%S'" "true"

Website

When uncommented, the example command below would set up an entry called "Start my website session ○" in the Ste-Mux TMUX sub menu. The ○ is an indicator that this session will detach from the session when the set up is complete.

Triggering will create a new terminal tmux session called "Web". When the session is established, it would change to a directory called "Web" in the user's home folder and run a Jekyll web server.

namedSessionAddition "$OSP" "my website" "Web" "cd ~/Web && bundle exec jekyll serve" "false"