Install and load a workspace

Python
Ruby Unavailable
Lua Unavailable
TypeScript
Rust
Go
Java
.NET
C++
Swift

github.com/libtmux/libtmux-go/workspace · Source

Build and run the native Go 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 Go 1.26 or newer, as required by the checkout’s workspace module. Build from the repository root so its Go workspace selects the local modules.

$ GOMAXPROCS=2 go build \
    -p 2 \
    -o tmux-workspace \
    ./workspace/cmd/tmux-workspace

Ordinary search uses Go regular expressions. Python-only regex behavior is explicitly selected with --regex-engine python; it checks Python 3.10 or newer. Python shell and plugin/custom-builder execution require tmuxp 1.74.0. Plugin append uses the current session when the document has no before_script key. Native before-script arguments validate for all inputs before any session is created or changed.

Inspect the built command:

$ ./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:

$ ./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:

$ ./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

Append through the Python workspace bridge with a document before_script key is unavailable and fails during preflight, including empty or null values. This prevents Python’s script-failure cleanup from deleting the borrowed session. Native scripted append remains supported.

load -s changes only the final input’s session name; earlier inputs keep their configured names. Legacy -8 and --88-colors fail before workspace lookup or runtime checks. Use -2 to request 256-color mode.

Some cleanup and interruption paths, diagnostic filtering, complete configuration coverage, and portable packaging still need work. Capture cannot reconstruct original command arguments, history or workspace extensions.

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.