# TypeScript-based tmux workspace manager

Source: https://libtmux.org/en/ts/latest/workspace/

> Describe a tmux session in a file, then load, inspect and capture it.

**Workspace Manager concept example** A working example of the core library. It can change without notice. The `tmux-workspace` CLI is published to npm, numbered 0.1.N. Pin its version when automation depends on its output.



`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](https://libtmux.org/en/ts/latest/workspace/guides/installation/).
2. [Configure windows and panes](https://libtmux.org/en/ts/latest/workspace/configuration/).
3. [Capture and reload a session](https://libtmux.org/en/ts/latest/workspace/guides/export-session/).

The [CLI manual](https://libtmux.org/en/ts/latest/workspace/cli/) covers discovery, search, editing, loading,
capture, conversion and import. [Examples](https://libtmux.org/en/ts/latest/workspace/examples/gallery/) provide
complete configurations with their prerequisites.

## Automate and inspect

Use [`load -d`](https://libtmux.org/en/ts/latest/workspace/cli/load/) when the caller should return without attaching. `--json` returns
a result, and `--ndjson` supports a stream of records. Read
[automation](https://libtmux.org/en/ts/latest/workspace/guides/automation/) for retry and cleanup decisions and
[errors](https://libtmux.org/en/ts/latest/workspace/reference/exit-codes/) for failure handling.

Loaded workspaces are ordinary tmux sessions. Select the same socket when
inspecting them from tmux or the [MCP server](https://libtmux.org/en/ts/latest/mcp/).

## Build from application code

The [workspace library](https://libtmux.org/en/ts/latest/workspace/internals/) 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](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md).


- [CLI Manual](https://libtmux.org/en/ts/latest/workspace/cli/): Commands, options and machine output.
- [Configuration](https://libtmux.org/en/ts/latest/workspace/configuration/): Workspace fields, normalization and execution.
- [Install and load](https://libtmux.org/en/ts/latest/workspace/guides/installation/): Load a workspace on a private socket, then capture it.
- [Example gallery](https://libtmux.org/en/ts/latest/workspace/examples/gallery/): Workspace files to start from, with their prerequisites.
- [Runtime support](https://libtmux.org/en/ts/latest/workspace/reference/compatibility/): Runtime requirements and supported behavior.
- [Internals](https://libtmux.org/en/ts/latest/workspace/internals/): The workspace library, for building sessions from code.