remi/teamocil

There's no I in Teamocil. At least not where you think. Teamocil is a simple tool used to automatically create windows and panes in tmux with YAML files.

Source code at GitHub https://github.com/remi/teamocil

{
  "createdAt": "2011-02-05T18:09:52Z",
  "defaultBranch": "master",
  "description": "There's no I in Teamocil. At least not where you think. Teamocil is a simple tool used to automatically create windows and panes in tmux with YAML files.",
  "fullName": "remi/teamocil",
  "homepage": "",
  "language": "Ruby",
  "name": "teamocil",
  "pushedAt": "2021-03-10T12:26:11Z",
  "stargazersCount": 2394,
  "topics": [
    "tmux"
  ],
  "updatedAt": "2025-10-29T14:57:43Z",
  "url": "https://github.com/remi/teamocil"
}

Teamocil is a simple tool used to automatically create
windows and panes in tmux with YAML files.

Installation

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

# Create your layout directory
$ mkdir ~/.teamocil

# Edit ~/.teamocil/sample.yml (look for sample layouts in this very `README.md`)
$ teamocil --edit sample

# Launch tmux
$ tmux

# Run your newly-created sample layout
$ teamocil sample

Usage

$ teamocil [options] [layout-name]

Global options

Option	Description
`--list`	Lists all available layouts in `~/.teamocil`

Layout options

Option	Description
`--layout`	Takes a custom file path to a YAML layout file instead of `[layout-name]`
`--here`	Uses the current window as the layout’s first window
`--edit`	Opens the layout file with `$EDITOR` instead of executing it
`--show`	Shows the layout content instead of executing it

Upgrading

Teamocil 1.0 is a complete rewrite (from scratch!) of Teamocil. The code is now very much simpler, cleaner and easier to maintain.

The downside of that is that several features were dropped during the rewrite process, mostly because I didn’t actually use/need them and I got tired of maintaining features I don’t think are useful.

You might have to clean up your layout files after upgrading to 1.0. I’m sorry about that. The documentation in README.md should help you find which keys are now supported.

The 0.4-stable branch is still available with the old code. Feel free to fork the repository and add back as many features as you want :)

Configuration

Session

Key	Description
`name`	The tmux session name
`windows`	An `Array` of windows

Windows

Key	Description
`name`	The tmux window name (required)
`root`	The path where all panes in the window will be started
`layout`	The layout that will be set after all panes are created by Teamocil
`panes`	An `Array` of panes
`focus`	If set to `true`, the window will be selected after the layout has been executed
`options`	A `Hash` of options that will be set with the `set-window-option` command

Panes

A pane can either be a String or a Hash. If it’s a String, Teamocil will treat it as a single-command pane.

Key	Description
`commands`	An `Array` of commands that will be ran when the pane is created
`focus`	If set to `true`, the pane will be selected after the layout has been executed

Examples

Simple two pane window

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

.------------------.------------------.
| (0)              | (1)              |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
'------------------'------------------'

Simple three pane window

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

.------------------.------------------.
| (0)              | (1)              |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |------------------|
|                  | (2)              |
|                  |                  |
|                  |                  |
|                  |                  |
'------------------'------------------'

Simple four pane window

windows:
  - name: sample-four-panes
    root: ~/Code/sample/www
    layout: tiled
    panes:
      - vim
      - foreman start web
      - git status
      - foreman start worker

.------------------.------------------.
| (0)              | (1)              |
|                  |                  |
|                  |                  |
|                  |                  |
|------------------|------------------|
| (2)              | (3)              |
|                  |                  |
|                  |                  |
|                  |                  |
'------------------'------------------'

Two pane window with focus in second pane

windows:
  - name: sample-two-panes
    root: ~/Code/sample/www
    layout: even-horizontal
    panes:
      - rails server
      - commands:
          - rails console
        focus: true

.------------------.------------------.
| (0)              | (1) <focus here> |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
'------------------'------------------'

Extras

Zsh autocompletion

To get autocompletion when typing teamocil <Tab> in a zsh session, add this line to your ~/.zshrc file:

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

zsh-completions also provides additional completion definitions for Teamocil.

Bash autocompletion

To get autocompletion when typing teamocil <Tab> in a bash session, add this line to your ~/.bashrc file:

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

Fish autocompletion

To get autocompletion when typing teamocil <Tab> in a fish session, add the following file ~/.config/fish/completions/teamocil.fish with the following content:

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

Custom window layout

Teamocil supports all the window layout names supported by tmux.

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

However, it also supports the custom format understood by tmux. This is especially useful if you want to manually resize your panes and keep using that layout in the future.

You can grab the layout for the current window by running this command:

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

You can then use the result as the layout key for any Teamocil window object.

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

Contributors

Feel free to contribute and submit issues/pull requests on GitHub, just like these fine folks did: