This tool is supposed to help manage tmux sessions for larger projects, e.g. with multiple 'packages', e.g. front-end, back-end, and shared code, which are all editied in individual editors, grouped into separate tmux windows.
This tool embraces that your TMUX environment may change, but you generally have a desired configuration that can be expressed in a configuration.
This means this tool is designed to be executed while you have the session running. Any missing windows and panes will be recreated. Did you accidentally close a window you didn't mean to? Start the project, and the missing window will be recreated.
This features is not yet implemented, but an original design goal was to support multiple layouts for different tasks, or different working environment.
E.e., in my office environment, I have the desktop monitor and 2 external monitors. Here, I'd like to have the center monitor for my editor, and the other external monitof for feedback. Feedback could include one or more test runners and compilers. Thus, I would have test runner and editor on separate windows.
But when just using the laptop, I'd want to have the test runner and editor as two separate panes in the same TMUX window.
So for a single configured project, you should be able to switch between different layouts.
I have tried other tools, e.g. tmuxinator the tmux-resurrect.
Tmuxinator, apart from being bugged1, was a one-time configuration. If you change the configuration, you need to completely kill the session, and restart.
Muxify can in that respect be described as a bug-free tmuxinator, that can apply configuration changes to an existing session.
Tmux-resurrect served as a trusty replacement for tmuxinator for a long time. But I had a lot of projects each with their own setup. Resurrect restores all tmux sessions. The result was that I would have 10-20 tmux sessions running, when only a few were relevent.
tldr; It works, but configuration format will change.
- The configuration files doesn't yet support multiple layouts for a project.
- Error messages are very poor.
- There is no validation, e.g. a project and window names must be valie project and session names; but that is not validated when loading the configuration.
The tool is currently working, i.e. you can run it, it will read a configuration
from $XDG_CONFIG_HOME/muxify/projects.yaml or fallback to
$HOME/.config/muxify/projects.yaml, and initialise a tmux session. The tool
will not start a client, see the tips below.
Error messages are also notoriously poor, and there is little validation of configuration file. E.g. a project name must be a valid tmux session name; but there is no validation of that yet.
You define 3 different concepts
- Project - a larger project you work on.
- Task - a process that needs to run while working on the project. E.g.
- An editor in the terminal
- Development web server
- Compiler running in watch mode, e.g. for TypeScript,
tsc -w - A test runner in watch mode
- A layout
- A configuration for the different tasks, and how they are organised in sessions, windows, and panes.
While learning about tmux, I realised that you can attach to a "command mode"; that can receive events in stdin. This could allow you to make tools that react to, e.g. test-output. This could allow you to have the test runner hidden, but have a desktop notification on
This is an idea that arose when I realised the technical possibility exists. But it is very low priority. But the use case itself is so useful that I want to investigate this when I get further.
This is written in Go
- A modern language with a good development experience, e.g. TDD with reasonably fast feedback.
- The code can be packaged into a compiled binary that can be distributed using native package managers.
This is a simple example configuration file. More windows can easily be created by adding to the list.
projects:
- name: muxify
working_dir: $HOME/src/muxify
tasks:
editor:
commands:
- nvim .
test:
commands:
- gow test
windows:
- name: Editor
layout: horizontal
panes:
- editor
- testThere isn't an official distribution yet, so you need to install from sources. Go makes this easy:
> go install github.com/stroiman/muxifyCurrently, there are no command line options, only the ability to launch a project:
> muxify <project name>This command will create a session, windows, and panes as necessary; but doesn't actually start a tmux client.
The following helper script embeds muxify into a flow with tmux client integration. It will launch a client connected to the session after creating it; or switch active session if executed from within tmux itself.
I call this m - and have manually created it in my search path.
#!/bin/sh
set -xe
muxify $1
if [ -z "$TMUX" ]; then
tmux attach -t $1
else
tmux switch-client -t $1
fiThe system is tested by actually starting a tmux server. The tests starts a new
tmux server, as to not interfere with a normal tmux server (assuming you didn't
launch a server on a socket named muxify-test-socket).
The server is loaded with the tmux.conf file in this project which sets
default-command "/bin/sh" - which should use /bin/sh as the default shell
as a non-login shell, as to not load your own $HOME/.profile.
This should test the system with a minimal configuration, which provides the following benefits
- Starts the tests in a controllable environment, not affected by the user's personal setup.
- A minimal shell profile results in faster startup and execution of the tests.
Creating a new project, and setting up a test runner. The outcome of this session was a simple function to ensure a session with a specific name was started.
Starting the session with a specific working directory, and verifying that the directory is set correctly. But coming to many dead ends trying to optimise how this is tested.
Fixed optimising testing as well as isolate the tests from the user's environment.
Basic control of window configuration, and restore missing windows when re-launching a session, but was left with an erratic test.
Reorganise windows, massive refactoring, and adding support to start know will need to change. Added the ability to start multiple panes.
Create an executable binary that reads configuration from a file, and I am now starting to use the tool.
Footnotes
-
Sessions started with tmuxinator someimes ran into weird states where the same app would be shown in multiple panes, or keyboard input would be directed to multiple shells. I also saw extreme lag with grouped tmux sessions. ↩
