TypeScript API reference

A restarted tmux on the same socket issues %0 again to a different pane, so an id from the previous run names nothing. Comparing epochs is what catches that, and it is why SessionRef and friends carry one.

A socket path names a place, not a process: kill-server and a restart give a new daemon the same path, and that daemon numbers its panes from %0 again. The pid alone is not enough — pids are reused — so the start time goes with it.

A handle exposes both spellings: the alias, and tmux's own token through format. The alias is this library's, so a field with no entry here is reachable only by its tmux name.

Read through format when the aliased property names on the handle are not what a caller wants — a field tmux added in a later version has a token here whether or not this library has given it a name.

A handle exposes both spellings: the alias, and tmux's own token through format. The alias is this library's, so a field with no entry here is reachable only by its tmux name.

tmux inserts at the next index before or after the target and moves the windows above it up to make room, so indices a caller is holding can shift. Without either direction the target index *is* the new window's place.

Read through format when the aliased property names on the handle are not what a caller wants — a field tmux added in a later version has a token here whether or not this library has given it a name.

The intersection keeps the three literals in autocomplete instead of letting the bare string swallow them.

A handle exposes both spellings: the alias, and tmux's own token through format. The alias is this library's, so a field with no entry here is reachable only by its tmux name.

Above and Left are the same split as Below and Right with tmux's -b flag, so the geometry is identical and only the occupant differs.

Read through format when the aliased property names on the handle are not what a caller wants — a field tmux added in a later version has a token here whether or not this library has given it a name.

A handle exposes both spellings: the alias, and tmux's own token through format. The alias is this library's, so a field with no entry here is reachable only by its tmux name.

Read through format when the aliased property names on the handle are not what a caller wants — a field tmux added in a later version has a token here whether or not this library has given it a name.

Branded so it cannot be confused with an OptionScope : passing this means the call sends no scope flag, which is not the same as sending the session one.

The scopes are not one chain. A pane option falls back to the window's, and an unset window or pane option falls back to the global window options; a session option falls back to the global session options, and server options belong to no session, window or pane at all. So setting something at window scope reaches every pane in it that has not set its own, and setting it at session scope does not.

The direction is where the boundary travels, not which pane grows: Up on a pane with a neighbour above it takes space from that neighbour.

null is 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.

Two servers on different sockets number their objects from the same place, so an id alone does not identify anything. This is the other half.

A tmux id is unique within one daemon and reissued by the next: kill-server and a restart give a new daemon the same socket, and it numbers its panes from %0 again. 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 -F does, because it is not a shell — tmux expands the format inside its command queue and cmdq_insert_afters the guarded command into the same queue, so nothing runs in between. The condition is pid and start_time together, 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.

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. guardRequest is 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.

Read from tmux's format.c rather than written by hand, so a field a newer tmux added is here as soon as the vocabulary is regenerated.

A field of one of these types carries an id a handle can be rebuilt from, which is why the row types refuse to report them as empty.

A field belongs to exactly one scope, and asking a pane for a session's field is what #{} silently answers as empty rather than as an error.

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: DecodedFormatValue is what a caller needs.

At least one of the three must be given. every and none both hold vacuously for an empty collection, which is set theory rather than a bug, and some is what a caller usually wants instead.

null matches the absence itself — a pane whose window is no longer in the snapshot — rather than matching anything.

The bare value is shorthand for { equals: value }, and null matches a field tmux reports as unset rather than empty.

Written as a union so the type rejects {} — criteria that constrain nothing would match everything, which is never what a caller meant.

The version is in the payload because these cross a process boundary — an MCP client, a config file — where the reader's library may be older than the writer's. Nothing widens 1 in place; a new shape gets a new number.

Written in terms of the handle rather than the kind so a caller holding a `Selection<Pane>` gets pane criteria without naming the kind twice.

The text side exists because the wire does. encodeFormatValue lowers every criterion to tmux's text before a query is serialized, and WhereDocumentV1 types both what a caller writes and what decodeWhereDocument gives 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.

Raw is 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.ts holds the layers in step.

The substring operations stay string deliberately: contains asks about the characters tmux sent, and a numeric field's text has characters like any other.

create-only, the default, sends them only to panes this apply created. always sends them to every pane on every apply.

tmux runs a command list until one fails and discards the rest, so the list is the unit of atomicity a caller gets. The daemon guard is what stops a raw tmux id being applied to whatever a restarted server reissued it to.

A union rather than string so a comparison against a name this package does not have is a type error rather than a branch that never runs.

Each class declares this type rather than its own literal because the hierarchy is three deep in places — NoMatchError extends ObjectNotFoundError — and a literal on the parent makes the child's declaration an illegal override. instanceof is the narrowing tool; this is the one that survives a bundler and a serialization round trip.

Kept as the caller wrote it rather than as a formatted sentence, so a caller that built the criteria from a form or a config file can point at the field that was wrong. The message renders it; this is the source.

A returncode of zero and a signal of null together mean tmux ran and answered; either one set means it did not finish, and stderr says why.

tmux pushes these; nothing here asked for them, and they arrive interleaved with command replies. The union is open in practice — an unrecognised notification arrives as TmuxUnknownEvent rather than being dropped, so a switch should still have a default.

The three are numbered independently, so $1, @1 and %1 can all exist at once and name unrelated objects. The kind is what keeps a pane id from being passed where a window id belongs.

A failure is written down rather than dropped because the queue is positional. An omitted failure does not merely lose itself — it hands the next call the answer belonging to the one after it, so a recorded failure replays as a pass and everything past it is off by one.

This is what a caller needs to decide whether retrying is safe: a command that was never written changed nothing, and one that was written but not answered may have done its work already. indeterminate is the honest answer, not a missing one.

These three exist so "101%" is a compile error rather than a runtime one.

Clients are absent on purpose: a client has a name rather than an id, and nothing numbers it.

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.

skipped is not a failure: a step whose precondition no longer holds is reported rather than retried, so the caller sees why the whole did less than it asked for.

This is the seam for logs, traces and metrics: a caller that wants to see what the library is doing has otherwise to supply a whole engine. It runs after the invocation is decided and cannot change its outcome — anything it throws is swallowed, because a command must not fail on account of the code watching it.

Returning a promise is allowed and never awaited: the invocation has already been decided, so waiting would only delay it. A rejection is swallowed on the same grounds as a throw, rather than left to the host's unhandled rejection policy.