# Workspace configuration

Source: https://libtmux.org/en/py/stable/workspace/configuration/

> Define the session, windows, panes and commands loaded by the workspace CLI.

A workspace file describes one tmux session, its windows and panes, and the
commands sent to them. YAML and JSON carry the same field names. Save this
complete example as [`workspace.yaml`](https://libtmux.org/en/py/stable/workspace/guides/installation/#create-the-input):

```yaml
session_name: workspace-example
start_directory: ./
windows:
  - window_name: editor
    layout: even-horizontal
    panes:
      - echo ready
      - blank
```

The equivalent JSON is:

```json
{
  "session_name": "workspace-example",
  "start_directory": "./",
  "windows": [
    {
      "window_name": "editor",
      "layout": "even-horizontal",
      "panes": ["echo ready", "blank"]
    }
  ]
}
```

With Python tmuxp installed, load this file detached on a socket reserved for
the example:

```console
$ tmuxp load \
    -L configuration-example \
    -d \
    workspace.yaml
```

Inspect the resulting panes:

```console
$ tmux -L configuration-example list-panes -t '=workspace-example'
```

Remove the example session when finished:

```console
$ tmux -L configuration-example kill-session -t '=workspace-example'
```

## How configuration becomes a session

The tmuxp loader reads a document, expands command shorthand and shell
variables, and applies inherited defaults before selecting a workspace builder.
The classic builder then creates tmux objects and sends commands. Completion
means construction and command delivery finished; it does not establish that a
server launched in a pane is ready.

[`"session_name"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-session-name) and [`"windows"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-windows) are needed by normal loading. A window can omit its
name and let tmux choose one; an omitted [`"panes"`](https://libtmux.org/en/py/stable/workspace/configuration/windows/#window-keys-panes) list defaults to one blank
pane. Supplying explicit names and pane lists makes a portable example clearer.
An empty pane list is not the same input as an omitted list.

The internal [`validate_schema`](<https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-validation-validate_schema/>) helper requires each window_name, but the current
CLI/classic builder path does not call it. It is not a complete JSON Schema or
an exact description of what load accepts. A YAML parser accepting a key also
does not mean a builder implements it.

## Configuration reference

- [Session](https://libtmux.org/en/py/stable/workspace/configuration/session/) covers identity, options, environment, and root keys.
- [Windows](https://libtmux.org/en/py/stable/workspace/configuration/windows/) covers names, indexes, option timing, and focus.
- [Panes](https://libtmux.org/en/py/stable/workspace/configuration/panes/) covers shorthand, blank forms, shell, and overrides.
- [Commands](https://libtmux.org/en/py/stable/workspace/configuration/commands/) covers before commands, Enter, delays, and history.
- [Environment](https://libtmux.org/en/py/stable/workspace/configuration/environment/) separates process settings from pane values.
- [Directories](https://libtmux.org/en/py/stable/workspace/configuration/directories/) explains file discovery and path resolution.
- [Layouts](https://libtmux.org/en/py/stable/workspace/configuration/layouts/) explains pane arrangement and terminal size.
- [Hooks and builders](https://libtmux.org/en/py/stable/workspace/configuration/hooks/) covers scripts and Python extensions.

Use the [configuration gallery](https://libtmux.org/en/py/stable/workspace/examples/gallery/) for more complete files.
Configuration conversion should preserve the source mapping, including extension
keys; loading that mapping requires separate support for every execution
feature.

## Reference source

[loader.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [validation.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/validation.py); [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py).