On this page
TypeScript API reference
878 symbols, extracted from source. Every type name in a signature links to its own entry; every cross-reference in a doc comment resolves against the same table.
By module 18 modules
- builder 11
- client 2
- common 28
- config 14
- constants 5
- engine 6
- exc 24
- field_types 13
- operation_options 8
- ownership 4
- pane 3
- planning 13
- selection 21
- server 6
- session 3
- types 65
- window 5
- Types 3
Server 2 types
Session 2 types
Window 3 types
Pane 2 types
Client 2 types
Versions 1 type
Commands 1 type
Formats 1 type
Queries 1 type
Workspaces — Plans 11 types
What Pane.plan offers, one entry per mutation it can describe.
What Session.plan offers, one entry per mutation it can describe.
A tmux command that has been described but not run.
WindowPlans 3 members What Window.plan offers, one entry per mutation it can describe.
One existing window placement named by a workspace plan.
WorkspaceWindowCreation 2 membersA window that applying would create.
WorkspacePaneCreation 2 membersPanes that applying would create in one window position.
WorkspacePaneRemoval 2 membersExisting panes that applying would destroy.
WorkspaceWindowRemoval 2 membersHow applying would remove an existing window placement.
WorkspaceWindowRename 3 membersOne existing window rename, identified independently of its current name.
WorkspacePlan 8 membersSession, window, and pane membership changes an apply would make.
Errors 17 types
A command did not complete, and this is how far it got.
TmuxTransportErrorOptions 5 members ObjectDoesNotExist 2 members MultipleObjectsReturned 3 members TmuxObjectDoesNotExist 1 members VersionTooLow 4 membersA field the server is too old to have.
WaitTimeout 0 members NoMatchError 0 members MultipleMatchesError 0 members QueryValidationError 3 members TmuxCommandError 7 membersA tmux command that exited non-zero.
WorkspaceApplyError 4 membersApplying stopped after tmux may already have changed.
Errors — Server 1 type
Constants and enums 31 types
Options for Server.snapshot .
Options for Server.cmd and the handle-level cmd.
Options for joining a pane into another window.
SetOptionOptions 1 membersOptions for writing a tmux option.
CaptureOptions 5 members SetHookOptions 1 members ResizeOptions 4 members RunShellOptions 1 members IfShellOptions 3 members RespawnOptions 3 members PopupOptions 4 members ChooseTreeOptions 2 members SetEnvironmentOptions 2 membersOptions for writing a tmux environment variable.
TmuxOutputEvent 4 membersA pane produced output.
TmuxSubscriptionEvent 7 membersA subscribed format expanded to a new value.
TmuxLayoutChangeEvent 5 membersA window's layout changed.
TmuxPasteBufferEvent 2 membersA paste buffer was written or deleted.
TmuxMessageEvent 2 memberstmux reported a message, or an error in its configuration.
TmuxExitEvent 2 membersThe control-mode connection is ending.
TmuxUnknownEvent 3 membersA notification this version of the package does not model.
TmuxReconnectedEvent 2 membersThe connection dropped and was reopened.
TmuxReconnectingEvent 2 membersThe connection dropped and a replacement is being opened.
ConnectionOptions 4 membersOptions shared by connected servers and event observers.
WaitForOptions 2 membersTiming for a whole-server state wait.
WatchOptions 2 members Options for Server.watch , a notification-only observer.
How applyWorkspace should treat a workspace that is already running.
Structural planning options; pane command delivery is apply-only.
Constants and enums — Server 1 type
Constants and enums — Session 5 types
The attached session changed, or a session was renamed.
TmuxSessionsChangedEvent 1 membersThe set of sessions changed. Carries no payload; re-read the server.
TmuxSessionWindowChangedEvent 3 membersA session's active window changed.
TmuxClientSessionChangedEvent 4 membersAnother client switched sessions.
Constants and enums — Window 6 types
A window was added, closed, or linked into or out of a session.
TmuxWindowRenamedEvent 3 membersA window was renamed.
TmuxWindowPaneChangedEvent 3 membersThe active pane of a window changed.
Constants and enums — Pane 2 types
Constants and enums — Client 1 type
Other 8 types
An immutable, ordered set of tmux objects read at one instant.
MenuEntry 3 members AbortLike 3 members The part of AbortSignal this package uses.
A live stream of tmux control-mode events.
Functions and constants 0 types
- applyWindow ( window : : Window , desired : : WorkspaceWindow , workspace : : Workspace , context : : ApplyWindowContext ) Promise<void>
- applyWorkspace ( server : : Server , workspaceInput : : WorkspaceInput , options : : ApplyWorkspaceOptions = {} ) Promise<Session>
-
Build a workspace into a real tmux session, or reconcile one that exists.
tmux gives every new session a window and every new window a pane, so the first window and first pane of each level are adopted rather than created. Creating them anyway is the classic workspace-builder bug that leaves an empty leading window behind.
What this reconciles is *topology*: which windows exist, in what order, under what names, with how many panes, under which layout. It is safe to apply twice and the second run does not duplicate anything. It is deliberately not a process supervisor — see
CommandPolicy— and it does not unset options a previous version of the file had set, because tmux cannot say which of an option's current values this file is responsible for.- Raises
-
-
ZodError – when the workspace does not satisfy the strict config schema.
-
TypeError – when the operation options are invalid.
-
WorkspaceApplyError – when tmux fails after applying may have started.
-
-
Claim a session this apply created.
- commandPolicy ( value : : unknown ) CommandPolicy
- decodeWhereDocument ( input : : unknown ) WhereDocumentV1
-
Validate a WHERE document and restore camelCase criteria names.
The returned document is canonical and deeply frozen.
Examples
import { decodeWhereDocument } from "libtmux/selection"; const document = decodeWhereDocument( JSON.parse('{"model":"pane","version":1,"where":{"pane_title":"logs"}}'), ); if (document.model === "pane") snapshot.panes.where(document.where);- Raises
-
-
QueryValidationError – when the document or its criteria are invalid.
-
- encodeWhereDocument ( document : : WhereDocumentV1 ) string
-
Serialize a WHERE document as canonical JSON.
Field names and values use tmux's stable wire spellings. The input is validated without invoking accessors or conversion hooks.
Examples
import { encodeWhereDocument } from "libtmux"; const encoded = encodeWhereDocument({ model: "pane", version: 1, where: { title: { contains: "log" } }, });- Raises
-
-
QueryValidationError – when the document or its criteria are invalid.
-
-
The directory tmux needs when it creates the session's first pane.
- inThisSession ( window : : Window , options : : MoveWindowOptions ) MoveWindowOptions
-
Fill in the destination session the caller left out.
tmux reads a destination of
:3as index 3 of the *current* session, which is whichever one it happens to consider current — not this window's. Naming the window's own is what makes "the window stays in its own session when omitted" true, and it is the only reading under which omitting the session is a smaller request rather than a different one.
- isSafeInteger ( value : : unknown ) value is SafeInteger
-
Test whether a value is an exact JavaScript integer.
Examples
import { isSafeInteger } from "libtmux"; const value: unknown = 3; if (isSafeInteger(value)) snapshot.sessions.where({ attached: value });
-
Test whether a value is valid tmux split geometry.
Examples
import { isSplitSize } from "libtmux"; const value: unknown = "30%"; const size = isSplitSize(value) ? value : undefined;
-
Test whether a value is a name every supported tmux stores unchanged.
The refusal the mutating calls apply, offered ahead of them so a caller validating configuration can report the bad field rather than catching a
TypeErrorfrom the call it fed.Examples
import { isTmuxName } from "libtmux"; const value: unknown = "work"; const name = isTmuxName(value) ? value : undefined;
- mayPrune ( policy : : PrunePolicy , owned : : boolean ) boolean
-
Whether surplus topology may be removed.
ownedis the default because it is the only one that is safe without knowing where the session came from: a workspace prunes what it built and leaves alone what it merely found.alwaysauthorizes pruning for one operation; it does not stamp or otherwise adopt the session.
- normalizeApplyWorkspaceOptions ( options : : ApplyWorkspaceOptions ) { readonly commands: CommandPolicy; readonly prune: PrunePolicy; }
-
Validate and snapshot apply options before server access.
- normalizePlanWorkspaceOptions ( options : : PlanWorkspaceOptions ) PrunePolicy
-
Validate and snapshot planning options before server access.
- optionValue ( value : : WorkspaceOptionValue ) string
-
Convert a YAML scalar to the string tmux accepts for an option value.
-
-
Whether this session carries the mark for
name.
- paneCommands ( pane : : WorkspacePane , window : : WorkspaceWindow ) readonly string[]
-
Normalize a pane entry to the commands it should run, in order.
A window's
shell_command_beforeruns in every one of its panes, ahead of that pane's own commands, which is how tmuxp seeds a common environment.
- paneStartDirectory ( pane : : WorkspacePane , window : : WorkspaceWindow , workspace : : Workspace ) string | undefined
-
A pane's start directory, falling back to its window's and then the session's.
- paneWantsFocus ( pane : : WorkspacePane ) boolean
-
Whether a pane entry asked to be the focused one.
- parseLegacyWhere ( model : : Model , input : : unknown ) Extract<WhereDocumentV1, { readonly model: Model }>
-
Convert the Python port's
name__containsspelling to canonical criteria.Accepts one own data property on a plain object and never invokes accessors or conversion hooks. The returned document and its criteria are frozen.
Examples
import { parseLegacyWhere } from "libtmux"; const document = parseLegacyWhere("window", { name__contains: "log" }); snapshot.windows.where(document.where);- Raises
-
-
QueryValidationError – when the model is not
sessionorwindow, or the input is not exactly one string-valuedname__containsproperty.
-
-
Validate a parsed workspace, rejecting anything the schema does not allow.
-
Parse a YAML or JSON workspace, then validate it.
YAML parsing is Bun's, and this package otherwise runs anywhere — so this is the one function that does not. Reached from Node it says so, rather than failing on an undefined global; parse the document yourself and hand the result to
parseWorkspace.
-
This placement, as tmux addresses one.
A window linked into two sessions is one window with two placements sharing an id, and a bare
@idleaves tmux to choose between them — which it does consistently, and consistently without regard for which placement the handle came from. Qualifying with the session is what makes an operation act on the placement it was reached through.Only the operations that address a placement take this.
kill,rename,selectLayoutandresizeact on the window itself, wherever it is linked, and naming a session there would suggest a choice that does not exist.
- planWorkspace ( server : : Server , workspaceInput : : WorkspaceInput , options : : PlanWorkspaceOptions = {} ) Promise<WorkspacePlan>
-
Plan session, window, and pane membership without changing tmux.
Reads the server once and answers from that capture, so it costs one snapshot and changes nothing. It reports structural creation, removal, retention, and window renames. It does not predict options, layouts, focus, or pane command effects.
Examples
const plan = await planWorkspace(server, workspace); if (plan.removesWindows.length > 0) console.log("would remove", plan.removesWindows);- Raises
-
-
ZodError – when the workspace does not satisfy the strict config schema.
-
TypeError – when planning options are invalid.
-
- planWorkspace ( server : : Server , workspace : : Workspace , prune : : PrunePolicy ) Promise<WorkspacePlan>
- prunePolicy ( value : : unknown ) PrunePolicy
-
Refuse a call that can only reach a tmux this process can spawn.
Control mode is a
tmux -C attachchild of this process. An engine exists because tmux is somewhere this process cannot spawn it, so spawning anyway would attach to whatever local tmux happens to be there — and every command afterwards would succeed against the wrong server.
-
-
The session this workspace names, on a server that may not be running yet.
Acquisition raises on an unreachable server rather than reading as empty, which is the answer a caller asking what is there needs. Building from nothing is the ordinary starting point here, though, and a socket with no daemon behind it is holding this session in the way an empty server is: not at all.
- safeInteger ( value : : number ) SafeInteger
-
Authenticate an exact JavaScript integer or throw.
Examples
import { safeInteger } from "libtmux"; const pid = safeInteger(42);
-
Which tmux this runtime addresses, or
undefinedwhen that is unknowable.An engine's socket is a path on a machine this process cannot see, so the socket alone does not name the daemon. Unknowable rather than guessed: an engine that declares no endpoint is the one case where answering would mean inventing the fact the comparison turns on.
-
How a connection addresses its daemon, as one comparable string.
An absolute socket path names the daemon outright. A name does not: it is resolved against
TMUX_TMPDIR(then the default tmpdir) and a per-user directory, so the tmpdir in force is part of the address. tmux's own default name isdefault, which is why an unnamed connection is not a third case.
-
The window that should hold position
index, created if it is not there yet.tmux window indexes are not positions —
base-indexshifts them and a killed window leaves a gap — so position is resolved by ordinal, not by index.
- windowStartDirectory ( window : : WorkspaceWindow , workspace : : Workspace ) string | undefined
-
A window's directory, inherited from its workspace when it has none.
- workspaceWindowPlacement ( window : : Window , position : : number ) WorkspaceWindowPlacement
-
Idiomatic property names layered over a row, carrying decoded values.
-
When a pane's
shell_commandentries are sent to it.create-only, the default, sends them only to panes this apply created.alwayssends them to every pane on every apply.
-
Options for
Server.connect.
-
Making a command refuse to run on a daemon that is not the one it was read from.
A tmux id is unique within one daemon and reissued by the next:
kill-serverand a restart give a new daemon the same socket, and it numbers its panes from%0again. A handle captured before the restart therefore names something that exists, belongs to somebody else, and answers to the same command.Checking first and sending second does not close that: the daemon can change between the two.
if-shell -Fdoes, because it is not a shell — tmux expands the format inside its command queue andcmdq_insert_afters the guarded command into the same queue, so nothing runs in between. The condition ispidandstart_timetogether, since pids are reused.The refusal has to be visible. tmux answers a false condition with no output and status 0, which is indistinguishable from a command that printed nothing, so the else branch is a freshly named unknown command. A 128-bit suffix makes matching a pre-existing command alias a guess, and the exact diagnostic distinguishes the refusal from the guarded command failing. The guarded command keeps its own stdout and stderr either way.
-
Which tmux daemon answered, as tmux itself reports it.
A socket path names a place, not a process:
kill-serverand a restart give a new daemon the same path, and that daemon numbers its panes from%0again. The pid alone is not enough — pids are reused — so the start time goes with it.
-
What a caller reads for one field, once the text has been decoded.
-
Environments live at server (global) or session scope, as hooks do.
-
A variable's state in a tmux environment.
nullis tmux's-NAME: the variable is present and marked for removal from the environment of any process tmux starts. Absent from the map is the third state, and means tmux carries no entry at all.
-
The shapes tmux writes that are not simply text.
-
Which fields carry which shape.
Derived from tmux's own format.c and held to a live server by tests/integration/format_types.test.ts on every version CI runs.
Local:
DecodedFormatValueis what a caller needs.
-
A daemon-guarded request paired with its exact refusal detector.
-
The server, session, window, or pane table that holds a hook.
-
A menu entry, or a horizontal rule.
tmux spells a separator as one empty argument rather than a name/key/command triple, so modelling it as a distinct value keeps callers from fabricating empty fields that tmux would reject.
-
A pane ID in tmux's
%nform.
-
Raw pane-ID text or an authenticated pane ID.
-
What to do with windows and panes the workspace does not describe.
-
The text tmux sends for a flag: it writes these two and nothing else.
-
The raw text tmux writes, authenticated where it carries an identity.
-
The decimal text tmux sends for a field it reports as a number or timestamp.
-
A raw format row whose listed identity fields are present.
-
A finite whole number within JavaScript's safe integer range.
Examples
import { safeInteger } from "libtmux"; import type { SafeInteger } from "libtmux"; const count: SafeInteger = safeInteger(3);
-
A session ID in tmux's
$nform.
-
Raw session-ID text or an authenticated session ID.
-
A nonnegative cell count within tmux's signed 32-bit geometry range.
Examples
import { splitSize } from "libtmux"; import type { SplitCellSize } from "libtmux"; const size: SplitCellSize = splitSize(20);
-
A canonical whole percentage from
0%through100%.Examples
import type { SplitPercentage } from "libtmux"; const size: SplitPercentage = "30%"; void size;
-
An authenticated cell count or canonical percentage for a pane split.
Examples
import type { SplitSize } from "libtmux"; const size: SplitSize = "30%"; void size;
-
A field's criteria accept its decoded shape as well as the text tmux sends:
where({ active: true })andwhere({ active: "1" })are the same query, and serialize identically. Anullcriterion matches any wire value that the field decoder treats as absent or invalid, rather than one particular wire spelling.The text side exists because the wire does.
encodeFormatValuelowers every criterion to tmux's text before a query is serialized, andWhereDocumentV1types both what a caller writes and whatdecodeWhereDocumentgives back — so a type that refused text would be lying about the documents this library's own encoder produces. That is the difference from an ORM, whose query AST never round-trips through a type the caller also authors.Rawis therefore not a taste."0" | "1"is the exact wire domain for a flag, while an integer uses${bigint}intersected with a decimal prefix. That rules out fractions, exponents, radix prefixes, leading zeroes,-0,NaN, and prose. TypeScript cannot bound an integer's magnitude, so the query validator also requires safe range at runtime.format_values.test.tsholds the layers in step.The substring operations stay
stringdeliberately:containsasks about the characters tmux sent, and a numeric field's text has characters like any other.
-
One nonempty tmux command, before command-list separators are inserted.
-
What runs a tmux command for a server.
Two obligations beyond returning bytes, and both are what the layers above assume rather than check:
Every request is one tmux invocation and carries its ordered command list. Keeping that structure at the seam prevents an engine from splitting a snapshot into several clients or guessing where global flags end. Environment, stdin, signal, and timeout apply once to the whole invocation.
daemonGuard, when a request carries one, must reach tmux — or the engine must be bound to one daemon for its lifetime, the way a control connection is. Ignoring it on a reconnecting engine means a handle read before a restart addressing whatever now holds its id.guardRequestis what the built-in engine calls to honour it, published so an implementer does not reproduce the wrapper, its else branch, and the stderr that tells refusal from failure.
-
A tmux object ID authenticated for one object kind.
-
Raw text or an already-authenticated ID of the expected kind.
-
What went wrong between this process and tmux, as opposed to inside tmux.
-
A window ID in tmux's
@nform.
-
Raw window-ID text or an authenticated window ID.
-
A relative direction, or any window target tmux accepts.
The intersection keeps the three literals in autocomplete instead of letting the bare
stringswallow them.
-
A validated workspace with every schema default and transform applied.
-
A high-level apply operation that finished before a later one failed.
-
The high-level operation an apply was attempting when it failed.
-
Workspace data before schema defaults and transforms are applied.
-
Surplus topology retained because removing it would exceed the policy.