Teamocil Documentation

Teamocil supports standard tmux layout names:

• even-horizontal
• even-vertical
• main-horizontal
• main-vertical
• tiled

You can also use a custom tmux layout string (the format used by tmux list-windows). To get the layout string for your current window, run:

tmux list-windows -F "#{window_active} #{window_layout}" | grep "^1" | cut -d " " -f 2

Then, use that string in your YAML file:

windows:
  - name: sample-two-uneven-panes
    layout: 00c7,158x38,0,0[158x9,0,0,37,158x28,0,10,39]
    panes:
      - echo foo
      - echo bar

To use Teamocil to automate your tmux layouts, follow these steps:

1. Install the Ruby gem:

   gem install teamocil

2. Create the configuration directory:

   mkdir ~/.teamocil

3. Create and edit a new layout file (e.g., sample.yml) using the --edit flag:

   teamocil --edit sample

4. Launch tmux and run your layout:

   tmux
   teamocil sample

# Install the `teamocil` Ruby gem
$ gem install teamocil

# Create your layout directory
$ mkdir ~/.teamocil

# Edit ~/.teamocil/sample.yml
$ teamocil --edit sample

# Launch tmux
$ tmux

# Run your newly-created sample layout
$ teamocil sample

Zsh

Add this to your ~/.zshrc:

compctl -g '~/.teamocil/*(:t:r)' teamocil

Bash

Add this to your ~/.bashrc:

complete -W "$(teamocil --list)" teamocil

Fish

Create ~/.config/fish/completions/teamocil.fish with:

complete -x -c teamocil -a '(teamocil --list)'

To run multiple commands in a single pane, use the commands array instead of a string.

windows:
  - name: sample-three-panes
    root: ~/Code/sample/www
    layout: main-vertical
    panes:
      - vim
      - commands:
        - git pull
        - git status
      - rails server

This example demonstrates a window named sample-two-panes that starts in a specific directory, uses an even-horizontal layout, and runs two different commands in separate panes.

windows:
  - name: sample-two-panes
    root: ~/Code/sample/www
    layout: even-horizontal
    panes:
      - git status
      - rails server

The Teamocil command line interface follows this pattern: teamocil [options] [layout-name]

Global options

• --list: Lists all available layouts stored in ~/.teamocil.

Layout options

• --layout <path>: Use a custom file path to a YAML layout file instead of using a name from ~/.teamocil.
• --here: Uses the current tmux window as the first window in the layout.
• --edit <name>: Opens the specified layout file with your $EDITOR instead of executing it.
• --show <name>: Displays the content of the layout file in the terminal instead of executing it.

$ teamocil [options] [layout-name]

The Teamocil module provides utility methods for interacting with the system and handling errors.

• Teamocil.bail(*args): Prints an error message prefixed with [teamocil error] and exits the process.
• Teamocil.puts(*args): Writes output to STDOUT.
• Teamocil.system(*args): Executes a system command using Kernel.system.
• Teamocil.query_system(command): Executes a command via the tmux binary and returns the output using backticks (e.g., Teamocil.query_system('list-sessions')).
• Teamocil.parse_options!(arguments: nil): Parses command-line arguments using OptionParser and stores the result in Teamocil.options.

You can retrieve a sorted list of all available layout names within a specific directory using Teamocil::Layout.print_available_layouts.

This method:

1. Scans the directory for .yml files.
2. Strips the .yml extension from the filenames.
3. Returns the names in alphabetical order.

It accepts an optional directory argument.

The Teamocil::Layout class manages the lifecycle of a layout file (a .yml file). You can interact with layouts through several primary actions:

• Execute: Runs the commands defined in the layout within a tmux session. If the global debug option is enabled, it prints the shell commands instead of executing them.
• Show: Prints the raw YAML content of the layout to the terminal.
• Edit: Opens the layout file in your default editor (defined by the $EDITOR environment variable, defaulting to vi).

When executing, Teamocil joins commands with ; and prefixes them with tmux to ensure they run within the tmux environment.