Session configuration
LibTmux.Workspace 0.0.0-alpha.14 · Source
tmuxp compatibility reference. Examples using tmuxp run the Python reference. Local CLI status describes this port’s implemented coverage.
The root mapping names the session and supplies defaults inherited by its
windows and panes. The file’s name is independent of "session_name": loading
project.yaml can create a session named development.
session_name: developmentstart_directory: ./suppress_history: trueshell_command_before: - echo preparing paneenvironment: WORKSPACE_ROLE: developmentoptions: default-shell: /bin/shglobal_options: status: truewindows: - window_name: main panes: - echo ready"global_options" changes the shared tmux server. Use a dedicated socket while
learning these options. The example assumes /bin/sh exists.
Root keysLink to section
| Key | Meaning |
|---|---|
"session_name" | Session identity; expanded before building |
"windows" | Ordered list of window mappings |
start_directory | Starting directory and base for inherited window directories |
"options" | tmux session options applied during construction |
"global_options" | tmux options applied with global scope on the selected server |
"environment" | Values placed in the tmux session environment |
shell_command_before | Commands prepended to commands in every pane |
"suppress_history" | Default history suppression inherited by windows and panes |
"before_script" | Process run after initial session creation, before configured windows |
"plugins" | List of Python plugin class references |
workspace_builder | Classic builder, registered builder name, or Python class reference |
workspace_builder_paths | Trusted directories used for Python builder imports |
workspace_builder_options | Builder behavior settings such as pane_readiness |
Options use tmux option names and values. A workspace key such as
start_directory is not a tmux option and does not belong in "options". Some
tmux settings are window options even when tmux permits them through a session
target; consult tmux’s option scope when choosing the catalog.
Construction orderLink to section
The classic builder creates the initial session, runs its initial plugin hook and workspace before_script, then applies root options, global options, and session environment before creating configured windows. The temporary initial window is replaced. Hooks can observe those tmux operations; loading is not an invisible transaction.
The same-named session is handled by the load command and its
attach, switch, append, and detached choices. Changing a YAML file does not
automatically reconcile an existing running session. An explicit load -s value
overrides the configured name for that invocation.
Inherited defaultsLink to section
A window can override its start directory and history policy, and a pane can override them again. Before commands accumulate in session, window, then pane order. Session environment remains distinct from window/pane launch environments. Read directories, commands, and environment before relying on inheritance.
Python scripts, plugins, and custom builder references execute code. Their exact timing and runtime requirements are in hooks and builders.
Current .NET builderLink to section
The parser supports session names, directories, scalar options, and windows. Python hooks/plugins, the complete environment runtime, and discovery are outside its model.
See the native builder behavior and configuration source before using these fields through application code.