tmux workspace manager, forged in Ruby.

Session manager for tmux. Load tmux sessions through YAML/JSON configuration files. Powered by libtmux for Ruby.

Explore tmux layout / workspace possibilities

Preset

session_name: shorthands
windows:
  - window_name: long form
    panes:
      - shell_command:
          - echo 'did you know'
          - echo 'you can inline'
      - shell_command: echo 'single commands'
      - echo 'for panes'

{
  "session_name": "shorthands",
  "windows": [
    {
      "window_name": "long form",
      "panes": [
        {
          "shell_command": [
            "echo 'did you know'",
            "echo 'you can inline'"
          ]
        },
        {
          "shell_command": "echo 'single commands'"
        },
        "echo 'for panes'"
      ]
    }
  ]
}

no layout set

session_name: 2-pane-vertical
windows:
  - window_name: my test window
    panes:
      - echo hello
      - echo hello

{
  "session_name": "2-pane-vertical",
  "windows": [
    {
      "window_name": "my test window",
      "panes": [
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

no layout set

session_name: 3-panes
windows:
  - window_name: dev window
    layout: main-vertical
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo hello
      - echo hello

{
  "session_name": "3-panes",
  "windows": [
    {
      "window_name": "dev window",
      "layout": "main-vertical",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep \\.log"
          ]
        },
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

layout main-vertical

session_name: 4-pane-split
windows:
  - window_name: dev window
    layout: tiled
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo hello
      - echo hello
      - echo hello

{
  "session_name": "4-pane-split",
  "windows": [
    {
      "window_name": "dev window",
      "layout": "tiled",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep \\.log"
          ]
        },
        "echo hello",
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

layout tiled

session_name: work
environment:
  PROJECT_MODE: development
windows:
  - window_name: editor
    window_index: 1
    layout: tiled
    panes:
      - shell_command: printf 'editor ready\n'
      - {}

{
  "session_name": "work",
  "environment": {
    "PROJECT_MODE": "development"
  },
  "windows": [
    {
      "window_name": "editor",
      "window_index": 1,
      "layout": "tiled",
      "panes": [
        {
          "shell_command": "printf 'editor ready\\n'"
        },
        {}
      ]
    }
  ]
}

layout tiled

session_name: Environment variables test
environment:
  EDITOR: /usr/bin/vim
  DJANGO_SETTINGS_MODULE: my_app.settings.local
  SERVER_PORT: "8009"
windows:
  - window_name: Django project
    panes:
      - ./manage.py runserver 0.0.0.0:${SERVER_PORT}
  - window_name: Another Django project
    environment:
      DJANGO_SETTINGS_MODULE: my_app.settings.local
      SERVER_PORT: "8010"
    panes:
      - ./manage.py runserver 0.0.0.0:${SERVER_PORT}
      - environment:
          DJANGO_SETTINGS_MODULE: my_app.settings.local-testing
          SERVER_PORT: "8011"
        shell_command: ./manage.py runserver 0.0.0.0:${SERVER_PORT}

{
  "session_name": "Environment variables test",
  "environment": {
    "EDITOR": "/usr/bin/vim",
    "DJANGO_SETTINGS_MODULE": "my_app.settings.local",
    "SERVER_PORT": "8009"
  },
  "windows": [
    {
      "window_name": "Django project",
      "panes": [
        "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
      ]
    },
    {
      "window_name": "Another Django project",
      "environment": {
        "DJANGO_SETTINGS_MODULE": "my_app.settings.local",
        "SERVER_PORT": "8010"
      },
      "panes": [
        "./manage.py runserver 0.0.0.0:${SERVER_PORT}",
        {
          "environment": {
            "DJANGO_SETTINGS_MODULE": "my_app.settings.local-testing",
            "SERVER_PORT": "8011"
          },
          "shell_command": "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
        }
      ]
    }
  ]
}

no layout set

session_name: Window index example
windows:
  - window_name: zero
    panes:
      - echo "this window's index will be zero"
  - window_name: five
    panes:
      - echo "this window's index will be five"
    window_index: 5
  - window_name: one
    panes:
      - echo "this window's index will be one"

{
  "session_name": "Window index example",
  "windows": [
    {
      "window_name": "zero",
      "panes": [
        "echo \"this window's index will be zero\""
      ]
    },
    {
      "window_name": "five",
      "panes": [
        "echo \"this window's index will be five\""
      ],
      "window_index": 5
    },
    {
      "window_name": "one",
      "panes": [
        "echo \"this window's index will be one\""
      ]
    }
  ]
}

no layout set

Install

Install the workspace package separately from the core library.

$ gem install libtmux-workspace

gem "libtmux-workspace"

libtmux-workspace parses bounded YAML or JSON into an immutable creation plan. validate and offline plan do not contact tmux. load and plan --live borrow an existing server selected with --socket.

The manager creates a new session. It does not reconcile, replace, or delete a preexisting workspace. Applying a plan authorizes declared shell commands; their delivery does not prove that the pane programs completed.

Start here¶

Guides covers validate, plan, and load.
Topics explains the supported format and creation-only model.
Examples provides a bounded YAML configuration.
CLI Manual documents commands, flags, output and exit statuses.
Language API documents the workspace gem.

The source-owned workspace guide is staged from the same revision as the generated reference.

Example workspaces

Each workspace below is a file that libtmux/libtmux-ruby loads in a test or a scheduled run, as the list under it says. The drawing shows the panes of each window and the commands each pane receives.

Short-hand panes

A pane can be one command written as a string, and a command list can be one string.

session_name: shorthands
windows:
  - window_name: long form
    panes:
      - shell_command:
          - echo 'did you know'
          - echo 'you can inline'
      - shell_command: echo 'single commands'
      - echo 'for panes'

{
  "session_name": "shorthands",
  "windows": [
    {
      "window_name": "long form",
      "panes": [
        {
          "shell_command": [
            "echo 'did you know'",
            "echo 'you can inline'"
          ]
        },
        {
          "shell_command": "echo 'single commands'"
        },
        "echo 'for panes'"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:long form

no layout set

Same file as tmuxp's examples/shorthands.yaml.

Source: test/fixtures/tmuxp/shorthands.yaml

Loaded by:

test_tmuxp_examples_load_through_workspace_load: Loads the file with Workspace.load and checks its profile. (test/unit/workspace_test.rb; loaded by the library in a test; the command is not run)

Two panes

A window of two panes.

session_name: 2-pane-vertical
windows:
  - window_name: my test window
    panes:
      - echo hello
      - echo hello

{
  "session_name": "2-pane-vertical",
  "windows": [
    {
      "window_name": "my test window",
      "panes": [
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:my test window

no layout set

Same file as tmuxp's examples/2-pane-vertical.yaml.

Source: test/fixtures/tmuxp/2-pane-vertical.yaml

Loaded by:

test_tmuxp_examples_load_through_workspace_load: Loads the file with Workspace.load and checks its profile. (test/unit/workspace_test.rb; loaded by the library in a test; the command is not run)

Three panes

A window of three panes.

Also shows: setup before each pane

session_name: 3-panes
windows:
  - window_name: dev window
    layout: main-vertical
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo hello
      - echo hello

{
  "session_name": "3-panes",
  "windows": [
    {
      "window_name": "dev window",
      "layout": "main-vertical",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep \\.log"
          ]
        },
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:dev window

layout main-vertical

Same file as tmuxp's examples/3-pane.yaml.

Source: test/fixtures/tmuxp/3-pane.yaml

Loaded by:

test_tmuxp_examples_load_through_workspace_load: Loads the file with Workspace.load and checks its profile. (test/unit/workspace_test.rb; loaded by the library in a test; the command is not run)

Four panes

A window of four panes.

Also shows: tiled layout

session_name: 4-pane-split
windows:
  - window_name: dev window
    layout: tiled
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo hello
      - echo hello
      - echo hello

{
  "session_name": "4-pane-split",
  "windows": [
    {
      "window_name": "dev window",
      "layout": "tiled",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep \\.log"
          ]
        },
        "echo hello",
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:dev window

layout tiled

Same file as tmuxp's examples/4-pane.yaml.

Source: test/fixtures/tmuxp/4-pane.yaml

Loaded by:

test_tmuxp_examples_load_through_workspace_load: Loads the file with Workspace.load and checks its profile. (test/unit/workspace_test.rb; loaded by the library in a test; the command is not run)

Tiled layout

The tiled layout arranges the panes in a grid.

Also shows: two panes, environment

session_name: work
environment:
  PROJECT_MODE: development
windows:
  - window_name: editor
    window_index: 1
    layout: tiled
    panes:
      - shell_command: printf 'editor ready\n'
      - {}

{
  "session_name": "work",
  "environment": {
    "PROJECT_MODE": "development"
  },
  "windows": [
    {
      "window_name": "editor",
      "window_index": 1,
      "layout": "tiled",
      "panes": [
        {
          "shell_command": "printf 'editor ready\\n'"
        },
        {}
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

1:editor

layout tiled

Source: examples/workspace.yaml

Loaded by:

test_installed_imports_use_declared_dependencies_without_starting_resources: Installs the gems into an isolated home and runs each installed example program in examples/manifest.json, including workspace_apply, which runs the installed libtmux-workspace executable on this file. (test/packaging/package_test.rb; a test runs the command)
workspace_apply: Loads the file with Workspace.load and applies it through the library, then runs the libtmux-workspace executable's validate, plan and load on it. (examples/workspace_apply.rb; a test runs the command)

Environment

environment sets variables for a session, a window or a pane.

session_name: Environment variables test
environment:
  EDITOR: /usr/bin/vim
  DJANGO_SETTINGS_MODULE: my_app.settings.local
  SERVER_PORT: "8009"
windows:
  - window_name: Django project
    panes:
      - ./manage.py runserver 0.0.0.0:${SERVER_PORT}
  - window_name: Another Django project
    environment:
      DJANGO_SETTINGS_MODULE: my_app.settings.local
      SERVER_PORT: "8010"
    panes:
      - ./manage.py runserver 0.0.0.0:${SERVER_PORT}
      - environment:
          DJANGO_SETTINGS_MODULE: my_app.settings.local-testing
          SERVER_PORT: "8011"
        shell_command: ./manage.py runserver 0.0.0.0:${SERVER_PORT}

{
  "session_name": "Environment variables test",
  "environment": {
    "EDITOR": "/usr/bin/vim",
    "DJANGO_SETTINGS_MODULE": "my_app.settings.local",
    "SERVER_PORT": "8009"
  },
  "windows": [
    {
      "window_name": "Django project",
      "panes": [
        "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
      ]
    },
    {
      "window_name": "Another Django project",
      "environment": {
        "DJANGO_SETTINGS_MODULE": "my_app.settings.local",
        "SERVER_PORT": "8010"
      },
      "panes": [
        "./manage.py runserver 0.0.0.0:${SERVER_PORT}",
        {
          "environment": {
            "DJANGO_SETTINGS_MODULE": "my_app.settings.local-testing",
            "SERVER_PORT": "8011"
          },
          "shell_command": "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:Django project

no layout set

1:Another Django project

no layout set

Same file as tmuxp's examples/session-environment.yaml.

Source: test/fixtures/tmuxp/session-environment.yaml

Loaded by:

test_tmuxp_examples_load_through_workspace_load: Loads the file with Workspace.load and checks its profile. (test/unit/workspace_test.rb; loaded by the library in a test; the command is not run)

Window index

window_index places a window at an index; a window without one takes the lowest free index.

session_name: Window index example
windows:
  - window_name: zero
    panes:
      - echo "this window's index will be zero"
  - window_name: five
    panes:
      - echo "this window's index will be five"
    window_index: 5
  - window_name: one
    panes:
      - echo "this window's index will be one"

{
  "session_name": "Window index example",
  "windows": [
    {
      "window_name": "zero",
      "panes": [
        "echo \"this window's index will be zero\""
      ]
    },
    {
      "window_name": "five",
      "panes": [
        "echo \"this window's index will be five\""
      ],
      "window_index": 5
    },
    {
      "window_name": "one",
      "panes": [
        "echo \"this window's index will be one\""
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:zero

no layout set

1:one

no layout set

5:five

no layout set

Same file as tmuxp's examples/window-index.yaml.

Source: test/fixtures/tmuxp/window-index.yaml

Loaded by:

test_tmuxp_examples_load_through_workspace_load: Loads the file with Workspace.load and checks its profile. (test/unit/workspace_test.rb; loaded by the library in a test; the command is not run)

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

tmux workspace manager, forged in Ruby.

Explore tmux layout / workspace possibilities

Install

Start here¶

Example workspaces

Short-hand panes

Two panes

Three panes

Four panes

Tiled layout

Environment

Window index