tmex

A minimalist tmux layout manager - one shell script + tmux + zero other dependencies

 ______   __    __    ______    __  __
/\__  _\ /\ \  |\ \  /\  ___\  /\_\_\_\
\/_/\ \/ \ \ \ | \ \ \ \  ___\ \/_/\_\/_
   \ \_\  \ \_\ \ \_\ \ \_____\  /\_\/\_\
    \/_/   \/_/  \/_/  \/_____/  \/_/\/_/  tmux execute

Contents - Usage | Layout | npm | Install | Tests | License

Create a dashboard for your project with one command. No messing with configuration files. Just the full power of tmux, plus an easy-yet-flexible layout system:

tmex -n test lint "npm install"

Tailor-made for simplifying unwieldy package.json scripts (though tmex works just as well with any arbitrary commands):

package.json
{
  "name": "special-project"
  "scripts": {
    "watch": "parcel index.html",
    "server": "python -m http.server",
    "typecheck" "tsc --watch --noEmit",
-   "start": "tmux new-session -s $npm_package_name 'npm run watch' \\; split-window 'npm run server' \\; split-window 'npm run typecheck'"
+   "start": ✨"tmex -n watch server typecheck"✨
  }
}

With tmex, npm run start composes watch, server, and typecheck into a single view with ease:

┌───────────┬───────────┐
│ npm run   │ npm run   │
│ watch     │ server    │
│           ├───────────┤
│           │ npm run   │
│           │ typecheck │
└───────────┴───────────┘
session : special-project

Sane defaults. Layouts with any number of panes. Given 8 commands, tmex generates:

┌───────┬───────┬───────┐
│ cmd 1 │ cmd 3 │ cmd 6 │
│       ├───────┼───────┤
├───────┤ cmd 4 │ cmd 7 │
│ cmd 2 ├───────┼───────┤
│       │ cmd 5 │ cmd 8 │
└───────┴───────┴───────┘

Usage

tmex your-session-name "cmd a" "cmd b" "cmd c" ... etc.

With options and custom layout provided:

tmex your-session-name --npm --layout=1224 --transpose "cmd a" "cmd b" "cmd c" ... etc.

Shorthand:

tmex your-session-name -nt 1224 "cmd a" "cmd b" "cmd c" ... etc.
                        │     │              │
              options ──┘     └── layout     └── shell commands

Session name optional if --npm or -n is set (will default to package name, details below):

tmex -nt 1224 "cmd a" "cmd b" "cmd c" ... etc.

Full options list (also accessible via tmex -h):

tmex <session-name>                - session name required unless --npm set; all other args optional
  [-h|--help]
  [-v|--version]
  [[-l|--layout] <1-9,[,],{,}>]    -l, --layout      layout string, each digit represents number of panes in column
  [-t|--transpose]                 -t, --transpose   build layout in left-to-right orientation instead of top-to-bottom
  [-n|--npm]                       -n, --npm         if set, prefix each command with "npm run" for package.json scripts
  [-p|--print]                     -p, --print       emit command as string of tmux args instead of invoking tmux directly
  [-d|--detached]                  -d, --detached    invoke tmux with -d (detached session); useful for piping data to tmex
  [-r|--reattach]                  -r, --reattach    if tmux session already exists, re-attach to it instead of replacing it
  [-s|--shellless]                 -s, --shellless   if set, invoke commands directly with tmux instead of running inside shell
  ["shell command 1"]
  ["shell command 2"]              - shell commands that will be executed in each pane
  ...                                number of shell commands N must not exceed sum of layout
  ["shell command N"]

Layout

If no layout is provided, a sensible default will be generated to match the number of commands provided. However, layouts are fully customizable via --layout or -l (or as shorthand, the first argument after session name if it is a valid layout):

tmex your-session-name 1224
# or
tmex your-session-name -l 1224
# or
tmex your-session-name --layout=1224
>>>                             │
   1─────2─────2─────4──────────┘
┌─────┬─────┬─────┬─────┐
│     │     │     │  f  │
│     │  b  │  d  ├─────┤
│     │     │     │  g  │
│  a  ├─────┼─────┼─────┤
│     │     │     │  h  │
│     │  c  │  e  ├─────┤
│     │     │     │  i  │
└─────┴─────┴─────┴─────┘

Each digit of 1224 specifies the number of panes each column will be split into. To operate on rows instead of columns, transpose layout left-to-right instead of top-to-bottom with --transpose or -t:

tmex your-session-name --transpose --layout=1224
>>>                                         │
┌───────────────────────┐                   │
│           a           │ 1─────────────────┘
├───────────┬───────────┤ │
│     b     │     c     │ 2
├───────────┼───────────┤ │
│     d     │     e     │ 2
├─────┬─────┼─────┬─────┤ │
│  f  │  g  │  h  │  i  │ 4
└─────┴─────┴─────┴─────┘

Layouts may be arbitrarily complex via sublayouts [xyz] and custom sizing {xyz}:

tmex your-session-name --layout=1[2{13}1]4{4112}
>>>                                 │      │
         ┌──────────────────────────┘      │
┌─────┬──│────────┬─────┐                  │
│     │  │        │     │                  │
│     │ 1│3       │  4─────────────────────┘
│     │  │        │  │  │
│     ├──┴────────┼──1──┤
│     │           ├──1──┤
│     │           ├──│──┤
│     │           │  2  │
└─────┴───────────┴─────┘

In the example above, the layout 1[2{13}1]4{4112} contains the sublayout 2{13}1 which is constructed in the second column of the full layout. This in turn specifies relative sizing 2{13} for its first 2 panes, meaning the 2nd pane will be 3x the size of the 1st (denoted by 1, 3 in the diagram above). The 3rd column of the full layout 4{4112} also defines custom sizing of panes (denoted by 4, 1, 1, 2 in the diagram above).

npm

Simplify package.json scripts via --npm or -n. Commands will be prefixed with npm run (if necessary) and session name will default to $npm_package_name. This will expand to match the name field set in package.json.

NOTE: tmux replaces .→_, :→_, \→\\ when setting session names, so your final session name may not exactly match the name specified in package.json (or the name you provide via the <session-name> argument at the command line).

cat package.json | grep name
>>> "name": "special-project"

tmex -n watch server typecheck
>>>
┌───────────┬───────────┐
│ npm run   │ npm run   │
│ watch     │ server    │
│           ├───────────┤
│           │ npm run   │
│           │ typecheck │
└───────────┴───────────┘
session : special-project

Install

Install as a build tool in a package:

npm install --save-dev tmex

Install globally for use with any set of package.json scripts or arbitrary commands:

npm install -g tmex

or sans-npm:

curl -o ~/bin/tmex https://raw.githubusercontent.com/evnp/tmex/master/tmex && chmod +x ~/bin/tmex
# or /usr/local/bin or other bin of your choice (as long it's in your $PATH)

tmex has no external dependencies other than tmux, but always read code before downloading to ensure it contains nothing unexpected.

tmex doesn't install tmux itself, so you'll also want to do that if you don't have tmux yet:

tmex -n test lint "npm install"
/Users/evan/bin/tmex: line 694: tmux: command not found

brew install tmux      # OSX
sudo apt install tmux  # Ubuntu, Debian

or refer to https://github.com/tmux/tmux/wiki/Installing for install instructions applicable to your platform.

Tests

Run once:

npm install
npm test

Use fswatch to re-run tests on file changes:

brew install fswatch
npm install
npm run testw

Non-OSX: replace brew install fswatch with package manager of choice (see fswatch docs)

License

MIT