Install and load a workspace

Java

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

libtmux-workspace 0.0.1-alpha.12-SNAPSHOT · Source

Build and run the native Java 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 JDK 21 or newer and the repository’s Gradle wrapper. The local application distribution includes its Java dependencies and needs Java on PATH, or JAVA_HOME set to a compatible JDK.

$ ./gradlew :workspace-cli:installDist \
    --max-workers=2 \
    --no-parallel

Keep the generated distribution together: its launcher uses libraries beside it. This local application distribution is separate from published Java library artifacts.

Inspect the built command:

$ workspace-cli/build/install/tmux-workspace/bin/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:

$ workspace-cli/build/install/tmux-workspace/bin/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:

$ workspace-cli/build/install/tmux-workspace/bin/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

Human load progress uses terminal stderr, with five presets or a custom --progress-format and a bounded --progress-lines panel. It preserves script stdout/stderr, clears on completion or interruption, and is disabled for machine output, redirected stderr, TERM=dumb, --no-progress or TMUXP_PROGRESS=0.

Python plugins and custom builders execute through the checked tmuxp bridge. Extension append rejects documents containing before_script to preserve the borrowed session. Complete configuration/capture coverage and full terminal/platform acceptance remain unfinished. Progress uses the initial terminal dimensions; it does not track resizing, and Unicode clipping is conservative.

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.