tmux workspace manager, forged in Java.

Session manager for tmux. Load, freeze, and convert tmux sessions through YAML/JSON configuration files. Powered by libtmux for Java.

Install

Install the workspace package separately from the core library.

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

tmux-workspace creates tmux sessions from YAML or JSON. A file describes windows, panes, commands, directories and environment. Load it from a terminal or request machine output for automation.

Load a workspace from the terminal¶

1. Install the command and load a workspace.
2. Configure windows and panes.
3. Capture and reload a session.

The CLI manual covers discovery, search, editing, loading, capture, conversion and import. Examples provide complete configurations with their prerequisites.

Automate and inspect¶

Use $load -d when the caller should return without attaching. --json returns a result, and --ndjson supports a stream of records. Read automation for retry and cleanup decisions and errors for failure handling.

Loaded workspaces are ordinary tmux sessions. Select the same socket when inspecting them from tmux or the MCP server.

Build from application code¶

The workspace library has its own API and configuration contract. Use it when a program needs direct control over construction. The CLI task guides here describe the tmux-workspace executable and link to its documented source revision.

CLI source.

Tested example workspace files for this port are coming.