Skip to main content

smux

The minimal tmux launcher, with the fewest options to set and the fastest ramp-up time. This project is on Github and on PyPi (this README is shared).

Originally created as a tool to make it easier to reproduce (and interactively debug) distributed systems bugs that required sshing into a lot of servers and starting processes, smux is a general purpose tmux launcher whose input resembles in all respects a concatenation of bash scripts to be run on each terminal.

In addition to being able to send literal commands to tmux windows, smux offers a variety of special #smux directives useable in its input files that make it easy to do certain expect-esque tasks inside tmux, such as waiting for prompts, pasting buffers, and executing arbitrary shell commmands internally (for example, to wait for user input before proceeding to send more commands to various panes). See #smux directives in the documentation for details.

See the samples directory for example smux scripts.

Why write another tmux launcher?

tmuxp and tmuxinator are powerful tmux session management systems that already exist, so why create another one? The big reasons are the ergonomics and ease of learning that arises from a flat input file format and extremely few options.

Consider smux if one of the following is true of your use case:

  1. You want to write commands exactly the same way you write a bash script. You just want your commands to execute in different tmux panes. You have neither time nor desire to learn a custom input format and understand a large number of options.
  2. You do not care about "managing" sessions, and just want to automate pane creation.
  3. You want scripts that you can directly copy-and-paste commands out of when you need to run commands manually.
  4. You want to leverage #smux directives for convenient access to tmux buffers and waiting for input.
  5. You want to embed a tmux launcher into another Python script that generate commands to run, without having to fit those other scripts into someone else's framework. This can be done with a single call to smux.create.

Demo (Click to View)

Writing and running a simple smux script in under 60 seconds.

asciicast

Expect-like features with #smux directives, such as waiting for input before sending specific keystrokes.

asciicast

Dependencies

  • Python 3.8+
  • tmux (any version)

Installation

Manual Method:

git clone https://github.com/hq6/smux.git
# Add the directory to your PATH

Automatic Method:

pip3 install smux.py

Usage (as a command line tool)

  1. Create a new file, either from scratch or by copying Sample.smux.

  2. (Optional) Specify desired options described in help(smux).

  3. For every pane you want to launch, write an entry of the following form.

    ---------
    command1
    command2
    command3
    

    Note that a pane does not necessary need to run any commands.

    Note further that it is not uncommon for the first command in a pane to be ssh ... and then the subsequent commands the ones to be run on the rmeote server.

  4. smux.py <input_file_name>

Usage (as a library)

import smux

smux.create(numPerWindow,
        [["command1_for_pane1", "command2_for_pane1"],
         ["command1_for_pane2", "command2_for_pane2"],
         ...
         ])

Metadata

Release files for smux.py 0.1.21

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for smux.py 0.1.21
File Size Uploaded Provenance Actions
smux.py-0.1.21.tar.gz 12.3 kB Without provenance Details for smux.py-0.1.21.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for smux.py 0.1.21
File Interpreter ABI Platform Actions
smux.py-0.1.21-py3-none-any.whl Python 3 none any Details for smux.py-0.1.21-py3-none-any.whl

Total release size: 31.6 kB

Release files / smux.py-0.1.21.tar.gz

Download URL smux.py-0.1.21.tar.gz
Size 12.3 kB
Tags Source
SHA-256 checksum
How to use checksums
50b00b7f09249bdc0bbfa58240a1cdd417553e6b798d43678c66dba103ff84c6
BLAKE2b-256 checksum
How to use checksums
726562905eb0a839392cef5d16642d497dde0d4d7a6861d8991a4c7f161a4db1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.0.0 CPython/3.8.10

Release files / smux.py-0.1.21-py3-none-any.whl

Download URL smux.py-0.1.21-py3-none-any.whl
Size 19.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
51cf2d74b9fc1a667749fca0ce4cf4be09220a0c7b92301c21798cd0cbfec2cc
BLAKE2b-256 checksum
How to use checksums
c6ebaa703693aded771aac9846d7c7b60ac8f4c6595cb1a1716d1f84a706864b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.0.0 CPython/3.8.10

Security for smux.py 0.1.21

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page