# libtmux for PowerShell

Source: https://libtmux.org/en/powershell/latest/

> libtmux for PowerShell, version latest.

![](https://libtmux.org/en/brand/powershell/library/logo.svg)

PowerShell-based tmux client

tmux client library for PowerShell. Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents

Product

Core API MCP Workspace Manager

## Start with PowerShell

Example details

\+ Error handling + Cleanup

```powershell
$ErrorActionPreference = 'Stop'
Import-Module "$PSScriptRoot/modules/LibTmux/0.1.0/LibTmux.psd1"


$socket = 'libtmux-home-' + [Guid]::NewGuid().ToString('N')
$server = New-TmuxServer -SocketName $socket -ConfigurationFile /dev/null


$session = $server | New-TmuxSession `
    -Name demo -WindowName editor -Command 'exec /bin/cat'
$pane = $session | Get-TmuxPane
$null = $pane | Split-TmuxPane -Horizontal -Command 'exec /bin/cat'
$null = $session | New-TmuxWindow -Name logs -Command 'exec /bin/cat'


$captured = ($server | Get-TmuxSnapshot).Sessions |
    Select-TmuxSession -Criteria @{ Name = 'demo' } -ExactlyOne
foreach ($window in $captured.Windows) {
    '{0}: {1}' -f $window.Name, ($window.Panes.Id -join ', ')
}
```

```powershell
$ErrorActionPreference = 'Stop'
Import-Module "$PSScriptRoot/modules/LibTmux/0.1.0/LibTmux.psd1"


try {
    $socket = 'libtmux-home-' + [Guid]::NewGuid().ToString('N')
    $server = New-TmuxServer -SocketName $socket -ConfigurationFile /dev/null


    $session = $server | New-TmuxSession `
        -Name demo -WindowName editor -Command 'exec /bin/cat'
    $pane = $session | Get-TmuxPane
    $null = $pane | Split-TmuxPane -Horizontal -Command 'exec /bin/cat'
    $null = $session | New-TmuxWindow -Name logs -Command 'exec /bin/cat'


    $captured = ($server | Get-TmuxSnapshot).Sessions |
        Select-TmuxSession -Criteria @{ Name = 'demo' } -ExactlyOne
    foreach ($window in $captured.Windows) {
        '{0}: {1}' -f $window.Name, ($window.Panes.Id -join ', ')
    }
} catch {
    $failure = [InvalidOperationException]::new(
        "tmux quickstart failed: $($_.Exception.Message)", $_.Exception)
    throw $failure
}
```

```powershell
$ErrorActionPreference = 'Stop'
Import-Module "$PSScriptRoot/modules/LibTmux/0.1.0/LibTmux.psd1"


$session = $null
$failure = $null
try {
    $socket = 'libtmux-home-' + [Guid]::NewGuid().ToString('N')
    $server = New-TmuxServer -SocketName $socket -ConfigurationFile /dev/null


    $session = $server | New-TmuxSession `
        -Name demo -WindowName editor -Command 'exec /bin/cat'
    $pane = $session | Get-TmuxPane
    $null = $pane | Split-TmuxPane -Horizontal -Command 'exec /bin/cat'
    $null = $session | New-TmuxWindow -Name logs -Command 'exec /bin/cat'


    $captured = ($server | Get-TmuxSnapshot).Sessions |
        Select-TmuxSession -Criteria @{ Name = 'demo' } -ExactlyOne
    foreach ($window in $captured.Windows) {
        '{0}: {1}' -f $window.Name, ($window.Panes.Id -join ', ')
    }
} catch {
    $failure = $_.Exception
    throw
} finally {
    if ($session) {
        $cleanupErrors = @()
        $session | Remove-TmuxSession -Confirm:$false `
            -ErrorAction SilentlyContinue -ErrorVariable cleanupErrors
        if ($cleanupErrors) {
            if ($failure) {
                $errors = @($failure) + $cleanupErrors.Exception
                throw [AggregateException]::new(
                    'tmux operation and cleanup failed.',
                    [Exception[]]$errors)
            }
            throw $cleanupErrors[0]
        }
    }
}
```

```powershell
$ErrorActionPreference = 'Stop'
Import-Module "$PSScriptRoot/modules/LibTmux/0.1.0/LibTmux.psd1"


$session = $null
$failure = $null
try {
    $socket = 'libtmux-home-' + [Guid]::NewGuid().ToString('N')
    $server = New-TmuxServer -SocketName $socket -ConfigurationFile /dev/null


    $session = $server | New-TmuxSession `
        -Name demo -WindowName editor -Command 'exec /bin/cat'
    $pane = $session | Get-TmuxPane
    $null = $pane | Split-TmuxPane -Horizontal -Command 'exec /bin/cat'
    $null = $session | New-TmuxWindow -Name logs -Command 'exec /bin/cat'


    $captured = ($server | Get-TmuxSnapshot).Sessions |
        Select-TmuxSession -Criteria @{ Name = 'demo' } -ExactlyOne
    foreach ($window in $captured.Windows) {
        '{0}: {1}' -f $window.Name, ($window.Panes.Id -join ', ')
    }
} catch {
    $failure = [InvalidOperationException]::new(
        "tmux quickstart failed: $($_.Exception.Message)", $_.Exception)
    throw $failure
} finally {
    if ($session) {
        $cleanupErrors = @()
        $session | Remove-TmuxSession -Confirm:$false `
            -ErrorAction SilentlyContinue -ErrorVariable cleanupErrors
        if ($cleanupErrors) {
            if ($failure) {
                $errors = @($failure) + $cleanupErrors.Exception
                throw [AggregateException]::new(
                    'tmux operation and cleanup failed.',
                    [Exception[]]$errors)
            }
            throw $cleanupErrors[0]
        }
    }
}
```

Run this example

PowerShell 7.4.20 with PSResourceGet 1.1.1, POSIX shell and tmux on Linux.

Save the program above as `quickstart.ps1` in a new directory, along with the files below.

Cleanup is omitted; the private tmux server and its temporary files may remain. Select Cleanup to remove them when the program finishes. The program stops its private tmux server and removes any temporary files it created when it finishes. Error handling adds diagnostics; every version checks required results and deadlines.

### Setup and run

```bash
pwsh -NoLogo -NoProfile -Command '
  $ErrorActionPreference = "Stop"
  $null = New-Item -ItemType Directory -Path ./modules -Force
  Save-PSResource -Name LibTmux -Version 0.1.0 `
    -Path ./modules -TrustRepository
'
```

```bash
unset TMUX TMUX_PANE
export ENV=/dev/null BASH_ENV=/dev/null SHELL=/bin/sh
pwsh -NoLogo -NoProfile -File quickstart.ps1
```

### Expected output

```text
editor: %0, %1
logs: %2
```

Library revision: [2c30121b7733](https://github.com/libtmux/libtmux-powershell/tree/2c30121b7733bf772d17140231a49332e5a470ab).

[Core Library documentation →](https://libtmux.org/en/powershell/latest/core/)[More PowerShell examples →](https://libtmux.org/en/powershell/latest/examples/)

### Install `LibTmux`

```powershell
Install-Module -Name LibTmux
```

Requires PowerShell 7.4 or later and tmux on the same Unix host.

## MCP

PowerShell has no MCP package of its own. It uses the C# port's `LibTmux.Mcp`.

The C# server lets an agent work with tmux through 45 tools, grouped as Inspect, Manage, Execute and Teardown.

### Install `LibTmux.Mcp`

Choose your client and configuration scope, then run the command or paste the configuration.

```console
$ claude mcp add tmux -- dnx LibTmux.Mcp --yes
```

Runs the server from NuGet without installing it; needs the .NET 10 SDK. Write LibTmux.Mcp@\<version> to pin a version.

Config file: `~/.claude.json (this project)`

* [Every tool, with its arguments and result →](https://libtmux.org/en/csharp/latest/mcp/tools/)
* [MCP documentation →](https://libtmux.org/en/powershell/latest/guides/mcp/)

Embed the server in a program

examples/LibTmux.Examples/Snippets/Mcp.cs

```csharp
Dictionary<string, string?> environment =
    StdioClientTransportOptions.GetDefaultEnvironmentVariables();
environment["LIBTMUX_SOCKET"] = server.ConnectionOptions.SocketName;
environment["TMUX_TMPDIR"] = Environment.GetEnvironmentVariable("TMUX_TMPDIR");
environment["DOTNET_ROOT"] = Environment.GetEnvironmentVariable("DOTNET_ROOT");
environment["LIBTMUX_TOOLSETS"] = "inspect,manage,execute";
environment["LIBTMUX_EXCLUDE_TOOLS"] = "run_shell_command";


var transport = new StdioClientTransport(new StdioClientTransportOptions
{
    Name = "tmux",
    Command = Environment.GetEnvironmentVariable("LIBTMUX_MCP_COMMAND")
        ?? "libtmux-mcp",
    InheritEnvironmentVariables = false,
    EnvironmentVariables = environment,
});
McpClient client = await McpClient.CreateAsync(
    transport,
    cancellationToken: ct);
```

Excerpt of [`examples/LibTmux.Examples/Snippets/Mcp.cs`](https://github.com/libtmux/libtmux-dotnet/blob/8d47af7d89638ad267528ac56897cec67df597f7/examples/LibTmux.Examples/Snippets/Mcp.cs), which `dotnet test --project tests/LibTmux.ExampleTests/LibTmux.ExampleTests.csproj` runs in the repository's CI (`.github/workflows/dotnet.yml`).

## Workspace Manager

### Main-horizontal layout

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

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

```json
{
  "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

Workspace file: [`tests/fixtures/workspace/tmuxp-v1.74.0-window_options.yaml`](https://github.com/libtmux/libtmux-powershell/blob/06233d3c99b40a5bce966c9e1d358f346ff4de55/tests/fixtures/workspace/tmuxp-v1.74.0-window_options.yaml). Tested by [`window options fixture`](https://github.com/libtmux/libtmux-powershell/blob/06233d3c99b40a5bce966c9e1d358f346ff4de55/tests/WorkspaceCorpus.Tests.ps1#L301) (tests/WorkspaceCorpus.Tests.ps1; a test runs the command).

### Install `LibTmux.Workspace`

The workspace package is separate from the core library.

```powershell
Install-Module -Name LibTmux.Workspace
```

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

* [Try other presets →](https://libtmux.org/en/powershell/latest/workspace/#try-a-preset)
* [Workspace Manager documentation →](https://libtmux.org/en/powershell/latest/workspace/)

Build the workspace from a program

examples/Guides.ps1

```powershell
$workspace = LibTmux.Workspace\Import-TmuxWorkspace -Yaml @'
session_name: readme-workspace-preview
windows:
  - window_name: editor
    panes:
      - shell_command: exec /bin/sh
      - shell_command: exec /bin/sh
'@
```

Excerpt of [`examples/Guides.ps1`](https://github.com/libtmux/libtmux-powershell/blob/06233d3c99b40a5bce966c9e1d358f346ff4de55/examples/Guides.ps1), which `eng/Test.ps1 -Suite Documentation` runs in the repository's CI (`.github/workflows/ci.yml`).

### [Topics](https://libtmux.org/en/powershell/latest/topics/)

[Subject-by-subject, with PowerShell in every code block.](https://libtmux.org/en/powershell/latest/topics/)

### [Guides](https://libtmux.org/en/powershell/latest/guides/)

[Task guides for PowerShell.](https://libtmux.org/en/powershell/latest/guides/)

### [Examples](https://libtmux.org/en/powershell/latest/examples/)

[Complete programs, sourced from the code each port tests.](https://libtmux.org/en/powershell/latest/examples/)

### [Concepts](https://libtmux.org/en/powershell/latest/concepts/)

[The domain model every port shares.](https://libtmux.org/en/powershell/latest/concepts/)

## Packages and integrations

### [Workspace Manager](https://libtmux.org/en/powershell/latest/workspace/)

[Read, validate, plan and load workspace files with LibTmux.Workspace.](https://libtmux.org/en/powershell/latest/workspace/)

## API references

### [Official reference](https://libtmux.org/en/powershell/latest/reference/)

[PowerShell API signatures and documentation, with links to related guides and APIs in other languages.](https://libtmux.org/en/powershell/latest/reference/)

[All PowerShell versions and install instructions](https://libtmux.org/en/powershell/)