Workspace configuration

Edit this page on GitHub

libtmux-workspace 0.0.1-alpha.12-SNAPSHOT · 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.

Native Java CLILink to section

The local tmux-workspace CLI validates its native configuration before scripts run or tmux state changes. It supports the session, window, pane and command fields described in the sections below. Unsupported native keys fail explicitly; Python plugin/custom-builder inputs use the separately selected extension path. Generic conversion preserves document fields without proving native execution.

See the CLI configuration parser. Application code using the lower-level workspace library has a separate builder API. Its schema is not the CLI configuration contract.

Reference sourceLink to section

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