tmux workspace manager, forged in PowerShell.

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

Try a preset

Preset

session_name: test window options
start_directory: '~'
windows:
- layout: main-horizontal
  options:
    main-pane-height: 5
  panes:
  - pane
  - pane
  - pane
  window_name: editor

{
  "session_name": "test window options",
  "start_directory": "~",
  "windows": [
    {
      "layout": "main-horizontal",
      "options": {
        "main-pane-height": 5
      },
      "panes": [
        "pane",
        "pane",
        "pane"
      ],
      "window_name": "editor"
    }
  ]
}

layout main-horizontal

session_name: corpus
start_directory: ${PROJECT_ROOT}
options:
  default-command: exec /bin/sh
  '@corpus-session': yaml-original
environment:
  CORPUS_SESSION: yaml-root
  CORPUS_LAYER: session
shell_command_before:
  - cmd: echo session >> order.txt
windows:
  - window_name: yaml-editor
    start_directory: window
    layout: even-horizontal
    focus: true
    options:
      '@corpus-window': '${OPTION_TAG}'
    environment:
      CORPUS_WINDOW: yaml-window
      CORPUS_LAYER: window
    shell_command_before:
      - cmd: echo window >> order.txt
    panes:
      - shell_command:
          - cmd: echo command >> order.txt
          - 'echo "$CORPUS_SESSION|$CORPUS_WINDOW|$CORPUS_PANE|$CORPUS_LAYER" > environment.txt'
          - tmux wait-for -S corpus-yaml-first
      - start_directory: pane
        focus: true
        options:
          '@corpus-pane': yaml
        environment:
          CORPUS_PANE: yaml-pane
          CORPUS_LAYER: pane
        shell_command_before:
          - cmd: echo pane >> order.txt
        shell_command:
          - echo command >> order.txt
          - 'echo "$CORPUS_SESSION|$CORPUS_WINDOW|$CORPUS_PANE|$CORPUS_LAYER" > environment.txt'
          - tmux wait-for -S corpus-yaml-second

{
  "session_name": "corpus",
  "start_directory": "${PROJECT_ROOT}",
  "options": {
    "default-command": "exec /bin/sh",
    "@corpus-session": "yaml-original"
  },
  "environment": {
    "CORPUS_SESSION": "yaml-root",
    "CORPUS_LAYER": "session"
  },
  "shell_command_before": [
    {
      "cmd": "echo session >> order.txt"
    }
  ],
  "windows": [
    {
      "window_name": "yaml-editor",
      "start_directory": "window",
      "layout": "even-horizontal",
      "focus": true,
      "options": {
        "@corpus-window": "${OPTION_TAG}"
      },
      "environment": {
        "CORPUS_WINDOW": "yaml-window",
        "CORPUS_LAYER": "window"
      },
      "shell_command_before": [
        {
          "cmd": "echo window >> order.txt"
        }
      ],
      "panes": [
        {
          "shell_command": [
            {
              "cmd": "echo command >> order.txt"
            },
            "echo \"$CORPUS_SESSION|$CORPUS_WINDOW|$CORPUS_PANE|$CORPUS_LAYER\" > environment.txt",
            "tmux wait-for -S corpus-yaml-first"
          ]
        },
        {
          "start_directory": "pane",
          "focus": true,
          "options": {
            "@corpus-pane": "yaml"
          },
          "environment": {
            "CORPUS_PANE": "yaml-pane",
            "CORPUS_LAYER": "pane"
          },
          "shell_command_before": [
            {
              "cmd": "echo pane >> order.txt"
            }
          ],
          "shell_command": [
            "echo command >> order.txt",
            "echo \"$CORPUS_SESSION|$CORPUS_WINDOW|$CORPUS_PANE|$CORPUS_LAYER\" > environment.txt",
            "tmux wait-for -S corpus-yaml-second"
          ]
        }
      ]
    }
  ]
}

layout even-horizontal

session_name: test env vars
start_directory: "~"
environment:
  FOO: SESSION
  PATH: /tmp
windows:
- window_name: no_overrides
  panes:
  - pane
- window_name: window_overrides
  environment:
    FOO: WINDOW
  panes:
  - pane
- window_name: pane_overrides
  panes:
  - environment:
      FOO: PANE
- window_name: both_overrides
  environment:
    FOO: WINDOW
  panes:
  - pane
  - environment:
      FOO: PANE
# This test case it just needed for warnings issued in old versions of tmux.
- window_name: both_overrides_on_first_pane
  environment:
    FOO: WINDOW
  panes:
  - environment:
      FOO: PANE

{
  "session_name": "test env vars",
  "start_directory": "~",
  "environment": {
    "FOO": "SESSION",
    "PATH": "/tmp"
  },
  "windows": [
    {
      "window_name": "no_overrides",
      "panes": [
        "pane"
      ]
    },
    {
      "window_name": "window_overrides",
      "environment": {
        "FOO": "WINDOW"
      },
      "panes": [
        "pane"
      ]
    },
    {
      "window_name": "pane_overrides",
      "panes": [
        {
          "environment": {
            "FOO": "PANE"
          }
        }
      ]
    },
    {
      "window_name": "both_overrides",
      "environment": {
        "FOO": "WINDOW"
      },
      "panes": [
        "pane",
        {
          "environment": {
            "FOO": "PANE"
          }
        }
      ]
    },
    {
      "window_name": "both_overrides_on_first_pane",
      "environment": {
        "FOO": "WINDOW"
      },
      "panes": [
        {
          "environment": {
            "FOO": "PANE"
          }
        }
      ]
    }
  ]
}

no layout set

session_name: sample workspace
windows:
  - panes:
    - start_directory: /usr
    - start_directory: /etc

{
  "session_name": "sample workspace",
  "windows": [
    {
      "panes": [
        {
          "start_directory": "/usr"
        },
        {
          "start_directory": "/etc"
        }
      ]
    }
  ]
}

no layout set

session_name: Skip command execution (command-level)
windows:
  - panes:
      - shell_command:
          # You can see this
          - echo "___$((11 + 1))___"
          # This is skipped
          - cmd: echo "___$((1 + 3))___"
            enter: false

{
  "session_name": "Skip command execution (command-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "echo \"___$((11 + 1))___\"",
            {
              "cmd": "echo \"___$((1 + 3))___\"",
              "enter": false
            }
          ]
        }
      ]
    }
  ]
}

no layout set

session_name: Skip command execution (pane-level)
windows:
  - panes:
      - shell_command: echo "___$((1 + 3))___"
        enter: false
      - shell_command:
          - echo "___$((1 + 3))___"\;
          - echo "___$((1 + 3))___"
        enter: false

{
  "session_name": "Skip command execution (pane-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": "echo \"___$((1 + 3))___\"",
          "enter": false
        },
        {
          "shell_command": [
            "echo \"___$((1 + 3))___\"\\;",
            "echo \"___$((1 + 3))___\""
          ],
          "enter": false
        }
      ]
    }
  ]
}

no layout set

Install

Install the workspace package separately from the core library.

Install-Module -Name LibTmux.Workspace

Installs the matching LibTmux core dependency. Run PowerShell and tmux on the same Unix host.

Install-PSResource -Name LibTmux.Workspace

Installs the matching LibTmux core dependency. Run PowerShell and tmux on the same Unix host.

LibTmux.Workspace provides PowerShell commands for reading, validating, planning and applying workspace configuration. The module uses LibTmux for tmux objects and operations.

Install the module with the commands below, then follow the workspace guide to inspect a plan before applying it. The command reference lists every exported workspace command and its parameter sets.

The PowerShell Gallery package also provides Azure Automation and manual download options. Manual downloads require you to install the package dependencies separately.

Example workspaces

Each workspace below is a file that libtmux/libtmux-powershell 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.

Main-horizontal layout

The main-horizontal layout gives the first pane the top of the window and splits the rest below it.

Also shows: three panes

session_name: test window options
start_directory: '~'
windows:
- layout: main-horizontal
  options:
    main-pane-height: 5
  panes:
  - pane
  - pane
  - pane
  window_name: editor

{
  "session_name": "test window options",
  "start_directory": "~",
  "windows": [
    {
      "layout": "main-horizontal",
      "options": {
        "main-pane-height": 5
      },
      "panes": [
        "pane",
        "pane",
        "pane"
      ],
      "window_name": "editor"
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:editor

layout main-horizontal

Source: tests/fixtures/workspace/tmuxp-v1.74.0-window_options.yaml

Loaded by:

window options fixture: Runs the workspace cmdlets Import-TmuxWorkspace, Resolve-TmuxWorkspace, Get-TmuxWorkspacePlan and Invoke-TmuxWorkspace on the file against real tmux and checks the layout, the main-pane-height option and each pane's directory. (tests/WorkspaceCorpus.Tests.ps1; a test runs the command)

Setup before each pane

shell_command_before runs ahead of a pane's own commands, at the session, window or pane level.

Also shows: environment, start directory, two panes

session_name: corpus
start_directory: ${PROJECT_ROOT}
options:
  default-command: exec /bin/sh
  '@corpus-session': yaml-original
environment:
  CORPUS_SESSION: yaml-root
  CORPUS_LAYER: session
shell_command_before:
  - cmd: echo session >> order.txt
windows:
  - window_name: yaml-editor
    start_directory: window
    layout: even-horizontal
    focus: true
    options:
      '@corpus-window': '${OPTION_TAG}'
    environment:
      CORPUS_WINDOW: yaml-window
      CORPUS_LAYER: window
    shell_command_before:
      - cmd: echo window >> order.txt
    panes:
      - shell_command:
          - cmd: echo command >> order.txt
          - 'echo "$CORPUS_SESSION|$CORPUS_WINDOW|$CORPUS_PANE|$CORPUS_LAYER" > environment.txt'
          - tmux wait-for -S corpus-yaml-first
      - start_directory: pane
        focus: true
        options:
          '@corpus-pane': yaml
        environment:
          CORPUS_PANE: yaml-pane
          CORPUS_LAYER: pane
        shell_command_before:
          - cmd: echo pane >> order.txt
        shell_command:
          - echo command >> order.txt
          - 'echo "$CORPUS_SESSION|$CORPUS_WINDOW|$CORPUS_PANE|$CORPUS_LAYER" > environment.txt'
          - tmux wait-for -S corpus-yaml-second

{
  "session_name": "corpus",
  "start_directory": "${PROJECT_ROOT}",
  "options": {
    "default-command": "exec /bin/sh",
    "@corpus-session": "yaml-original"
  },
  "environment": {
    "CORPUS_SESSION": "yaml-root",
    "CORPUS_LAYER": "session"
  },
  "shell_command_before": [
    {
      "cmd": "echo session >> order.txt"
    }
  ],
  "windows": [
    {
      "window_name": "yaml-editor",
      "start_directory": "window",
      "layout": "even-horizontal",
      "focus": true,
      "options": {
        "@corpus-window": "${OPTION_TAG}"
      },
      "environment": {
        "CORPUS_WINDOW": "yaml-window",
        "CORPUS_LAYER": "window"
      },
      "shell_command_before": [
        {
          "cmd": "echo window >> order.txt"
        }
      ],
      "panes": [
        {
          "shell_command": [
            {
              "cmd": "echo command >> order.txt"
            },
            "echo \"$CORPUS_SESSION|$CORPUS_WINDOW|$CORPUS_PANE|$CORPUS_LAYER\" > environment.txt",
            "tmux wait-for -S corpus-yaml-first"
          ]
        },
        {
          "start_directory": "pane",
          "focus": true,
          "options": {
            "@corpus-pane": "yaml"
          },
          "environment": {
            "CORPUS_PANE": "yaml-pane",
            "CORPUS_LAYER": "pane"
          },
          "shell_command_before": [
            {
              "cmd": "echo pane >> order.txt"
            }
          ],
          "shell_command": [
            "echo command >> order.txt",
            "echo \"$CORPUS_SESSION|$CORPUS_WINDOW|$CORPUS_PANE|$CORPUS_LAYER\" > environment.txt",
            "tmux wait-for -S corpus-yaml-second"
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:yaml-editor

layout even-horizontal

${PROJECT_ROOT} and ${OPTION_TAG} are variables the loader expands.

Source: tests/fixtures/workspace/corpus.yaml

Loaded by:

corpus fixture: Runs the workspace cmdlets Import-TmuxWorkspace, Resolve-TmuxWorkspace, Get-TmuxWorkspacePlan and Invoke-TmuxWorkspace on the file against real tmux and checks the order of the commands, the environment each pane sees and each pane's directory. (tests/WorkspaceCorpus.Tests.ps1; a test runs the command)

Environment

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

session_name: test env vars
start_directory: "~"
environment:
  FOO: SESSION
  PATH: /tmp
windows:
- window_name: no_overrides
  panes:
  - pane
- window_name: window_overrides
  environment:
    FOO: WINDOW
  panes:
  - pane
- window_name: pane_overrides
  panes:
  - environment:
      FOO: PANE
- window_name: both_overrides
  environment:
    FOO: WINDOW
  panes:
  - pane
  - environment:
      FOO: PANE
# This test case it just needed for warnings issued in old versions of tmux.
- window_name: both_overrides_on_first_pane
  environment:
    FOO: WINDOW
  panes:
  - environment:
      FOO: PANE

{
  "session_name": "test env vars",
  "start_directory": "~",
  "environment": {
    "FOO": "SESSION",
    "PATH": "/tmp"
  },
  "windows": [
    {
      "window_name": "no_overrides",
      "panes": [
        "pane"
      ]
    },
    {
      "window_name": "window_overrides",
      "environment": {
        "FOO": "WINDOW"
      },
      "panes": [
        "pane"
      ]
    },
    {
      "window_name": "pane_overrides",
      "panes": [
        {
          "environment": {
            "FOO": "PANE"
          }
        }
      ]
    },
    {
      "window_name": "both_overrides",
      "environment": {
        "FOO": "WINDOW"
      },
      "panes": [
        "pane",
        {
          "environment": {
            "FOO": "PANE"
          }
        }
      ]
    },
    {
      "window_name": "both_overrides_on_first_pane",
      "environment": {
        "FOO": "WINDOW"
      },
      "panes": [
        {
          "environment": {
            "FOO": "PANE"
          }
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:no_overrides

no layout set

1:window_overrides

no layout set

2:pane_overrides

no layout set

3:both_overrides

no layout set

4:both_overrides_on_first_pane

no layout set

Source: tests/fixtures/workspace/tmuxp-v1.74.0-environment_vars.yaml

Loaded by:

environment variables fixture: Runs the workspace cmdlets Import-TmuxWorkspace, Resolve-TmuxWorkspace, Get-TmuxWorkspacePlan and Invoke-TmuxWorkspace on the file against real tmux and checks the session environment and the value each pane prints. (tests/WorkspaceCorpus.Tests.ps1; a test runs the command)

Start directory

start_directory chooses where a session, a window or a pane starts.

Also shows: two panes

session_name: sample workspace
windows:
  - panes:
    - start_directory: /usr
    - start_directory: /etc

{
  "session_name": "sample workspace",
  "windows": [
    {
      "panes": [
        {
          "start_directory": "/usr"
        },
        {
          "start_directory": "/etc"
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set

Source: tests/fixtures/workspace/tmuxp-v1.74.0-first_pane_start_directory.yaml

Loaded by:

first pane start directory fixture: Runs the workspace cmdlets Import-TmuxWorkspace, Get-TmuxWorkspacePlan and Invoke-TmuxWorkspace on the file against real tmux, resolving it with the document's Resolve method, and checks the directory of each pane. (tests/WorkspaceCorpus.Tests.ps1; a test runs the command)

Skip Enter for a command

enter: false types a command without running it.

session_name: Skip command execution (command-level)
windows:
  - panes:
      - shell_command:
          # You can see this
          - echo "___$((11 + 1))___"
          # This is skipped
          - cmd: echo "___$((1 + 3))___"
            enter: false

{
  "session_name": "Skip command execution (command-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "echo \"___$((11 + 1))___\"",
            {
              "cmd": "echo \"___$((1 + 3))___\"",
              "enter": false
            }
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set

Same file as tmuxp's examples/skip-send.yaml.

Source: tests/fixtures/workspace/tmuxp-v1.74.0-skip-send.yaml

Loaded by:

skip-send fixture: Plans the file and its JSON twin with Get-TmuxWorkspacePlan and checks which commands are sent without Enter. Applies nothing. (tests/WorkspaceCorpus.Tests.ps1; built by the library in a test; the command is not run)

Skip Enter for a pane

enter: false on a pane types its commands without running them.

session_name: Skip command execution (pane-level)
windows:
  - panes:
      - shell_command: echo "___$((1 + 3))___"
        enter: false
      - shell_command:
          - echo "___$((1 + 3))___"\;
          - echo "___$((1 + 3))___"
        enter: false

{
  "session_name": "Skip command execution (pane-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": "echo \"___$((1 + 3))___\"",
          "enter": false
        },
        {
          "shell_command": [
            "echo \"___$((1 + 3))___\"\\;",
            "echo \"___$((1 + 3))___\""
          ],
          "enter": false
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set

Same file as tmuxp's examples/skip-send-pane-level.yaml.

Source: tests/fixtures/workspace/tmuxp-v1.74.0-skip-send-pane-level.yaml

Loaded by:

skip-send pane-level fixture: Plans the file and its JSON twin with Get-TmuxWorkspacePlan and checks which commands are sent without Enter. Applies nothing. (tests/WorkspaceCorpus.Tests.ps1; built by the library in a test; the command is not run)

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

tmux workspace manager, forged in PowerShell.

Try a preset

Install

Example workspaces

Main-horizontal layout

Setup before each pane

Environment

Start directory

Skip Enter for a command

Skip Enter for a pane