tmux field catalog

This curated catalog describes the scalar fields needed by the core entity model. It does not enumerate every tmux format. Edit the source catalog and regenerate this reference together with Lua metadata and LuaLS field annotations:

$ python scripts/generate_fields.py

Check generated files without changing them:

$ python scripts/generate_fields.py --check

Generation uses Python and the pinned StyLua formatter; it needs no network or tmux process. The optional --verify-source argument accepts a local tmux Git checkout and verifies every pinned format mapping and source anchor.

Availability and valuesLink to section

Since means the first release supported by this catalog for that field, not necessarily the release that introduced it. The floor is tmux 3.2a. Source inspection establishes format availability; it does not establish complete runtime or platform compatibility. Later release strings retain known fields; development and prerelease strings require explicit capability evidence and are rejected by the schema helper.

Record names are Lua aliases for literal tmux format names. IDs retain their $, @, and % prefixes. number fields represent integers; consumers must reject values outside the exact integer range of their Lua runtime rather than silently round them. All generated LuaLS fields are optional because a projection may leave a field unloaded.

Nullable fields may be absent within an otherwise valid native context. Loaded absence uses query.NULL; an omitted key means not loaded. Known fields unavailable at the requested version remain in the query schema with supported = false. Empty text remains text for nonnullable string fields. The scalar catalog does not build relationships or perform I/O.

Window index, active state, and flags belong to window_link. Windows and panes have no scalar session ID because a window can be linked into several sessions. client_session provides a session name, not a session ID. Client names and buffer names need contextual revalidation before later mutations.

Source provenanceLink to section

• floor: 3.2a.
• added: 3.3.
• stable: 3.7c.
• upstream: inspected upstream revision.

ServerLink to section

• pid: Daemon process ID.
• socket_path: Socket path reported by the daemon.
• version: Daemon version string.
• start_time: Daemon start time in Unix seconds.

SessionLink to section

• id: Session ID, including its dollar-sign prefix.
• name: Session name.
• created: Creation time in Unix seconds.
• activity: Last activity time in Unix seconds.
• attached: Attached client count, not a boolean.
• window_count: Number of window links in this session.
• group: Session group name; absent for an ungrouped session.
• grouped: Whether this session belongs to a group.
• path: Session working directory.

WindowLink to section

• id: Window ID, including its at-sign prefix.
• name: Window name.
• width: Width in character cells.
• height: Height in character cells.
• pane_count: Number of panes owned by this window.
• layout: Layout including panes hidden by zoom; absent without a layout tree.
• visible_layout: Visible layout; absent without a layout tree.
• zoomed: Whether this window is zoomed.

Window linkLink to section

• session_id: Session owning this contextual link.
• window_id: Underlying window shared by links.
• index: tmux index within the session, not Lua array position.
• active: Whether this link is the session current window.
• flags: Printable flags for this session/window link.

PaneLink to section

• id: Pane ID, including its percent-sign prefix.
• window_id: ID of the window that owns this pane.
• index: tmux pane index within its window.
• active: Whether this pane is active in its window.
• title: Pane title; an empty title remains an empty string.
• width: Width in character cells.
• height: Height in character cells.
• left: Left cell offset in the window.
• top: Top cell offset in the window.
• pid: PID recorded for the pane process.
• tty: Pseudo-terminal name; empty is preserved.
• current_path: Process working directory when the OS can determine it.
• current_command: Displayed command name; absent without pane shell context.
• start_command: Stringified startup argv; this is not a shell-safe command.
• dead: Whether tmux has a ready dead-process status.
• dead_status: Exit status only when the process exited normally.
• dead_signal: Signal name only when the process terminated by signal.
• dead_time: Dead-pane display time in Unix seconds, when available.
• mode: Top mode name; absent outside pane modes.
• mode_count: Number of active modes, not a boolean.
• synchronized: Effective synchronize-panes option.

ClientLink to section

• name: Observed client name; not a persistent identifier.
• tty: Observed terminal name; empty is preserved.
• pid: Client process ID.
• session_name: Attached session name, not a session ID.
• width: Terminal width; nullable without a started TTY.
• height: Terminal height; nullable without a started TTY.
• control_mode: Whether this is a control-mode client.
• readonly: Whether this client is read-only.
• created: Creation time in Unix seconds.
• activity: Last activity time in Unix seconds.

BufferLink to section

• name: Buffer name; revalidate before later mutations.
• size: Buffer size in bytes.
• sample: tmux printable preview; not complete buffer bytes.
• created: Creation time in Unix seconds.