# Install and load a workspace

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

> Build the workspace command and load a session on a private tmux socket.

**Workspace Manager concept example** A working example of the core library. It can change without notice.



Build the documented `tmux-workspace` revision, then load a small session on a
private socket. Use a Unix shell with tmux 3.3a or newer on `PATH`.

## Build the command

Fetch the documented source revision, then build from its repository root.
Keep the exported `PATH` in this shell for the rest of the walkthrough.

```console
$ git clone --filter=blob:none https://github.com/libtmux/libtmux-ts.git
```

```console
$ cd libtmux-ts
```

```console
$ git fetch --depth=1 origin f36d692552bb9a373b45338bb5fece854e57cc3d
```

```console
$ git checkout --detach FETCH_HEAD
```

Use Bun and Node.js 22 or newer. Install the locked dependencies and build the
core package before the CLI:

```console
$ bun install --frozen-lockfile
```

```console
$ bun run --cwd packages/libtmux build
```

```console
$ bun run --cwd packages/workspace-cli build
```

```console
$ WORKSPACE_BIN="$(mktemp -d)"
```

```console
$ ln -s "$PWD/packages/workspace-cli/dist/main.js" "$WORKSPACE_BIN/tmux-workspace"
```

```console
$ export PATH="$WORKSPACE_BIN:$PATH"
```

The launcher runs the built JavaScript using Node. Keep the source directory
in place while using it.

```console
$ tmux-workspace --help
```

## Create the input

Keep this shell open. Create a temporary working directory on a filesystem that
supports Unix sockets, then enter it:

```console
$ WORKSPACE_TMP="$(mktemp -d)"
```

```console
$ cd "$WORKSPACE_TMP"
```

Save this as `workspace.yaml`:

```yaml title="workspace.yaml"
session_name: workspace-guide
windows:
  - window_name: editor
    layout: even-horizontal
    panes: [null, null]
```

## Load and inspect

```console
$ tmux-workspace load \
    -S "$WORKSPACE_TMP/tmux.sock" \
    -f /dev/null \
    -d \
    --json \
    workspace.yaml
```

`-d` leaves the session detached. Inspect its panes using the same socket:

```console
$ tmux -S "$WORKSPACE_TMP/tmux.sock" list-panes -t '=workspace-guide:editor'
```

Attach interactively with [`tmux -S "$WORKSPACE_TMP/tmux.sock" attach-session -t
'=workspace-guide'`](https://libtmux.org/en/tmux/latest/manual/attach-session/). Detach with your tmux detach binding before continuing.

## Capture and clean up

```console
$ tmux-workspace freeze -S "$WORKSPACE_TMP/tmux.sock" --json workspace-guide
```

Try [export and reload](https://libtmux.org/en/ts/latest/workspace/guides/export-session/) before cleanup. Capture cannot
recover original scripts, command history or application state.

Remove only the session created by this walkthrough when finished:

```console
$ tmux -S "$WORKSPACE_TMP/tmux.sock" kill-session -t '=workspace-guide'
```

The configuration remains in the temporary directory. Keep the session running
when following guides that continue this example.

## Continue

[Configuration](https://libtmux.org/en/ts/latest/workspace/configuration/) describes execution fields;
[discovery](https://libtmux.org/en/ts/latest/workspace/guides/discovery/) finds saved files. Read the [load reference](https://libtmux.org/en/ts/latest/workspace/cli/load/)
and [automation](https://libtmux.org/en/ts/latest/workspace/guides/automation/) for attachment, output and failure handling.

[CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md).