ste-mux for SwiftBar

31 Mar 2023

Since I began using Jekyll as the static site generator for my web sites, I have been hosting locally while I modify structural changes and write the content prior to publishing. Serving the sites locally involves me running terminal sessions that run the web server. Unless I am actively working on something where I need to check what the web server is doing, I always wanted it to be out of the way, ideally tucked under some icon on the Mac’s menu bar. A menu bar terminal app kind of felt like what I was after.

Recently I was reading a post that made reference to “bitbar” an application that allowed you to put text and menu items into your menu bar based on a script. I’d come across this and similar apps many times before, but never had a reason to use them. Until now that is, as I realised I might just be able to create my own solution for my out of sight, but still accessible local web server management.

SwiftBar

After a little look at Xbar, the reboot of the original bitbar, I noted that SwiftBar seemed to be in active development and was a little more appealing to me. I opted to take SwiftBar as my utility of choice, but I strongly suspect that my little plugin will work with Xbar and other similarly rooted utility apps too.

So what is SwiftBar? Well, it’s an app that will run scripts on a periodic basis that can build a custom menu bar entry to display content and options which can in turn trigger other scripted actions. There is lots of detail on SwiftBar’s GitHub repo about this.

Building a Plugin Script

With the utility in place, I initially took a look around the existing plugins, in particular, I was looking for something that might let me manage terminal sessions through tmux. I found the Mac-Mux plugin by @etopiei.

This plugin confirmed to me that what I wanted to do was possible, but I wanted something with a bit more functionality.

I know at least enough shell scripting to be a danger to self and others and so I figured I’d take a shot at building something myself. That was my first step down the rabbit hole.

I soon managed to put together a script that was broadly similar to the Mac-Mux plugin script, but this one allowed me to start specifying my own custom tmux sessions with their own names - so I would know what the sessions were intended to do; generally open a tmux session, start a particular Jekyll web server, and immediately detach the session.

I experimented a little with the tmux functionality and added options to list attached sessions as well as to be able to terminate any running tmux session.

Once that was all working, I spent a while tidying up some of the code and adding some comments. The next step was to take the data that I’d effectively hard coded into the script and move it out into a separate file. My initial thought was to make it a simple data file, but after some consideration, I made it a second script file, but one that uses specific sets of commands that specify my tmux sessions as a set of parameters. While it isn’t the most user friendly of options, it does provide a good deal of flexibility, and allowed me to separate my personal data out of the main plugin script, which meant it was easier to share. Oh and pulling it out like that resulted in my moving some custom functions into a library script for use by both other script files.

This had got as little more complicated but I figured that this was a good point at which I could write a quick blog post and share the plugin. It seemed to do everything I wanted it to.

It was about then I had to connect to one of my other machines and I thought - “hey, why not add in a bit of support for secure shell sessions too?” It seemed like that should be a relatively quick and easy addition given some of the complexity of managing tmux sessions. After a bit of judicious cloning and modification of some of the code I’d created for the tmux management, I soon had some simple options for triggering SSH sessions. My SSH commands ended up being defined in the same file as the tmux definitions, and I had a bit of scripting around them to build them out into the SwiftBar menus.

Then I thought - “should I limit this to SSH and TMUX?” The obvious answer was of course, “no”. As a result I then spent a while adding a generic run command option into the plugin script and I put a few examples in alongside my tmux and SSH commands for testing purposes.

And then I reworked some of the plugin script again and ended up splitting out the tmux session commands from the other commands as I decided I really wanted to make this a “TMUX-first” plugin.

So what I’d expected to be a project for a few hours turned into something many times larger than that as I tinkered away.

Then I decided, if I was going to share this, it was going to need some more thorough testing and a set of examples, and off I went once again, beavering away and revising things as I went. Adding more checks and comments. Changing the core script to use a settings file so I could quickly switch between sets of test configuration (via a bit of scripting and an Alfred workflow I created just for the purpose).

At this point it was “done”.

Next…

And then I realised if I wanted to share this, it actually did offer quite a bit now, and a blog post probably wasn’t going to be adequate.

Since most other plugins I’d come across for use with SwiftBar were in GitHub I figured I’d put everything in a repo and use GitHub’s wiki feature to write a couple of pages of documentation.

After battling with some infuriating issues with GitHub’s wiki (I should just have done it with Jekyll - unbelievably it would have been quicker!) I ended up with a surprising eleven pages of documentation.

I set up a few extra bits and pieces in the repo and decided I really was done this time and I should write up a post to go with it being available.

Get the Plugin

After a bit of general business and illness, I’m finally writing the post. What started as a mini-project at the start of the month has ended to running through the whole of March. The plugin has been getting plenty of use this month through testing, and as I write this post, it is now also getting some more real use as I started a tmux session to run Jekyll while I write and check this very post on my Mac.

If you want to grab a copy of the plugin or read more about the functionality of Ste-Mux, you can head over to the GitHub Repo.