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.pyCheck generated files without changing them:
$ python scripts/generate_fields.py --checkGeneration 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 values¶
Since means the first release supported by this catalog for that field,
not necessarily the release that introduced it. The floor is tmux 3.3a.
Source inspection establishes format availability; it does not establish
complete runtime or platform compatibility. The schema helper accepts recognized
final, release-candidate and next-X.Y reports that rank at or above the floor.
Field availability is checked against that rank. Unrecognized reports and
versions below the floor are rejected.
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 provenance¶
- floor: 3.3a.
- stable: 3.7c.
- upstream: inspected upstream revision.
Server¶
| Record field | tmux format | Type | Nullable | Since | Native scope |
|---|---|---|---|---|---|
pid¶ | pid | number | no | 3.3a | server |
socket_path¶ | socket_path | string | no | 3.3a | server |
version¶ | version | string | no | 3.3a | server |
start_time¶ | start_time | number | no | 3.3a | server |
pid: Daemon process ID.socket_path: Socket path reported by the daemon.version: Daemon version string.start_time: Daemon start time in Unix seconds.
Session¶
| Record field | tmux format | Type | Nullable | Since | Native scope |
|---|---|---|---|---|---|
id¶ | session_id | string | no | 3.3a | session |
name¶ | session_name | string | no | 3.3a | session |
created¶ | session_created | number | no | 3.3a | session |
activity¶ | session_activity | number | no | 3.3a | session |
attached¶ | session_attached | number | no | 3.3a | session |
window_count¶ | session_windows | number | no | 3.3a | session |
group¶ | session_group | string | yes | 3.3a | session |
grouped¶ | session_grouped | boolean | no | 3.3a | session |
path¶ | session_path | string | no | 3.3a | session |
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.
Window¶
| Record field | tmux format | Type | Nullable | Since | Native scope |
|---|---|---|---|---|---|
id¶ | window_id | string | no | 3.3a | window |
name¶ | window_name | string | no | 3.3a | window |
width¶ | window_width | number | no | 3.3a | window |
height¶ | window_height | number | no | 3.3a | window |
pane_count¶ | window_panes | number | no | 3.3a | window |
layout¶ | window_layout | string | yes | 3.3a | window |
visible_layout¶ | window_visible_layout | string | yes | 3.3a | window |
zoomed¶ | window_zoomed_flag | boolean | no | 3.3a | window |
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 link¶
| Record field | tmux format | Type | Nullable | Since | Native scope |
|---|---|---|---|---|---|
session_id¶ | session_id | string | no | 3.3a | session |
window_id¶ | window_id | string | no | 3.3a | window |
index¶ | window_index | number | no | 3.3a | winlink |
active¶ | window_active | boolean | no | 3.3a | winlink |
flags¶ | window_flags | string | no | 3.3a | winlink |
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.
Pane¶
| Record field | tmux format | Type | Nullable | Since | Native scope |
|---|---|---|---|---|---|
id¶ | pane_id | string | no | 3.3a | pane |
window_id¶ | window_id | string | no | 3.3a | window |
index¶ | pane_index | number | no | 3.3a | pane |
active¶ | pane_active | boolean | no | 3.3a | pane |
title¶ | pane_title | string | no | 3.3a | pane |
width¶ | pane_width | number | no | 3.3a | pane |
height¶ | pane_height | number | no | 3.3a | pane |
left¶ | pane_left | number | no | 3.3a | pane |
top¶ | pane_top | number | no | 3.3a | pane |
pid¶ | pane_pid | number | no | 3.3a | pane |
tty¶ | pane_tty | string | no | 3.3a | pane |
current_path¶ | pane_current_path | string | yes | 3.3a | pane |
current_command¶ | pane_current_command | string | yes | 3.3a | pane |
start_command¶ | pane_start_command | string | no | 3.3a | pane |
dead¶ | pane_dead | boolean | no | 3.3a | pane |
dead_status¶ | pane_dead_status | number | yes | 3.3a | pane |
dead_signal¶ | pane_dead_signal | string | yes | 3.3a | pane |
dead_time¶ | pane_dead_time | number | yes | 3.3a | pane |
mode¶ | pane_mode | string | yes | 3.3a | pane |
mode_count¶ | pane_in_mode | number | no | 3.3a | pane |
synchronized¶ | pane_synchronized | boolean | no | 3.3a | pane |
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.
Client¶
| Record field | tmux format | Type | Nullable | Since | Native scope |
|---|---|---|---|---|---|
name¶ | client_name | string | no | 3.3a | client |
tty¶ | client_tty | string | no | 3.3a | client |
pid¶ | client_pid | number | no | 3.3a | client |
session_name¶ | client_session | string | yes | 3.3a | client |
width¶ | client_width | number | yes | 3.3a | client |
height¶ | client_height | number | yes | 3.3a | client |
control_mode¶ | client_control_mode | boolean | no | 3.3a | client |
readonly¶ | client_readonly | boolean | no | 3.3a | client |
created¶ | client_created | number | no | 3.3a | client |
activity¶ | client_activity | number | no | 3.3a | client |
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.
Buffer¶
| Record field | tmux format | Type | Nullable | Since | Native scope |
|---|---|---|---|---|---|
name¶ | buffer_name | string | no | 3.3a | buffer |
size¶ | buffer_size | number | no | 3.3a | buffer |
sample¶ | buffer_sample | string | no | 3.3a | buffer |
created¶ | buffer_created | number | no | 3.3a | buffer |
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.