Topology operations

Session, Window, Pane and WindowLink handles perform explicit mutations through the PROCESS endpoint. Each operation returns a Request that resolves to true when tmux successfully processes it. Refresh or capture a snapshot explicitly to inspect the resulting state; existing records do not change in place.

assert(session:rename("build"):await())
assert(window:resize({ width = 120, height = 40 }):await())
assert(window:layout({ named = "tiled" }):await())

The integration fixture includes setup, native-state assertions and cleanup through both runtime adapters.

Names and removalLink to section

session:rename(name) and window:rename(name) use their stable native IDs. Names are nonempty NUL-free strings up to 1,024 bytes. Session names also exclude dots, colons, ASCII controls and DEL. Format markers remain literal; native name validation and cleaning still apply. Releases differ in accepted bytes and escaping, so success does not promise byte-exact storage. Exact tmux 3.7 also rejects dots and colons in Window names. Renaming a Window turns off its automatic rename option.

session:kill() destroys that session and its links. A linked window can survive in another session. window:kill() destroys the window and every link to it, potentially removing sessions left without windows. Neither method targets all other sessions or windows. Use these only for intended mutations; Request cancellation never implies either operation.

Window navigationLink to section

session:navigate_window(direction) accepts "next", "previous" or "last". Next/previous support activity = true to select a window with a native alert. Last rejects the activity option, including explicit false. Navigation changes the session’s active window and follows native hooks and grouped-session behavior.

session:renumber_windows() renumbers from the session’s base-index option. It preserves Window IDs but invalidates captured link indices. It is a separate operation from moving one window.

Window placementsLink to section

A WindowLink identifies one placement by session, index and Window ID. Use creation.window_link or a handle from snapshot.window_links when an operation needs that exact placement, including duplicate links in one session. link:select() selects its index within its session.

link:link(destination) creates another placement; link:move(destination) also removes this source placement. Destinations accept one of these plain records:

• { session = session, index = 5 } chooses an explicit index. Omitting index requests a native free index from base-index, not append.
• { link = anchor, position = "before"|"after" } inserts relative to an existing placement and may shift indices.
• { link = victim, position = "at" } requires { replace = true } as the operation options. Replacement can destroy the victim Window if it has no other links. A numeric index alone never authorizes replacement.

Both operations default to select = false. Removal of an active source or replacement of an active destination can still force native selection. Occupied numeric destinations return native errors; the library never searches for a different destination or retries.

link:swap(other) exchanges the Windows in two placements. By default, selected slots remain selected, although their Window identities change. select = true selects the destination slot, and the source slot when the sessions differ. Swapping two placements of the same Window is a native no-op.

link:unlink() removes only this placement and refuses native last-link destruction. kill_if_last = true permits that destruction. Grouped sessions retain tmux’s synchronization and last-link rules. Native refusal is not rollback: insertion can shift indices before a later grouped-session error.

Each operation checks the stored source tuple, and any destination link tuple, in the native command queue immediately before the mutation. A recognized mismatch returns stale_target, effect = "not_sent", and the native receipt. Old handles never rebind automatically after index reuse, movement or swapping. Recreating the identical tuple cannot be distinguished from continuous identity; native command aliases can also change these checks. The native-command contract applies to the generated guards and their mutation branches. They are not a transaction or an unconditional compare-and-swap guarantee.

Success returns true; capture a new snapshot explicitly to find resulting placements. No predicted index or hidden post-mutation read constructs a new WindowLink handle.

Window size and layoutLink to section

window:resize(options) accepts exactly one form:

• width and/or height, integers from 1 to 10,000.
• direction = "left"|"right"|"up"|"down", with amount from 1 to 10,000, defaulting to one.
• largest = true or smallest = true, using tmux’s native client-size rule.

Native resizing sets window-size to manual. Layout constraints and available client sizes can affect the result; the command’s success is not a dimensions oracle. Resizing affects every link to the Window.

window:layout(options) also accepts exactly one form:

• named: even-horizontal, even-vertical, main-horizontal, main-vertical or tiled. The mirrored main layouts require tmux 3.5+.
• layout: an exported native layout string with a four-digit hexadecimal checksum, comma and body, bounded at 65,536 bytes.
• next = true, previous = true or restore = true.

Malformed custom-layout headers return invalid_layout before dispatch. This avoids faulty error handling in tmux 3.3/3.3a and short-header reads in older native parsers. Use named for standard layout names.

Layout operations unzoom before native checksum and body validation. A rejected layout can therefore change zoom state. A nonzero native exit carries its receipt and effect = "completed"; it does not establish rollback. Custom layout syntax is tmux’s grammar and is not evaluated as Lua or shell text.

Restart a windowLink to section

window:respawn({ context = link, ... }) requires a WindowLink naming this Window. Its session supplies the native launch context, including inherited environment. The link is checked in the native queue before respawn; the method never chooses an arbitrary session from a global Window ID.

Launch options match creation: literal argv or explicit shell, absolute cwd and a per-process environment map. Omitting launch text reuses the previous command. Working-directory validation is asynchronous and completes before dispatch. kill = true permits replacement of running processes; otherwise tmux refuses an active window.

Respawn retains the Window ID and its first Pane, removes sibling panes, and resets layout through every link to the Window. It can fail after destructive preparation; a native error does not establish rollback. Existing sibling Pane handles do not become references to the restarted first Pane.

Move a paneLink to section

pane:move_to(target, options) moves the same Pane into the target Pane’s Window. It defaults to a vertical split with select = false. Choose direction = "horizontal", size from 1 to 10,000 cells, or percent from 1 to 100. Size and percent exclude one another. before = true changes native geometry; it does not promise a matching pane-index order. full_size = true extends the split across the Window.

select = true requires target_link = link, identifying the exact placement whose session and index will be selected. An optional target link also checks membership when selection is disabled. The library checks that placement and the target Pane’s current Window separately in the native queue, then submits the compound target. A moved target Pane produces stale_target; a target that tmux cannot resolve can instead retain its native command error.

Movement changes global pane membership through all Window links. Moving the last Pane destroys the old Window and all its placements. Native layout and selection changes can happen before a later error. Moving a Pane preserves its ID and running process; it does not restart that process.

Break a pane into a windowLink to section

pane:break_out(source_link, destination, options) requires the Pane’s exact source WindowLink. Destinations accept a Session with an optional numeric index, or an anchor WindowLink with position = "before"|"after", as described under window placements. Replacement is not supported; an occupied numeric destination returns the native error.

The source placement and current Pane membership are checked in the native queue, along with any destination anchor. The operation preserves the Pane ID and running process. With multiple panes, tmux creates a new Window and keeps the source Window’s links. With one pane, it moves the specified placement of the existing Window; other links to that Window survive. select defaults to false, though removal of an active placement can force native selection.

name follows the Window name rules above. Omitting it preserves native naming: a singleton retains its existing Window name and options; a newly created Window takes the native default name and inherited options. An explicit name disables automatic rename for the resulting Window.

Exact tmux 3.7 has a native multi-pane naming defect. The library supplies a placeholder when no name is requested, avoiding the faulty native null-name path. For a named multi-pane break, it follows the break with a rename of the same Pane’s Window. This repair fires native rename notifications and after-rename-window hooks. Singleton breaks and other releases need no repair. A repair failure can occur after the Pane has moved; it is not rollback.

Effects and boundariesLink to section

Options are copied before dispatch and must be plain records. These methods accept the same nested process limits as Pane operations. Input is bounded at one MiB per operation. A stale generation or invalid target fails before dispatch. If continuity is lost after successful native completion, the error preserves effect = "completed" and that receipt. Mutations are never retried automatically.

Native aliases and hooks remain observable. These APIs do not promise transactions or protection against aliases that replace a built-in command.