Automux is a highly configurable Tmux automator inspired from similar projects like Teamocil & Tmuxinator. It provides more advanced configuration options like getopts integration, custom indexes and recipes while keeping a strong focus on well designed, easily extendable code base.

Setup

Run these commands to get Automux started. Its easier to look at the different options later.

$ gem install automux
$ automux setup
$ automux

This should open 3 windows with 3 panes in the first window.

Blueprints & Recipes

The yaml configuration files are called blueprints while a logic to translate it into a shell script is called a recipe. Automux can be used with different combinations of blueprints and recipes.

Session, Windows and Panes

Automux stays true to tmux conventions for session, windows and panes. The first blueprint indentation level is for the session. Session can have many Windows all listed under the key windows.

windows is an array of hashes. Just as in Tmux convention a window has atleast one pane, each hash should atleast have a blank panes key defined.

name: test
windows:
  - name: blank
  - panes:

The above blueprint will ask automux to create two shell windows with the first one named as blank.

Session Options

name: helps to identify your session when tmux ls is run. Its the only field thats compulsory.

root: automux will cd to this path before starting tmux.

windows: an array of windows. A tmux session can be started with no windows defined.

flags: session specific flags as given in the tmux man page.

options: translates each key-value pair into set-option. See man tmux for the list of available options.

hooks: is an hash with pre and post keys. The specified commands are run before starting and attaching session respectively.

Window Options

name: optional name field.

layout: layout can be one of the preset layouts(even-horizontal, even-vertical, main-horizontal, main-vertical, or tiled) or a custom defined value.

root: automux will cd to this path before running the adding the pane.

panes: is an array of commands for each pane in this window.

options: translates each key-value pair into set-window-option. See man tmux for the list of available options.

hooks: is an hash with pre and post keys. The specified commands are run before and after adding the panes respectively.

index: index for the window.

opt: makes the window optional. The window will not be created if the flag is not passed.

Default Blueprint

By default, automux uses the blueprint located at $HOME/.automux/blueprints/default.yml, which was copied during automux setup.

name: test
root: ~/
flags: -u2
options:
  status-left: '#S>'
hooks:
  pre: echo 'Starting session'
windows:
  - name: panes
    layout: tiled
    panes:
      - irb
      - top
      - ls
  - name: vim
    hooks:
      pre:
        - echo 'Starting vim'
    panes: vim
  - name: custom-indexed-window
    index: 1
    hooks:
      post:
        - echo 'Running <%= name %>'
  - name: optional-window
    opt: '-r'
    panes:
      - echo 'Created optional window'
    options:
      automatic-rename: off
      window-status-bg: black

When an argument is passed, Automux will look for a blueprint with the specified name. For e.g., the following command will look for custom.yml under $HOME/.automux/blueprints

$ automux custom

The default blueprint can be changed to suit your needs. To get the original default blueprint back, run automux setup again.

Managing Blueprints

If $EDITOR is undefined, vi will be used to open the blueprint.

Create

$ automux blueprint create custom

This will clone the default.yml as custom.yml and open it in an editor.

Edit

$ automux blueprint edit custom

Delete

$ automux blueprint delete custom

aliased to rm

Copy

$ automux blueprint copy default custom

aliased to cp

List

$ automux blueprint list

aliased to index

Command-line options

Automux can understand command-line options to make windows optional or provide input at runtime. Lets look at some examples.

name: test
root: '-r:'
windows:
  - name: top
    opt: "-t"
    panes: top

automux test will start Tmux with a window containing shell.

automux test -t will start Tmux with a window containing top.

automux test -tr projects will cd into the projects folder and then launch top.

The option can also be specified inside another command. This can be useful in cases like providing a branch name for a git pull at runtime:

name: test
windows:
  - name: git
    panes: git pull origin '-r:'

Dynamic root values using opts.

root defaults to the current directory. One may use an opt to achieve dynamic assignment.

name: test
root: '-r:'
windows:
  - panes: pwd

automux test -r projects will change the directory to projects before starting Tmux.

automux test will use the current directory.

automux test -h will list the valid options.

Note

• Since the opts are derived from the blueprint, the blueprint name needs to precede the opts as seen in the above commands.
• The option needs to be surounded by quotes. It makes Automux's job easier.

Custom defined window indexes

Windows can have custom indexes which will be assigned to them at runtime. Lets look at an example.

name: test
windows:
  - name: third
    panes: ls
  - name: fourth
    panes: htop
  - name: second
    index: 1
    panes: pwd
  - name: first
    index: 0
    panes: [pwd, echo Hello]

Here the windows will be arranged in the order indicated by their names.

Base Index

As Automux tries to assign window indexes beforehand, it will overwrite any global base-index setting. To use a base-index, one would need to let Automux know about it like so:

name: test
options:
  base-index: 2
windows:
  - panes: pwd
  - panes: ls
    index: 9

Here the indexing will start from 2 onwards.

The Automux Way

What would Tmux do?

Automux is built on top of an ruby API for Tmux. Instead of providing a custom key for every possible Tmux option, its approach is to provide direct access to the session/window objects. This gives way for higher levels of customizations like allowing end users to add their own session/window methods and using them in the blueprints or letting them define their own recipes for logic. The following sections will look at some these approaches.

Hooks with ERB

Automux provides context specific ERB support for hooks.

name: projects
hooks:
  pre: cd ~/<%= name %>
windows:
  - name: automux
    hooks:
      pre:
       - cd <%= name %>
       - pwd
    panes: vim
  - panes: pwd

This will execute the following steps

• cd ~/projects
• ... tmux startup stuff
• ... create first window
• cd automux
• pwd #=> ~/projects/automux
• vim
• ... create second window
• pwd #=> ~/projects

The session/window hooks have access to session and window objects respectively.

Select/Focus Window

To select a specific window when session is attached, Tmux provides the method select-window. Staying true to Tmux conventions, Automux's session object provides select_window.

name: hooked
hooks:
  post:
    - <%= select_window 'one' %>
windows:
  - name: one
  - name: two

This selects the window named 'one' after all windows have been setup. Index number is also an acceptable parameter.

Link Window

Tmux exposes the link-window method to link an existing window with current session.

name: test
hooks:
  post:
    - <%= link_window('primary', 'irb', 3)%>
windows:
  - panes: vim

This will link a window named irb from an existing session named primary as 3rd window in current session. The third parameter is optional just like Tmux would do.

Writing your own Recipe

• automux setup copies a sample of the default recipe to $HOME/recipes/default.sh.erb. It looks like the following script:

cd <%= root %>

= start_server
= new_session

- windows.each do |window|
  = new_window(window)
  = rename_window(window) if window.name

  - if window.has_panes?
    - window.panes.each do |pane|
      = split_window if pane.index > 0
      = send_keys(window, pane.command)
    - end
  - end
- end

= attach_session

Its a simpler form of ERB, much like HAML without indentation sensitivity. The ERB is evaluated with session's context. Hence all methods defined for session are available here. Custom recipes can be run like so:

$ automux default custom_recipe

Where default is the default blueprint name.

• Note: The default recipe comes from the Gem and cannot be overwritten. Running automux default default will invoke the recipe defined in the Gem instead of any user defined default. The primary reason for this approach is not the burden end users with the necessity to update their default recipe in future releases.

Bash Autocompletion

Currently blueprint names can be autocompleted. A dedicated autocompletion shell script is in the pipeline. For now add the following to your ~/.bashrc to get autocompletion for blueprint names.

complete -W "$(automux blueprint list)" automux

Coming Up

• Bash Autocompletion for blueprint commands and recipe names.
• Make Session and Window extendable on the client end.
• Blueprint inheritance.

License

MIT License. See LICENSE.txt for more details.