Workspace configuration

Edit this page on GitHub

github.com/libtmux/libtmux-go/workspace · 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 Go builderLink to section

The Go workspace package rejects unknown fields. It supports a configuration subset, but does not perform tmuxp variable expansion or run Python plugins. Its builder can leave partial state after an error.

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.