psmux

https://psmux.pages.dev
Admin
psmux is a native Windows terminal multiplexer offering tmux-compatible session management, pane...
Tokens:54,547
Snippets:744
Trust Score:7.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install persistent psmux-win client

Source: https://psmux.pages.dev/docs/mouse-ssh

Run the installer script to set up a persistent client for one-command connections. The installer creates local configuration and binary files without modifying SSH settings.

```bash
sh install-psmux-win.sh --host user@windows-host \
  --psmux C:/Users/user/.cargo/bin/psmux.exe

psmux-win -s work
psmux-win -L project -s work
```

--------------------------------

### Install libtmux

Source: https://psmux.pages.dev/docs/integration

Install the libtmux library via pip.

```bash
pip install libtmux
```

--------------------------------

### Install PowerShell 7+

Source: https://psmux.pages.dev/docs/claude-code

Use winget to install the required version of PowerShell on Windows.

```powershell
winget install --id Microsoft.PowerShell --source winget
```

--------------------------------

### Example Directory Listing

Source: https://psmux.pages.dev/docs/diagnostics

Sample output showing session files and the plugins directory within the psmux home folder.

```text
Mode    LastWriteTime        Length Name
----    -------------        ------ ----
d----   7/27/2026  9:14 AM          plugins
-a---   7/27/2026  9:14 AM      21  work.port
-a---   7/27/2026  9:14 AM      44  work.key
-a---   7/27/2026  9:14 AM      26  work.pid
-a---   7/27/2026  9:12 AM      21  __warm__.port
-a---   7/27/2026  9:12 AM       4  last_session
```

--------------------------------

### Install the psmux plugin manager

Source: https://psmux.pages.dev/docs/plugins

Use these commands to clone the plugin repository and install the ppm manager to the local plugins directory.

```powershell
# Install the plugin manager
git clone https://github.com/psmux/psmux-plugins.git "$env:TEMP\psmux-plugins"
Copy-Item "$env:TEMP\psmux-plugins\ppm" "$env:USERPROFILE\.psmux\plugins\ppm" -Recurse
Remove-Item "$env:TEMP\psmux-plugins" -Recurse -Force
```

--------------------------------

### Install psmux via Cargo

Source: https://psmux.pages.dev/README.md

Install psmux from crates.io using Cargo.

```bash
$cargo install psmux
```

--------------------------------

### Configure Custom Key Bindings

Source: https://psmux.pages.dev/docs/keybindings

Examples of binding keys to commands in different tables, handling repeatable keys, and removing existing bindings.

```text
# Bind in prefix table (default)
bind-key h split-window -h
bind-key v split-window -v

# Bind in root table (no prefix needed)
bind-key -n C-h select-pane -L

# Restore the pre-issue-488 bare PageUp behavior
bind-key -n PageUp copy-mode -u

# Bind inside copy mode
bind-key -T copy-mode-vi v send-keys -X begin-selection

# Repeatable binding (stay in prefix mode)
bind-key -r H resize-pane -L 5

# Unbind a key
unbind-key C-b

# Unbind all
unbind-key -a
```

--------------------------------

### Install psmux via Winget

Source: https://psmux.pages.dev/README.md

Install psmux using the Windows Package Manager.

```bash
$winget install psmux
```

--------------------------------

### Define basic psmux configuration

Source: https://psmux.pages.dev/docs/configuration

Example configuration for ~/.psmux.conf covering prefix keys, mouse support, status bar styling, and key bindings.

```tmux
# Change prefix key to Ctrl+a
set -g prefix C-a

# Enable mouse
set -g mouse on

# Window numbering base (default is 0)
set -g base-index 1

# Customize status bar
set -g status-left "[#S] "
set -g status-right "%H:%M %d-%b-%y"
set -g status-style "bg=green,fg=black"

# Cursor style: block, underline, or bar
set -g cursor-style bar
set -g cursor-blink on

# Scrollback history
set -g history-limit 5000

# Prediction dimming (disable for apps like Neovim)
set -g prediction-dimming off

# Key bindings
bind-key -T prefix h split-window -h
bind-key -T prefix v split-window -v
```

--------------------------------

### Define Key Bindings

Source: https://psmux.pages.dev/docs/keybindings

Examples of binding keys to specific commands in different tables.

```text
bind-key t
```

```text
bind-key T
```

```text
bind-key -n <key>
```

```text
bind-key -T root <key>
```

```text
bind-key <key>
```

```text
bind-key -T copy-mode <key>
```

```text
bind-key -T copy-mode-vi <key>
```

--------------------------------

### Install psmux via Scoop

Source: https://psmux.pages.dev/README.md

Install psmux using the Scoop package manager.

```bash
$scoop install psmux
```

--------------------------------

### Status Bar Format Examples

Source: https://psmux.pages.dev/docs/pane-titles

Examples of status bar output showing the difference between a path-based title and a hostname-based title.

```text
"C:\Program Files\Powe" 19:39 17-Apr-26
```

```text
"DESKTOP-ABC1234" 19:39 17-Apr-26
```

--------------------------------

### Install psmux via PowerShell

Source: https://psmux.pages.dev/README.md

Use the provided one-liner to install the latest version of psmux.

```powershell
$irm https://raw.githubusercontent.com/psmux/psmux/master/scripts/install.ps1 | iex
```

--------------------------------

### Configure CI/CD Test Matrix

Source: https://psmux.pages.dev/docs/integration

Example GitHub Actions configuration for testing across both Linux and Windows environments.

```yaml
# GitHub Actions example
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    include:
      - os: ubuntu-latest
        mux: tmux
      - os: windows-latest
        mux: psmux

steps:
  - name: Install multiplexer
    run: |
      if [ "${{ matrix.mux }}" = "psmux" ]; then
        cargo install --git https://github.com/psmux/psmux
      else
        sudo apt-get install -y tmux
      fi
    shell: bash

  - name: Run integration tests
    run: python -m pytest tests/test_mux_integration.py
    env:
      PYTHONUTF8: "1"
```

--------------------------------

### Registering Event Hooks

Source: https://psmux.pages.dev/docs/integration

Basic examples of setting hooks for common session events like window creation, client attachment, and layout changes.

```bash
# Run a script when a new window is created
psmux set-hook -g after-new-window "run-shell 'echo window created >> events.log'"

# Notify on session attach
psmux set-hook -g client-attached "display-message 'Welcome back!'"

# Auto-layout on split
psmux set-hook -g after-split-window "select-layout tiled"
```

--------------------------------

### Install psmux via Chocolatey

Source: https://psmux.pages.dev/README.md

Install psmux using the Chocolatey package manager.

```bash
$choco install psmux
```

--------------------------------

### Start psmux Session

Source: https://psmux.pages.dev/docs/claude-code

Initialize a new psmux session to begin working with Claude Code.

```bash
psmux new-session -s work
```

--------------------------------

### Configure default shell in .psmux.conf

Source: https://psmux.pages.dev/docs/multi-shell

Examples of setting the default shell using absolute paths or system PATH resolution.

```bash
# Git Bash
set -g default-shell "C:/Program Files/Git/bin/bash.exe"

# Git Bash (backslashes work too)
set -g default-shell "C:\Program Files\Git\bin\bash.exe"

# Git Bash with login profile
set -g default-shell "C:/Program Files/Git/bin/bash.exe" --login

# cmd.exe
set -g default-shell cmd.exe

# PowerShell 7 (the default if nothing is set)
set -g default-shell pwsh

# Windows PowerShell 5
set -g default-shell powershell

# Nushell
set -g default-shell nu

# WSL default distro
set -g default-shell wsl
```

--------------------------------

### Create Startup Script for Background Services

Source: https://psmux.pages.dev/docs/use-cases

Use a PowerShell script to start or reuse a detached psmux session for background services like VPNs.

```powershell
# Start (or reuse) a detached psmux session that hosts the VPN
psmux has-session -t vpn 2>$null
if ($LASTEXITCODE -ne 0) {
    psmux new-session -d -s vpn -n tunnel -- openvpn --config C:\vpn\client.ovpn
}
```

--------------------------------

### Install Claude Code Globally

Source: https://psmux.pages.dev/docs/claude-code

Command to install the Claude Code CLI via npm.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Install psmux via Package Managers

Source: https://psmux.pages.dev/docs/integration

Commands to install psmux using common Windows package managers or Cargo.

```shell
# Cargo (recommended for developers)
cargo install --git https://github.com/psmux/psmux

# Scoop
scoop bucket add extras
scoop install psmux

# Winget
winget install psmux

# Chocolatey
choco install psmux
```

--------------------------------

### psmux Session Management Commands

Source: https://psmux.pages.dev/README.md

Common commands for starting, listing, attaching, and killing psmux sessions.

```bash
$psmux
$psmux new-session -s work
$psmux ls
$psmux attach -t work
$psmux kill-session -t work
```

--------------------------------

### Querying Format Variables

Source: https://psmux.pages.dev/docs/integration

Examples of how to retrieve specific format variables or user options using the psmux display-message command.

```APIDOC
## Querying Format Variables

### Description
Use the `display-message` command with the `-p` flag to output the value of a specific format variable or option.

### Usage
`psmux display-message -p "#{variable_name}"`

### Examples
```bash
psmux display-message -p "#{mouse}"            # Returns: on
psmux display-message -p "#{history-limit}"    # Returns: 2000
psmux display-message -p "#{@my-tool-state}"   # Returns: user option value
```
```

--------------------------------

### Control Mode Command Interaction

Source: https://psmux.pages.dev/docs/control-mode

Example of sending a command and receiving structured output in the control mode loop.

```text
list-windows
%begin 1700000000 1 1
0: pwsh* (1 panes) [120x30]
%end 1700000000 1 1
```

--------------------------------

### Conditional Key Binding

Source: https://psmux.pages.dev/docs/scripting

Example of using pattern matching to conditionally forward keys or select panes.

```bash
bind-key -n C-h if-shell -F "#{m/r:^(pwsh|n?vim)$,#{pane_current_command}}" \
  "send-keys C-h" "select-pane -L"
```

--------------------------------

### Targeting Sessions, Windows, and Panes

Source: https://psmux.pages.dev/docs/scripting

Examples of using the -t flag to target specific sessions, windows, or panes using names, indices, or stable IDs.

```bash
# Target a session by name
psmux has-session -t mysession
psmux switch-client -t mysession

# Target a session by stable id
psmux switch-client -t '$0'

# Window by index in a session
psmux select-window -t work:2

# Window by name in a session
psmux select-window -t work:editor

# Window by index in the current session
psmux select-window -t 3
psmux select-window -t :2

# Window by stable window id
psmux select-window -t @4

# Pane by stable pane id
psmux send-keys -t %3 "pwd" Enter

# Pane within a window in the current session
psmux select-pane -t :2.1              # window 2, pane 1

# Full session:window.pane path
psmux send-keys -t dev:0.2 "make build" Enter

# Relative targets
psmux select-pane -t +                 # next pane
psmux select-pane -t -                 # previous pane
psmux select-window -t !               # last (previous) window
```

--------------------------------

### Initialize New Windows

Source: https://psmux.pages.dev/docs/configuration

Set window names, working directories, and initial commands upon creation.

```bash
# New window with a specific name
new-window -n "logs"

# New window in a specific directory
new-window -c "C:\Projects"

# New window running a specific command with a name
new-window -n "build" -- cargo build --watch
```

--------------------------------

### Create new sessions

Source: https://psmux.pages.dev/docs/scripting

Initialize sessions with specific names, working directories, environment variables, or initial commands.

```bash
# Create a named session
psmux new-session -s work

# Create in a specific directory
psmux new-session -s project -c "C:\Projects\myapp"

# Create with environment variables
psmux new-session -s dev -e "NODE_ENV=development"

# Create in background (detached)
psmux new-session -d -s background

# Create with an initial command
psmux new-session -s monitor -- htop

# Create a session with a named first window
psmux new-session -s work -n "editor"
```

--------------------------------

### Configure plugins in .psmux.conf

Source: https://psmux.pages.dev/docs/plugins

Add plugin declarations and the initialization script to your configuration file to enable them.

```text
set -g @plugin 'psmux-plugins/ppm'
set -g @plugin 'psmux-plugins/psmux-sensible'
run '~/.psmux/plugins/ppm/ppm.ps1'
```

--------------------------------

### Manage Bold Is Bright via CLI

Source: https://psmux.pages.dev/docs/configuration

Runtime configuration and inspection of the bold-is-bright setting.

```bash
psmux set-option -g bold-is-bright off
psmux show-options -g bold-is-bright
psmux display-message -p '#{bold-is-bright}'
```

--------------------------------

### Create windows with specific options

Source: https://psmux.pages.dev/docs/scripting

Configure new windows with custom names, directories, or initial commands. Setting a name with -n disables automatic renaming.

```bash
# Create a window with a name
psmux new-window -n "logs"

# Create a window in the background (don't switch to it)
psmux new-window -d -n "background"

# Create a window in a specific directory
psmux new-window -c "C:\Projects\myapp"

# Create a window running a command
psmux new-window -n "build" -- cargo watch

# Create a window at a specific index
psmux new-window -t 5
```

--------------------------------

### Spawn Server with Session Group

Source: https://psmux.pages.dev/docs/configuration

Initializes a server instance directly into a specific session group.

```bash
psmux server -g work
```

--------------------------------

### Manage Detached Sessions

Source: https://psmux.pages.dev/docs/use-cases

Start a session in the background and re-attach to it later from any terminal window.

```bash
# Start a session in the background (no window opens)
psmux new-session -d -s work

# ...do other things, close terminals, even sign out...

# Later, from any terminal, jump back in exactly where it was
psmux attach -t work
```

--------------------------------

### Configure Split Window Options

Source: https://psmux.pages.dev/docs/configuration

Control pane orientation, size, working directory, and initial commands when splitting windows.

```bash
# Split vertically, new pane takes 30% of the space
split-window -v -p 30

# Split horizontally, new pane takes 70% of the space
split-window -h -p 70

# Split and start in a specific directory
split-window -v -c "C:\Projects\myapp"

# Split and start in the current pane's directory
split-window -h -c "#{pane_current_path}"

# Split and run a specific command
split-window -v -- python
```

--------------------------------

### Asynchronous Notifications

Source: https://psmux.pages.dev/docs/control-mode

The server sends asynchronous notifications starting with '%' to inform the client of state changes.

```APIDOC
## Asynchronous Notifications

### Description
Notifications are asynchronous messages sent by the server between command response blocks. They indicate changes in windows, sessions, pane output, or client status.

### Common Notifications
- **Window Notifications**: `%window-add @<WID>`, `%window-close @<WID>`, `%window-renamed @<WID> <name>`
- **Session Notifications**: `%session-changed $<SID> <name>`, `%session-renamed <name>`
- **Pane Output**: `%output %<PID> <escaped_data>`
- **Flow Control**: `%pause %<PID>`, `%continue %<PID>`
- **Client/Buffer**: `%client-detached <client>`, `%paste-buffer-changed <name>`
- **Exit**: `%exit` or `%exit <reason>`
```

--------------------------------

### new-window

Source: https://psmux.pages.dev/docs/scripting

Creates a new window with optional naming, directory setting, or initial command execution.

```APIDOC
## psmux new-window

### Description
Creates a new window. Setting a name with -n disables automatic renaming.

### Parameters
- **-n** (string) - Optional - Set window name
- **-d** (flag) - Optional - Create in background
- **-c** (string) - Optional - Start directory
- **-t** (integer) - Optional - Specific index
- **--** (command) - Optional - Initial command to run
```

--------------------------------

### Build the project from source

Source: https://psmux.pages.dev/README.md

Command to compile the project in release mode using Cargo.

```powershell
PS C:\dev\psmux❯cargo build --release
Compiling psmux v3.3.2
Finished release [optimized] in 12.4s
```

--------------------------------

### Verify Command Aliases

Source: https://psmux.pages.dev/docs/scripting

List configured command aliases using show-options.

```bash
psmux show-options | Select-String command-alias
# command-alias "sph=split-window -h"
```

--------------------------------

### Automating interactive console programs

Source: https://psmux.pages.dev/docs/use-cases

Uses send-keys and capture-pane to interact with programs requiring a real console, such as REPLs or installers.

```powershell
# Start a Python REPL detached
psmux new-session -d -s repl -- python

# Feed it statements
psmux send-keys -t repl "import platform; print(platform.system())" Enter
Start-Sleep -Milliseconds 200

# Read the answer back
psmux capture-pane -p -t repl -S -5

# Clean up
psmux kill-session -t repl
```

--------------------------------

### Configuration and Hook Commands

Source: https://psmux.pages.dev/docs/control-mode

Commands for managing options, hooks, and key bindings.

```text
set-option -g status-style "bg=blue"              # Set an option
show-options -g                                     # Show all global options
set-hook -g after-new-window "display-message hi"  # Set a hook
bind-key M-x display-message "pressed!"            # Bind a key
```

--------------------------------

### Manage sessions and windows via CLI

Source: https://psmux.pages.dev/

Common command-line operations for creating, attaching, and listing sessions or windows.

```bash
PS C:\dev\psmux❯psmux new-session -s dev
✓ session "dev" created
PS C:\dev\psmux❯cargo build --release
Compiling psmux v3.3.2
Finished release [optimized] in 12.4s
PS C:\dev\psmux❯_
```

```bash
$ psmux attach -t dev
● attached
$ psmux list-windows
0: editor (2 panes)
1: server (running)
2: logs
```

--------------------------------

### Session and Window Management Commands

Source: https://psmux.pages.dev/docs/control-mode

Commands for creating, splitting, killing, and navigating windows and panes.

```text
new-window                     # Create a new window
new-window -n editor           # Create a named window
split-window -v                # Split vertically
split-window -h                # Split horizontally
kill-pane                      # Kill the active pane
kill-window                    # Kill the active window
select-window -t 1             # Switch to window 1
select-pane -t %3              # Switch to pane %3
rename-window new-name         # Rename the active window
rename-session new-name        # Rename the session
```

--------------------------------

### Run long-lived background jobs

Source: https://psmux.pages.dev/docs/use-cases

Start a detached session to ensure processes continue running after RDP disconnects or terminal closure.

```powershell
# Start the long job detached
psmux new-session -d -s build -- pwsh -c "cargo build --release; Write-Host DONE"

# Disconnect RDP, go home, come back tomorrow...

# Reattach and check on it
psmux attach -t build
```

--------------------------------

### Run psmux-ssh.sh wrapper

Source: https://psmux.pages.dev/docs/mouse-ssh

Use the wrapper script on macOS or Linux to connect to a Windows host. SSH options can be passed after the double dash.

```bash
sh psmux-ssh.sh --session work -- user@windows-host

# A named psmux socket/namespace:
sh psmux-ssh.sh --socket project --session work -- user@windows-host

# SSH options are passed through after `--`:
sh psmux-ssh.sh --session work -- -p 2222 user@windows-host
```

--------------------------------

### Test specific remote psmux executable

Source: https://psmux.pages.dev/docs/mouse-ssh

Explicitly define the path to the remote psmux executable when testing builds that are not yet installed on the system path.

```bash
sh psmux-ssh.sh --session work \
  --psmux C:/path/to/psmux.exe -- user@windows-host
```

--------------------------------

### Quote Option Values in psmux

Source: https://psmux.pages.dev/docs/configuration

Use quotes to preserve spaces in option values. These examples demonstrate setting the status-right option with specific spacing.

```bash
# Both of these store the twelve spaces
set -g status-right "left            right"
```

```bash
psmux set -g status-right "left            right"
```

--------------------------------

### Launch psmux in iTerm2 Control Mode

Source: https://psmux.pages.dev/docs/iterm2-control-mode

Configures the local TTY and initiates an SSH connection to the Windows host to start psmux in control mode.

```bash
stty raw -echo -isig
ssh -T user@windows-host 'C:/path/to/psmux.exe -CC'
```

--------------------------------

### Register Background Task in Windows Task Scheduler

Source: https://psmux.pages.dev/docs/use-cases

Register a PowerShell script as a startup task to ensure the psmux session starts automatically under the user account.

```powershell
# Run once, elevated, to register the task
$action  = New-ScheduledTaskAction -Execute "pwsh.exe" `
    -Argument "-NoProfile -WindowStyle Hidden -File C:\scripts\start-vpn.ps1"
$trigger = New-ScheduledTaskTrigger -AtStartup
$principal = New-ScheduledTaskPrincipal -UserId "$env:USERNAME" -LogonType S4U -RunLevel Highest

Register-ScheduledTask -TaskName "psmux-vpn" -Action $action `
    -Trigger $trigger -Principal $principal
```

--------------------------------

### Read configuration options using format variables

Source: https://psmux.pages.dev/docs/scripting

Use the #{...} syntax to resolve option names directly into format strings without parsing command output.

```bash
psmux display-message -p "#{status-left}"      # [#S]
psmux display-message -p "#{mouse}"            # on
psmux display-message -p "#{history-limit}"    # 2000
```

--------------------------------

### Configure Dedicated Tool Windows

Source: https://psmux.pages.dev/docs/multi-shell

Binds keys to launch specific tools or SSH sessions in new windows.

```bash
# Quick launch for common tools
bind-key P new-window python
bind-key J new-window node
bind-key S new-window "C:/Program Files/Git/bin/bash.exe" -c "ssh myserver"
```

--------------------------------

### Configure Chooser Preview

Source: https://psmux.pages.dev/docs/configuration

Set the default visibility for the live preview pane in session and tree choosers.

```bash
# Open all choosers with the preview pane already visible
set -g choose-tree-preview on
```

--------------------------------

### Configuring Window and Pane Numbering

Source: https://psmux.pages.dev/docs/configuration

Settings to change the starting index for windows and panes. These settings affect pane targets, format variables, and status bar labels.

```conf
# Start window numbering at 1
set -g base-index 1

# Start pane numbering at 1
set -g pane-base-index 1
```

```conf
set -g base-index 1
set -g pane-base-index 1
```

--------------------------------

### Configure Vi-style selection behavior

Source: https://psmux.pages.dev/docs/keybindings

Rebinds the 'v' key in copy-mode-vi to start a character selection, overriding the default rectangle-toggle behavior to match standard Vi muscle memory.

```text
bind-key -T copy-mode-vi v send-keys -X begin-selection
```

--------------------------------

### Retrieve pane and window information

Source: https://psmux.pages.dev/docs/scripting

Commands to list session components and capture or display pane content.

```bash
# List all panes in current window
psmux list-panes

# List all windows
psmux list-windows

# Capture pane content
psmux capture-pane

# Display formatted message with variables
psmux display-message "#S:#I:#W"   # Session:Window Index:Window Name
```

--------------------------------

### Integrate psmux with Go

Source: https://psmux.pages.dev/docs/integration

Uses os/exec to run tmux commands and return output as a string.

```go
package main

import (
    "fmt"
    "os/exec"
    "strings"
)

func muxCmd(args ...string) (string, error) {
    out, err := exec.Command("tmux", args...).Output()
    return strings.TrimSpace(string(out)), err
}

func main() {
    muxCmd("new-session", "-d", "-s", "dev", "-x", "120", "-y", "30")
    muxCmd("send-keys", "-t", "dev", "echo hello", "Enter")
    content, _ := muxCmd("capture-pane", "-t", "dev", "-p")
    fmt.Println(content)
    muxCmd("kill-session", "-t", "dev")
}
```

--------------------------------

### Kill Server Scoping

Source: https://psmux.pages.dev/docs/compatibility

Demonstrates the difference between global and namespaced server termination commands.

```bash
psmux kill-server            # kills ALL sockets and ALL sessions (default + every -L namespace)
psmux -L work kill-server    # kills ONLY the "work" socket; other sockets keep running
```

--------------------------------

### List supported psmux commands

Source: https://psmux.pages.dev/docs/faq

Run this command to see the full list of tmux-compatible commands supported by the current build.

```bash
psmux list-commands
```

--------------------------------

### Run multiple AI agents side by side

Source: https://psmux.pages.dev/docs/use-cases

Initialize a session with multiple windows, each running a different AI agent for simultaneous monitoring.

```bash
psmux new-session -d -s agents -n claude   -- claude
psmux new-window  -t agents -n opencode    -- opencode
psmux new-window  -t agents -n aider       -- aider
psmux new-window  -t agents -n pi          -- pi
psmux attach -t agents
```

--------------------------------

### Managing Sessions and Panes

Source: https://psmux.pages.dev/docs/scripting

Commands for session lifecycle management, navigation, and pane respawning.

```bash
# Check if session exists (exit code 0 = exists)
psmux has-session -t mysession

# Rename session
psmux rename-session newname

# Switch to another session
psmux switch-client -t other-session

# Cycle through sessions
psmux switch-client -n          # Next session
psmux switch-client -p          # Previous session
psmux switch-client -l          # Last (most recently used) session

# Create a session with environment variables
psmux new-session -s work -e "MY_VAR=value"

# Respawn pane (restart shell, or restart with a different command)
psmux respawn-pane
psmux respawn-pane -k           # Kill the current process first
psmux respawn-pane -c /tmp      # Restart in a different directory
```

--------------------------------

### Basic libtmux Usage

Source: https://psmux.pages.dev/docs/integration

Connect to the psmux server and perform common operations like listing sessions, creating windows, and sending commands.

```python
import libtmux

# Connect to the psmux server
server = libtmux.Server(socket_name="default")

# List sessions
for session in server.sessions:
    print(f"{session.name} ({session.id}): {len(session.windows)} windows")

# Work with a session
session = server.sessions[0]

# Create a window
window = session.new_window(window_name="build")

# Access panes
pane = window.panes[0]

# Send commands
pane.send_keys("cargo build")

# Capture output
lines = pane.capture_pane()
for line in lines:
    print(line)

# Kill the window
window.kill()
```

--------------------------------

### Initialize Control Mode

Source: https://psmux.pages.dev/docs/integration

Establishes a persistent, event-driven connection to psmux using subprocess and threading to handle asynchronous output.

```python
import subprocess
import threading

proc = subprocess.Popen(
    ["psmux", "-CC"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
    encoding="utf-8",
)

def reader():
    for line in proc.stdout:
        line = line.rstrip("\n")
        if line.startswith("%output"):
            _, pane_id, *data = line.split(" ", 2)
            print(f"[{pane_id}] {data[0] if data else ''}")
        elif line.startswith("%window-add"):
            print(f"Window created: {line}")
        elif line.startswith("%session-changed"):
            print(f"Session changed: {line}")

t = threading.Thread(target=reader, daemon=True)
t.start()

# Send commands
proc.stdin.write("list-windows\n")
proc.stdin.flush()

proc.stdin.write("new-window -n monitor\n")
proc.stdin.flush()

proc.stdin.write('send-keys "Get-Process" Enter\n')
proc.stdin.flush()
```

--------------------------------

### Creating Interactive Menus

Source: https://psmux.pages.dev/docs/scripting

Commands for rendering interactive menus with titles, key bindings, and associated actions.

```bash
# Display an interactive menu
# Format: display-menu [-x x] [-y y] [-T title] name key command ...
psmux display-menu -T "Actions" \
  "New Window" n "new-window" \
  "Split Horizontal" h "split-window -h" \
  "Split Vertical" v "split-window -v" \
  "Close Pane" x "kill-pane"

# Position the menu at specific coordinates
psmux display-menu -x 10 -y 5 -T "Quick" \
  "Zoom" z "resize-pane -Z" \
  "Rename" r "command-prompt -I '#W' 'rename-window %%'"
```

--------------------------------

### Displaying Popups

Source: https://psmux.pages.dev/docs/scripting

Commands for opening and configuring popup windows with specific dimensions, directories, and exit behaviors.

```bash
# Open a popup running a command
psmux display-popup "Get-Process"

# Set width and height (absolute or percentage)
psmux display-popup -w 80% -h 50% "htop"

# Set the starting directory
psmux display-popup -d "C:\Projects" -w 100 -h 30

# Close popup on command exit (default behavior, -E inverts it)
psmux display-popup -E "git log --oneline -20"

# Keep popup open after command finishes
psmux display-popup -K "echo done"
```

--------------------------------

### Test with empty configuration

Source: https://psmux.pages.dev/docs/diagnostics

Verifies if an issue persists when using a default, empty configuration.

```shell
psmux -f NUL new-session
```

--------------------------------

### Pane Management

Source: https://psmux.pages.dev/docs

Commands for splitting and configuring panes.

```bash
split-window -v -p 30
```

```bash
split-window -c "#{pane_current_path}"
```

```bash
bind-key '"' split-window -v -c "#{pane_current_path}"
```

--------------------------------

### List active windows

Source: https://psmux.pages.dev/README.md

Command to display all windows within the current session.

```bash
$ psmux list-windows
0: editor (2 panes)
1: server (running)
2: logs
```

--------------------------------

### Appending and Verifying Hooks

Source: https://psmux.pages.dev/docs/integration

Demonstrates appending a hook to existing handlers and verifying the current hook configuration.

```bash
psmux set-hook -ga after-new-window "run-shell 'my-tool notify window'"
psmux show-hooks
# after-new-window[0] -> select-layout tiled
# after-new-window[1] -> run-shell 'my-tool notify window'
```

--------------------------------

### Index Configuration

Source: https://psmux.pages.dev/docs

Set base indices for panes and windows.

```bash
set -g pane-base-index 1
```

```bash
set -g base-index 1
```

--------------------------------

### Configure Mouse Interaction

Source: https://psmux.pages.dev/docs/configuration

Global settings to toggle mouse support, scroll behavior, and selection modes.

```bash
# Disable mouse entirely (no click, scroll, or drag)
set -g mouse off

# Disable entering copy mode on mouse scroll
set -g scroll-enter-copy-mode off

# Enable tmux-like release-copy selection with pane clipping
# Double-click selects a word, triple-click selects a line
set -g pwsh-mouse-selection on
```

--------------------------------

### Influence Agent Selection via Project Instructions

Source: https://psmux.pages.dev/docs/claude-code

Add these instructions to CLAUDE.md to encourage the model to use the teammate system instead of worktree isolation.

```markdown
# Agent Configuration
When spawning subagents, always use the teammate system (team_name + name parameters)
instead of worktree isolation. This ensures agents are visible in tmux panes.
Do NOT use isolation: "worktree". Use teammates instead.
```

--------------------------------

### Command-line psmux equivalents

Source: https://psmux.pages.dev/docs/iterm2-control-mode

Direct replacements for standard tmux control mode commands.

```bash
psmux -CC
```

```bash
psmux -CC new -A -s work
```

```bash
psmux -CC attach -t work
```

--------------------------------

### Configure Key Bindings

Source: https://psmux.pages.dev/docs/scripting

Manage key mappings using bind-key and unbind-key, supporting custom tables, repeat behavior, and format variables.

```bash
# Bind a key in the default prefix table
psmux bind-key h split-window -h

# Bind with format variable expansion (-F flag)
psmux bind-key -F M-h "resize-pane -L #{pane_width}"

# Bind with repeat (successive presses within repeat-time don't need prefix)
psmux bind-key -r Left select-pane -L
psmux bind-key -r Right select-pane -R

# Bind in root table (no prefix needed)
psmux bind-key -n M-Left select-pane -L

# Bind in a specific key table
psmux bind-key -T copy-mode-vi y send-keys -X copy-selection

# Unbind a single key
psmux unbind-key h

# Unbind ALL keys (reset to clean slate)
psmux unbind-key -a

# Unbind all keys in a specific key table only
psmux unbind-key -a -T copy-mode-vi
psmux unbind-key -a -T prefix
psmux unbind-key -a -T root
psmux unbind-key -a -T copy-mode
```

--------------------------------

### Scripting a reproducible development environment

Source: https://psmux.pages.dev/docs/use-cases

Automates the launch of multiple windows and panes for editors, servers, and log watchers in a single session.

```powershell
$proj = "C:\Projects\myapp"
psmux new-session  -d -s myapp -n edit  -c $proj -- nvim
psmux new-window   -t myapp   -n server -c $proj -- pwsh -c "npm run dev"
psmux new-window   -t myapp   -n build  -c $proj -- pwsh -c "cargo watch -x build"
psmux split-window -t myapp:build -v -c $proj -- pwsh -c "Get-Content .\dev.log -Wait"
psmux select-window -t myapp:edit
psmux attach -t myapp
```

--------------------------------

### Configure Cross-Platform Testing Keys

Source: https://psmux.pages.dev/docs/multi-shell

Binds function keys to launch different shell environments for testing purposes.

```bash
bind-key F1 new-window pwsh
bind-key F2 new-window "C:/Program Files/Git/bin/bash.exe"
bind-key F3 new-window cmd.exe
bind-key F4 new-window wsl
```

--------------------------------

### Verify Preview Option

Source: https://psmux.pages.dev/docs/preview

Check the current status of the choose-tree-preview option.

```powershell
psmux show-options -g | Select-String choose-tree-preview
```

--------------------------------

### Query lists with custom formats

Source: https://psmux.pages.dev/docs/scripting

Retrieve session, window, and pane information using the -F flag to define custom output formats.

```bash
# List all sessions with custom format
psmux list-sessions -F "#{session_name}:#{session_windows}"

# List all windows with custom format
psmux list-windows -F "#{window_index}:#{window_name}:#{window_panes}"

# List all panes across the session (-s flag)
psmux list-panes -s -F "#{window_index}.#{pane_index}: #{pane_current_command} [#{pane_width}x#{pane_height}]"

# List all panes across all sessions (-a flag)
psmux list-panes -a

# Capture pane content to stdout
psmux capture-pane -p -t %0

# Capture with line range (negative = scrollback)
psmux capture-pane -p -S -100 -E -1

# Print a format variable
psmux display-message -p "#{pane_current_path}"
```

--------------------------------

### Window Naming

Source: https://psmux.pages.dev/docs

Configure window naming behavior.

```bash
new-window -n "myname"
```

```bash
set -g automatic-rename off
```

```bash
set -w automatic-rename off
```

--------------------------------

### Execute Copy Mode Commands via Script

Source: https://psmux.pages.dev/docs/scripting

Demonstrates how to drive copy mode programmatically using the psmux CLI.

```bash
# Drive copy mode from a script
psmux copy-mode
psmux send-keys -X history-top
psmux send-keys -X begin-selection
psmux send-keys -X cursor-down
psmux send-keys -X copy-selection-and-cancel
```

--------------------------------

### Specify custom configuration file

Source: https://psmux.pages.dev/docs/configuration

Use the -f flag to override default configuration search paths or provide an empty configuration.

```bash
# Use a specific config file instead of default search
psmux -f ~/.config/psmux/custom.conf

# Use an empty config (no settings loaded)
psmux -f NUL
```

--------------------------------

### Create Sessions with Different Shells

Source: https://psmux.pages.dev/docs/multi-shell

Commands to initialize separate psmux sessions, each configured with a specific default shell or environment.

```bash
# Session for PowerShell work
psmux new-session -d -s work

# Session for Linux/bash work
psmux new-session -d -s linux -- wsl

# Session for a specific project using bash
psmux new-session -d -s webapp -- "C:/Program Files/Git/bin/bash.exe" --login
```

--------------------------------

### Configure default shell and key bindings in .psmux.conf

Source: https://psmux.pages.dev/docs/multi-shell

Define persistent shell defaults and custom key bindings for launching specific shells.

```psmux
# Default shell is PowerShell
set -g default-shell pwsh

# Bind keys to quickly open specific shells
bind-key B new-window "C:/Program Files/Git/bin/bash.exe"
bind-key C new-window cmd.exe
bind-key W new-window wsl
bind-key N new-window nu

# Bind keys for splitting with a specific shell
bind-key b split-window -v "C:/Program Files/Git/bin/bash.exe"
bind-key c split-window -v cmd.exe
```

--------------------------------

### Remove and inspect hooks

Source: https://psmux.pages.dev/docs/scripting

Use the -u flag to unset hooks and show-hooks to verify the current configuration.

```bash
# Remove a global hook
psmux set-hook -gu after-new-window

# View all active hooks
psmux show-hooks
```
Tokens:
Raw