Workspace configuration

Edit this page on GitHub

@libtmux/workspace 0.1.0-alpha.10 · Source

tmuxp compatibility reference. Examples using tmuxp run the Python reference. Local CLI status describes this port’s implemented coverage.

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:

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

The equivalent JSON is:

{
  "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:

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

Inspect the resulting panes:

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

Remove the example session when finished:

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

How configuration becomes a sessionLink to section

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" and "windows" are needed by normal loading. A window can omit its name and let tmux choose one; an omitted "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 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 referenceLink to section

• Session covers identity, options, environment, and root keys.
• Windows covers names, indexes, option timing, and focus.
• Panes covers shorthand, blank forms, shell, and overrides.
• Commands covers before commands, Enter, delays, and history.
• Environment separates process settings from pane values.
• Directories explains file discovery and path resolution.
• Layouts explains pane arrangement and terminal size.
• Hooks and builders covers scripts and Python extensions.

Use the configuration 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.

Current TypeScript builderLink to section

@libtmux/workspace validates a strict subset. Its apply operation reconciles a session using ownership and command policies, which differs from tmuxp load. Its YAML helper requires Bun; Node callers need a separate YAML decoder.

See the native builder behavior and configuration source before using these fields through application code.

Reference sourceLink to section

loader.py; validation.py; classic.py.