stmux: a small terminal multiplexer that runs your npm scripts side by side

A tiny subset of tmux, aimed at npm script workflows

stmux is a simple terminal multiplexing utility for Node.js environments, and the README is upfront about what it is and is not.

It is inspired by the awesome and unreachable tmux native Unix utility, and it is intended to provide just a very tiny subset of the original tmux functionality, but in a portable way for bare Node.js environments and with some special features for application build environments.

So it is not a tmux replacement. There is no session persistence, no detach and attach, no server, no config file, no scripting, no copy mode. What it does is take a set of commands and run them side by side in split panes within one terminal window, and that is the entire scope.

The three special features for build environments are the reason to use it rather than tmux, and they are named in the Abstract. There is a build-time error detection and notification feature, it can automatically restart terminated commands, and it can automatically close or wait after all spawned commands have successfully or unsuccessfully terminated.

That last one is the most interesting, because it solves a problem that tmux does not. When you run a frontend build and a backend build in two panes, the failure case is a terminal that sits there with a red error while you have no idea whether the other build is still going. stmux can watch for the error, notify you, and then either exit or wait depending on configuration, which means the command returns a meaningful exit status instead of leaving a half-dead multiplexer on your screen.

Internally the tool is built on the Blessed screen rendering environment and emulates full XTerm compatible pseudo terminals to the spawned programs, using the author's own blessed-xterm wrapper around XTerm.js for the terminal rendering and node-pty for the pseudo-terminal integration.

The primary language is TypeScript, the licence field in the package manifest is MIT with the author listed as Dr. Ralf S. Engelschall, and the homepage for the package is npmjs.com/stmux. The last push was on 2026-07-19 and there are no GitHub releases, while the manifest version is 2.1.1.

The command spec is a small language of its own

The example command in the README shows the shape of the specification argument.

$ stmux -- [ [ -s 1/3 bash .. vim ] : mc ]

The structure after the double dash is a list of panes, separated by a colon, with each pane described by a set of options and a command. The -s 1/3 is a size, splitting the pane to a third, and the dot-dot separates the two commands that share the pane, so bash and vim run in the same region while mc gets the remaining space.

The full option list is given in the Usage section, and running the tool with -h prints it.

$ stmux -h

The global options are where the build-oriented behaviour lives. The -w or --wait option waits after the last finished command and does not shut down automatically, either if any command terminated with an error or just always. The -e or --error option takes a comma separated list of regular expressions that have to match on a single line, and a regular expression prefixed with ! is required not to match. The default is (?:ERROR|Error|error), which is a deliberately broad default for build output.

The -m or --method option then decides what happens when an error is detected: a comma separated list of methods to perform user notification, with the default being no extra notification beyond the terminal annotation. The possible methods are beep and system, the latter meaning a desktop notification.

That combination is the feature in one line of configuration. A build error is detected by matching the output against a regular expression, and the person at the keyboard is told with a beep or a system notification rather than by noticing a pane.

The other options are more conventional. The -a or --activator sets the CTRL prefix character for special commands and has to be a single lowercase letter, defaulting to a, which means opening the help popup is CTRL+a released and then ? pressed. The -t option sets the terminal title, default stmux. The -c option sets the cursor type to block, underline or line. The -n option shows a terminal number and focus indicator in the title. The -M option enables mouse event handling, which gives left-click focus switching, wheel scrolling and mouse events sent to the terminal as key sequences. And -U enables full Unicode handling in the screen rendering, which correctly displays East Asian characters, something that a plain terminal grid gets wrong.

The package.json integration is the intended way to use it

The Intention section is explicit that this utility is primarily intended to be used from within a package.json script to easily side-by-side run various NPM-based commands in a Node.js build-time environment.

The example shows the full shape of that: a top-level project with a ui and an sv sub-project, where the dev script runs the frontend build in watch mode and the backend in watch mode side by side, and the start command in a third pane.

    "dev":        "stmux -w always -e ERROR -m beep,system -- [ [ \"npm run dev:ui\" .. \"npm run dev:sv\" ] : -s 1/3 -f \"npm start\" ]",

Read that line carefully, because it shows the three features working together. The -w always means stmux waits after the last command finishes instead of exiting, so your dev session stays up. The -e ERROR narrows the error pattern from the default of three case variants to one. The -m beep,system means an error produces both a terminal beep and a desktop notification. And the -f points the third pane at the npm start command, which is the run-time of the backend server project.

The layout is the split notation: the first pane is divided with -s 1/3 between the UI and SV watch commands, and the second pane is the server run time.

So the intended workflow is that npm run dev gives you a frontend build, a backend build and a running server, in one terminal, and if either build breaks you get told rather than having to look.

The package.json snippet in the README also shows the shape of the script set: install, build, start and clean, each of which fans out into per-project variants with a cd into the sub-directory, and then the dev script that ties them together through stmux.

The dependency entry in that example is a wildcard version, "stmux": "*", which is worth noting for anyone copying it into a real project. A wildcard range on a tool that changes behaviour between versions is not something you would normally want in a committed package.json.

Installing means a working C toolchain, and that is the real dependency

The install itself is one command.

$ npm install -g stmux

What follows it in the README is the important part for anyone deploying this. The dependencies of stmux transitively include node-pty, which must be built with node-gyp during npm install, and you need to provide the necessary C and C++ compiler environment on your operating system.

The per-platform guidance is where the practical detail sits.

On macOS, install the Command Line Tools under Preferences then Downloads in Xcode.

On Windows, open an elevated cmd.exe and run the commands npm install --global windows-build-tools and npm config set msvs_version 2015 --global. The msvs_version 2015 setting is a specific pin, and it is the kind of thing that will need revisiting when the toolchain moves on.

On the Windows Subsystem for Linux with an Ubuntu distribution, run sudo apt-get update and sudo apt-get install -y python make build-essential. The python package is needed because node-gyp runs on Python.

And under Linux or FreeBSD you usually do not have to do anything.

So a plain npm install of a JavaScript tool turns into a native compilation step on three of the four platforms, which is the main operational difference from what people expect of an npm package. In a CI container built on alpine or a slim image, node-pty compilation is a step you will have to add.

The build itself is driven from the repository rather than from npm scripts, and the Makefile shows a project with its own toolchain.

build: bootstrap
	@$(STX) -v4 -c etc/stx.conf build

The build and clean and distclean and test targets all delegate to stx, the author's own build tool, with a configuration file at etc/stx.conf. The bootstrap target installs stx itself if it is not already present in node_modules. The Makefile also carries the full MIT permission notice for the project, copyright 2017-2026.

Where stmux is the wrong tool

The first wrong-tool case is someone who wants a session manager rather than a pane runner. The README describes stmux as a very tiny subset of tmux functionality, and that is not a marketing hedge. There is no detach, no reattach, no named sessions, no configuration file, no copy mode, no plugins, no scripting. If your requirement is to close a terminal window and come back to your running processes, tmux or zellij or screen is the tool, and stmux is not a reduced version of them.

The second case is a team that wants to run a long-lived development environment across a reboot, or a remote session over SSH that survives a dropped connection. stmux draws its panes in a terminal it owns; there is no server and no state outside the process, so killing the terminal kills the children.

The third case is a project whose build output does not match the error patterns. The detection works by matching regular expressions against terminal lines, and the default is (?:ERROR|Error|error). A build system that reports failures as FAIL, FAILED, a non-zero exit with no matching word, or a stack trace with no word resembling error will not trigger the notification. The -e option fixes that, but it means the tool only works if your build tool says the word error somewhere, and for a tool that reports failures some other way you are back to watching panes yourself.

There is a related subtlety. The regular expressions have to match on a single line, and the detection is over what appears in the terminal, which is the program's output after the terminal has interpreted it. A build tool that writes progress with carriage returns, that colours its output, or that wraps long lines will have its output shaped before the match runs.

The fourth case is a platform without a compiler. The dependency on node-pty is not optional, so every machine that installs stmux needs a native build. That excludes some minimal container images and some locked-down developer environments until the base image is extended.

On the packaging side, the manifest version is 2.1.1 while the release list is empty, and the licence field in the repository metadata is reported as unknown even though the manifest says MIT and the Makefile carries the full MIT text. Any distribution decision should be based on the LICENSE file and the in-repo notice rather than the GitHub metadata field.

What you get in exchange is a small tool with one clear job, and a specific answer to a problem npm scripts have had for years. Running a frontend watch build and a backend watch build in one terminal with a real split pane, and being told when either breaks, is a genuine improvement over running them in two background tabs. The automatic restart of terminated commands covers the common case where a watch build crashes and needs restarting, and the -w and -m options together mean the npm script can return a meaningful exit status rather than hanging.

Editorial conclusion

stmux suits a team that runs a frontend and a backend build side by side during development and wants the terminal itself to notice when one of them fails, since the error detection and notification feature is the part tmux does not provide. It does not suit someone who wants a general purpose session manager, since the README describes it as a very tiny subset of tmux functionality. Before adopting, check that node-pty can be compiled on your machines, because the transitive dependency has to be built with node-gyp and needs a C and C++ toolchain on Windows and macOS.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. rse/stmux on GitHub