Create sessions, windows and panes

Server:new_session, Session:new_window and Pane:split return a Request<Creation>. Await inside the adapter’s managed coroutine, or register on_complete(value, err). See connections and runtime ownership for setup and cancellation.

The receipt contains session, window, pane and window_link handles made from tmux’s returned IDs. Its created sequence names the objects this operation created: all four for a session, window/pane/link for a window, and only the pane for a split. Other handles describe the containing context. Creating a pane proves neither application readiness nor command success.

Commands and literal valuesLink to section

Pass argv for a literal command, or shell for explicitly authored tmux shell text. They are mutually exclusive. Multiple arguments use tmux’s native argument execution. A singleton executable uses /usr/bin/env -- to avoid tmux’s single-argument shell interpretation; it requires that utility and rejects executable names containing =. Use explicit shell text for that case. Omitting both fields uses tmux’s configured default command or shell.

Names, directories and environment values stay literal, including tmux format-looking text. Session names reject :, ., and control bytes because tmux would otherwise change them. environment maps portable variable names to string values and applies to the created session or pane process through tmux’s -e semantics. It does not change the caller’s environment.

An explicit cwd must be an absolute existing directory. The asynchronous preflight rejects a missing directory before sending the creation command. Filesystem changes after validation remain possible. Input is copied and validated before dispatch, including nested process options.

Placement and selectionLink to section

Sessions start detached and accept name, window_name, width and height. Windows accept name, an optional nonnegative index, and select; their parent is the Session handle’s exact ID. A supplied occupied index fails rather than replacing the existing window.

Splits accept direction (left, right, up or down), optional positive size in cells or percent from 1 through 99, full_size, and select. The default direction is down. New windows and splits leave selection unchanged unless select=true. Handle references cannot be edited to redirect an operation.

Errors and limitsLink to section

process accepts timeout, deadline, max_output_bytes, kill_timeout and drain_timeout; see command completion. It cannot replace the bound socket, process environment, input stream or working directory. Creation accepts at most 1024 argv items, 128 environment entries and one MiB of encoded input, subject to the runtime’s shared byte capacity.

Errors preserve whether the command was not sent, may have taken effect, or completed. A malformed receipt reports invalid_result with completed effect and retained command output. Canceling the tmux client cannot undo a creation already accepted by the daemon. Creation does not retry or remove partial state. Closing the Server connection leaves created sessions running.

The public creation fixture exercises the same API through luv and Neovim with literal arguments, environment and directory values, returned IDs, explicit shell text and missing directories.