Tmex
Lightweight tmux cmd/layout composer · 1 shell script · 0 dependencies exc. tmux
Install / Use
/learn @evnp/TmexREADME
______ __ __ ______ __ __
/\__ _\ /\ \ |\ \ /\ ___\ /\_\_\_\
\/_/\ \/ \ \ \ | \ \ \ \ ___\ \/_/\_\/_
\ \_\ \ \_\ \ \_\ \ \_____\ /\_\/\_\
\/_/ \/_/ \/_/ \/_____/ \/_/\/_/ tmux execute
Contents - Usage | Layout | npm | Install | Tests | License
New in v2 🐣 <br> Multi-window management | Focused-pane control | Multi-digit pane counts | Top-level sizing | Grid sub-layouts
If you'd like to jump straight to installing tmex, please go to the Install section or try one of these:
brew install tmex
# OR
npm install -g tmex
# OR to curl directly, see https://github.com/evnp/tmex#install
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 or --kill set; all other args optional
[-h|--help] [-v|--version]
[-l|--layout] 0-9 [ ] { } . - + layout string, each digit represents number of panes in column
[-f|--focus] 0-9 ············· tmux pane to select by index, must be an integer, positive or negative
[-w|--window] "name" ··········· separate sets of tmex args to start session with multiple tmux windows
[-W|--window-focus] "name" ····· same as above, but focus this window when session begins
[-t|--transpose] ··············· build layout in left-to-right orientation instead of top-to-bottom
[-n|--npm] ····················· if set, prefix each command with "npm run" for package.json scripts
[-p|--print] ··················· emit command as string of tmux args instead of invoking tmux directly
[-d|--detached] ················ invoke tmux with -d (detached session); useful for piping data to tmex
[-r|--reattach] ················ if tmux session already exists, re-attach to it instead of replacing it
[-s|--shellless] ··············· if set, invoke commands directly with tmux instead of running inside shell
[-k|--kill] ···················· kill the current or specified tmux session (all other arguments ignored)
[-q|--quiet] ··················· suppress any stdout and stderr output from tmex (tmex argument errors will still be logged)
[-c|--command] "new-session" ··· tmux command that will be called with constructed arguments; default is "new-session"
[--set-XYZ "value" ] ··········· set tmux option XYZ, eg. "tmex test --set-status=off" -> "tmux -s test ; set status off"
["command 1" "command 2" ...] ·· shell commands to be executed in each pane (num commands cannot exceed total pane count)
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).
If you want to change the widths of columns at the top level of the layout, you'll need to prefix the layout with a set of widths:
tmex your-session-name --layout={152}1[2{13}1]4{4112}
>>>
├─1─┼───────5───────┼──2───┤
┌───┬────┬──────────┬──────┐
│ │ │ │ │
│ │ 1 │ 3 │ 4 │
│ │ │ │ │
│ ├────┴──────────┼──1───┤
│ │ ├──1───┤
│ │ ├──────┤
│ │ │ 2 │
└───┴───────────────┴──────┘
Note that the sublayout [2{13}1] is treated as a single column when sizing is applied, so that set of panes as a whole receives 5 as its width relative to the other columns.
Top-level layout sizing (new in v2 🐣)
Since a sizing clause like {123} always follows a pane count number within a layout, you may be wondering how sizing could be applied to the "top level" columns (or rows) of a layout. For example, given the layout 234, how could you:
- make the first column
2fill half the screen - make the second column
3fill a third of the screen - make the third column
4fill the remainder (one sixth) of the screen
This special case is handled by placing the sizing clause at the start of the layout (prior to v2, this would result in an invalid layout error):
tmex your-session-name --layout={321}234
>>>
┌───────────────┬──────────┬─────┐
│ │ │ 4 │
│ │ 3 │ │
│ 2 │
