Build a workspace from a file

A tmux command file can create a session, arrange its windows, and split its panes. This example builds two windows with three panes, prints their names and pane counts, then removes its private server. It requires tmux 3.2 or newer and a POSIX shell.

Define the layout¶

Save this command file:

new-session -d -s dev -n editor -x 100 -y 30 'sh'
split-window -h -t '=dev:editor' 'sh'
new-window -t '=dev' -n logs 'sh'
select-window -t '=dev:editor'
select-pane -t '=dev:editor.0'

The editor window has two panes; logs has one. Each pane starts sh. Explicit targets keep each command tied to the intended session and window.

Build and inspect it¶

Save this complete program as workspace.sh beside the configuration file:

(
    set -eu
    directory=$(mktemp -d "${TMPDIR:-/tmp}/libtmux-workspace.XXXXXX")
    socket="$directory/tmux.sock"

    cleanup() {
        status=$?
        trap - EXIT
        if [ -S "$socket" ] && ! tmux -S "$socket" kill-server; then
            printf '%s\n' "Cannot stop tmux; kept $directory." >&2
            exit 1
        fi
        rm -rf "$directory" || status=$?
        exit "$status"
    }
    trap cleanup EXIT
    trap 'exit 1' HUP INT TERM

    tmux -S "$socket" -f /dev/null start-server \; \
        set-option -s exit-empty off
    tmux -S "$socket" source-file ./workspace.conf
    tmux -S "$socket" list-windows -t '=dev' \
        -F '#{window_name}: #{window_panes} panes'
)

Run it from that directory:

$ sh workspace.sh

The result is:

editor: 2 panes
logs: 1 panes

source-file executes the configuration on the private server. Setting exit-empty to off keeps that server available for cleanup even when a configuration error prevents session creation. Errors remain visible and make the program fail. Cleanup runs after partial creation too; if stopping tmux fails, the script keeps the socket directory and reports its location.

Use a workspace manager¶

For YAML or JSON configuration, validation, and language APIs, choose a port:

Python CLI · TypeScript · Go · Rust · Java · C# · C++ · Swift

The workspace concept guide explains configuration and ownership. The capture example shows how to wait for pane output after sending a command.

The tmux manual source describes source-file, window targets, and exit-empty.