Install and load a workspace

Edit this page on GitHub

TmuxWorkspace 0.1.0-alpha.5 · Source

Build and run the native Swift tmux-workspace command from the local workspace-cli checkout. This is a partial, unreleased implementation. These commands require that local source; they are not registry installation instructions or a claim that the CLI is available on the published branch.

Build from the local checkoutLink to section

Run these commands from the native repository root. Use a Unix environment with tmux 3.2a or newer on PATH for this walkthrough.

Use Swift 6.2 or newer on Linux. On macOS, use Xcode’s Swift 6.3 or newer toolchain; the subprocess dependency requires it. The package targets macOS 13 or newer. Enable the YAML build trait for this walkthrough; JSON-only builds can omit it.

$ swift build \
    --jobs 2 \
    --traits YAMLWorkspaces \
    --force-resolved-versions \
    --product tmux-workspace

Outside tmux, this local loader requires an explicit endpoint. The walkthrough supplies one with -S. A copied Linux executable still needs the Swift runtime libraries supplied by its toolchain; it is not a standalone distribution.

Inspect the built command:

$ .build/debug/tmux-workspace --help

Create the inputLink to section

Keep this shell open for the walkthrough. Create a temporary directory for its configuration and private tmux socket:

$ WORKSPACE_TMP="$(mktemp -d)"

Write a minimal configuration with two blank shell panes to workspace.yaml inside that directory:

$ cat > "$WORKSPACE_TMP/workspace.yaml" <<'YAML'
session_name: workspace-guide
windows:
  - window_name: editor
    layout: even-horizontal
    panes: [null, null]
YAML

Load and inspectLink to section

Load detached on the temporary socket. The JSON result describes the load; -d prevents terminal attachment:

$ .build/debug/tmux-workspace load \
    -S "$WORKSPACE_TMP/tmux.sock" \
    -d \
    --json \
    "$WORKSPACE_TMP/workspace.yaml"

Inspect the two panes through the same endpoint:

$ tmux \
    -S "$WORKSPACE_TMP/tmux.sock" \
    list-panes \
    -t '=workspace-guide:editor'

Attach with tmux when ready:

$ tmux \
    -S "$WORKSPACE_TMP/tmux.sock" \
    attach-session \
    -t '=workspace-guide'

Detach with your configured tmux detach binding. Capture the live session without choosing a file destination:

$ .build/debug/tmux-workspace freeze \
    -S "$WORKSPACE_TMP/tmux.sock" \
    --json \
    workspace-guide

Capture reports recoverable live state. It cannot reconstruct the original command history, script or plugin definitions. Remove the walkthrough session when finished:

$ tmux \
    -S "$WORKSPACE_TMP/tmux.sock" \
    kill-session \
    -t '=workspace-guide'

The configuration remains in the temporary directory until you remove it. Every tmux command above addresses that private socket.

Current limitsLink to section

load -2 forces 256-color handling in native tmux clients. Legacy -8 is recognized but rejected before document lookup because supported tmux versions do not implement 88-color mode. Without -2, tmux detects color support.

--log-level filters advisory diagnostics; fatal errors remain visible. load --log-file appends structured lifecycle and diagnostic records to a regular file. A write failure reports a secondary diagnostic and preserves the load result.

Human load displays progress on terminal stderr, with presets, custom counters and a bounded recent-output panel. It uses the initial terminal size and conservative Unicode clipping. Bootstrap output keeps its original stdout or stderr destination, but is collected before display. Machine output disables the panel and emits structured window/pane events. Interruption clears the panel; SIGINT and SIGTERM return status 130 and stop captured children.

Terminal attachment, plugins/custom builders, further pane/window execution settings, fuller capture, generated manuals and portable distribution remain unfinished. The complete tmuxp flag surface is not available.

Python-specific shell behavior requires an interpreter with tmuxp 1.74.0 installed. Select it with TMUX_WORKSPACE_PYTHON. Ordinary native loading of this example does not require Python.

Python alternativeLink to section

For the separate released tmuxp application, install its isolated Python tool environment with uv:

$ uv tool install tmuxp

Follow the Python installation guide for that workflow. Installing tmuxp does not install the native command.

ContinueLink to section

Discovery, configuration and the load reference explain the tmuxp compatibility model. Compare those references with the local command’s help and the limits above. Export and reload explains the capture workflow, and the compatibility reference records builder gaps. Use Internals for the library and consumer APIs.

tmuxp reference source.