Install and load a workspace

Edit this page on GitHub

@libtmux/workspace 0.1.0-alpha.10 · Source

Install and run the native TypeScript tmux-workspace command from its npm prerelease, @libtmux/workspace-cli. This is a partial, prerelease implementation.

Install from npmLink to section

Use a Unix environment with tmux 3.2a or newer on PATH for this walkthrough.

The command runs on Node.js 22.12 or newer, or Bun 1.3.14 or newer. Install it globally with npm:

$ npm install -g @libtmux/workspace-cli

The package puts tmux-workspace on PATH. To run it without installing, use npx -y @libtmux/workspace-cli wherever this walkthrough runs tmux-workspace. The overview lists the Bun, pnpm and Yarn runners and global installs.

Inspect the installed 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

Interactive prompts and complete configuration/platform acceptance remain unfinished. Capture reports live state rather than recovering the original workspace commands or extension intent.

Python shell evaluation and explicit plugin/custom-builder loads require an interpreter with tmuxp 1.74.0 installed. Select it with TMUX_WORKSPACE_PYTHON; the default is python3. Install extension packages in that interpreter or provide workspace_builder_paths relative to the workspace file. See hooks and builders for append and failure behavior. 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.