Clients¶

Attached terminals connected to a tmux server
Each client has its own view of the active session, window, and pane
Identified by client_name (the path or label tmux assigns at attach time)

class libtmux.Client ¶ class[source] class[source] class libtmux.Client ¶

Bases: Obj

A tmux client is an attached terminal. The same tmux server can have multiple clients attached simultaneously (e.g. $ tmux attach from several terminals) and each receives its own view of the active session, window, and pane.

Warning

client_session, session_id, window_id and pane_id are snapshots of the client’s currently attached view at the moment this object was read — not stable identity for the client. When the client switches sessions via switch-client, moves focus via select-window / select-pane, or detaches, these fields go stale until refresh() re-reads them from list-clients. The client_name (tty path on Unix) is the client’s stable identity.

Prefer attached_session(), attached_window(), and attached_pane() when you need the client’s current attachment. Each property re-reads tmux before returning, so the Session / Window / Pane you get back reflects where the client is attached now, not where it was when this Client was constructed. If tmux no longer reports this client_name through list-clients, these properties return None.

attached_pane() follows the attached session’s current window. That can differ from the per-client active pane set by select-pane -P; see attached_pane() for the exact behavior. Each property re-reads tmux on every access.

Parameters:: server (Server)

Examples

>>> with control_mode() as ctl:
...     attached = [
...         c
...         for c in server.clients
...         if c.client_name == ctl.client_name
...     ]
>>> bool(attached)
True

>>> with control_mode() as ctl:
...     client = server.clients.get(client_name=ctl.client_name)
...     client.client_readonly in {"0", "1"}
True

References

[client_manual]

tmux client. openbsd manpage for TMUX(1).: “tmux supports multiple attached clients. Each client has its own keymap, view of the session, and message log.”

https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed 2026.

property attached_session: Session | None ¶ property property property attached_session: Session | None ¶

Return the Session this client is currently attached to.

Re-reads the client from list-clients before resolving, so the returned Session reflects the client’s live attachment rather than the snapshot captured when this Client was read. Returns None when tmux no longer reports this client_name through list-clients, when the client is not attached to any session, or when the snapshot session_id no longer names a live session.

Examples

>>> with control_mode() as ctl:
...     client = server.clients.get(client_name=ctl.client_name)
...     attached = client.attached_session
>>> attached is not None
True

property attached_pane: Pane | None ¶ property property property attached_pane: Pane | None ¶: Return the Pane this client is currently viewing.

Re-reads the client from list-clients, looks up its attached session’s current window, and returns that window’s active_pane. Returns None when no live attached session or active pane can be resolved.

This follows the attached session’s current window and active pane. When a client has used select-pane -P to set its own active pane, this property returns the session’s current active pane, not the client’s per-client focus.

_resolve_attached() ¶ method[source] method[source] _resolve_attached() ¶

Resolve live attachment with a single list-clients refresh.

The three attached_session / attached_window / attached_pane properties each trigger their own list-clients refresh — calling them in sequence performs three tmux reads for one conceptual “where is this client attached now” read. _resolve_attached shares a single refresh across the triple and returns the three values together.

Returns:

tuple[Session | None, Window | None, Pane | None] –
- (None, None, None) when tmux no longer reports this client_name through list-clients, when the client snapshot has no session_id, or when the snapshot session_id no longer names a live session.
- (session, None, None) when the attached session has no active window.
- (session, window, pane) for a fully-resolved live attachment. pane is None only when the active window has no active pane.
MultipleActiveWindows propagates rather than
collapsing to (session, None, None) — multiple active windows
in one session indicates inconsistent tmux state that callers
should see, not absent attachment.

Return type:

tuple[Session | None, Window | None, Pane | None]

__init__(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_activity=None, client_cell_height=None, client_cell_width=None, client_control_mode=None, client_created=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_last_session=None, client_mode_format=None, client_name=None, client_pid=None, client_prefix=None, client_readonly=None, client_session=None, client_termfeatures=None, client_termname=None, client_termtype=None, client_tty=None, client_uid=None, client_user=None, client_utf8=None, client_width=None, client_written=None, command_list_alias=None, command_list_name=None, command_list_usage=None, config_files=None, copy_cursor_line=None, copy_cursor_word=None, copy_cursor_x=None, copy_cursor_y=None, current_file=None, cursor_character=None, cursor_flag=None, cursor_x=None, cursor_y=None, history_bytes=None, history_limit=None, history_size=None, insert_flag=None, keypad_cursor_flag=None, keypad_flag=None, last_window_index=None, line=None, mouse_all_flag=None, mouse_any_flag=None, mouse_button_flag=None, mouse_sgr_flag=None, mouse_standard_flag=None, next_session_id=None, origin_flag=None, pane_active=None, pane_at_bottom=None, pane_at_left=None, pane_at_right=None, pane_at_top=None, pane_bg=None, pane_bottom=None, pane_current_command=None, pane_current_path=None, pane_dead=None, pane_dead_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_format=None, pane_height=None, pane_id=None, pane_in_mode=None, pane_index=None, pane_input_off=None, pane_last=None, pane_left=None, pane_marked=None, pane_marked_set=None, pane_mode=None, pane_path=None, pane_pid=None, pane_pipe=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_synchronized=None, pane_tabs=None, pane_title=None, pane_top=None, pane_tty=None, pane_width=None, pid=None, scroll_position=None, scroll_region_lower=None, scroll_region_upper=None, search_match=None, selection_end_x=None, selection_end_y=None, selection_start_x=None, selection_start_y=None, session_activity=None, session_alerts=None, session_attached=None, session_attached_list=None, session_created=None, session_format=None, session_group=None, session_group_attached=None, session_group_attached_list=None, session_group_list=None, session_group_many_attached=None, session_group_size=None, session_grouped=None, session_id=None, session_last_attached=None, session_many_attached=None, session_marked=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_clients_list=None, window_active_sessions=None, window_active_sessions_list=None, window_activity=None, window_activity_flag=None, window_bell_flag=None, window_bigger=None, window_cell_height=None, window_cell_width=None, window_end_flag=None, window_flags=None, window_format=None, window_height=None, window_id=None, window_index=None, window_last_flag=None, window_layout=None, window_linked=None, window_linked_sessions=None, window_linked_sessions_list=None, window_marked_flag=None, window_name=None, window_offset_x=None, window_offset_y=None, window_panes=None, window_raw_flags=None, window_silence_flag=None, window_stack_index=None, window_start_flag=None, window_visible_layout=None, window_width=None, window_zoomed_flag=None, wrap_flag=None) ¶ method[source] method[source] __init__(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_activity=None, client_cell_height=None, client_cell_width=None, client_control_mode=None, client_created=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_last_session=None, client_mode_format=None, client_name=None, client_pid=None, client_prefix=None, client_readonly=None, client_session=None, client_termfeatures=None, client_termname=None, client_termtype=None, client_tty=None, client_uid=None, client_user=None, client_utf8=None, client_width=None, client_written=None, command_list_alias=None, command_list_name=None, command_list_usage=None, config_files=None, copy_cursor_line=None, copy_cursor_word=None, copy_cursor_x=None, copy_cursor_y=None, current_file=None, cursor_character=None, cursor_flag=None, cursor_x=None, cursor_y=None, history_bytes=None, history_limit=None, history_size=None, insert_flag=None, keypad_cursor_flag=None, keypad_flag=None, last_window_index=None, line=None, mouse_all_flag=None, mouse_any_flag=None, mouse_button_flag=None, mouse_sgr_flag=None, mouse_standard_flag=None, next_session_id=None, origin_flag=None, pane_active=None, pane_at_bottom=None, pane_at_left=None, pane_at_right=None, pane_at_top=None, pane_bg=None, pane_bottom=None, pane_current_command=None, pane_current_path=None, pane_dead=None, pane_dead_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_format=None, pane_height=None, pane_id=None, pane_in_mode=None, pane_index=None, pane_input_off=None, pane_last=None, pane_left=None, pane_marked=None, pane_marked_set=None, pane_mode=None, pane_path=None, pane_pid=None, pane_pipe=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_synchronized=None, pane_tabs=None, pane_title=None, pane_top=None, pane_tty=None, pane_width=None, pid=None, scroll_position=None, scroll_region_lower=None, scroll_region_upper=None, search_match=None, selection_end_x=None, selection_end_y=None, selection_start_x=None, selection_start_y=None, session_activity=None, session_alerts=None, session_attached=None, session_attached_list=None, session_created=None, session_format=None, session_group=None, session_group_attached=None, session_group_attached_list=None, session_group_list=None, session_group_many_attached=None, session_group_size=None, session_grouped=None, session_id=None, session_last_attached=None, session_many_attached=None, session_marked=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_clients_list=None, window_active_sessions=None, window_active_sessions_list=None, window_activity=None, window_activity_flag=None, window_bell_flag=None, window_bigger=None, window_cell_height=None, window_cell_width=None, window_end_flag=None, window_flags=None, window_format=None, window_height=None, window_id=None, window_index=None, window_last_flag=None, window_layout=None, window_linked=None, window_linked_sessions=None, window_linked_sessions_list=None, window_marked_flag=None, window_name=None, window_offset_x=None, window_offset_y=None, window_panes=None, window_raw_flags=None, window_silence_flag=None, window_stack_index=None, window_start_flag=None, window_visible_layout=None, window_width=None, window_zoomed_flag=None, wrap_flag=None) ¶

Parameters:

server (Server)
active_window_index (str | None)
alternate_saved_x (str | None)
alternate_saved_y (str | None)
buffer_name (str | None)
buffer_sample (str | None)
buffer_size (str | None)
client_activity (str | None)
client_cell_height (str | None)
client_cell_width (str | None)
client_control_mode (str | None)
client_created (str | None)
client_discarded (str | None)
client_flags (str | None)
client_height (str | None)
client_key_table (str | None)
client_last_session (str | None)
client_mode_format (str | None)
client_name (str | None)
client_pid (str | None)
client_prefix (str | None)
client_readonly (str | None)
client_session (str | None)
client_termfeatures (str | None)
client_termname (str | None)
client_termtype (str | None)
client_tty (str | None)
client_uid (str | None)
client_user (str | None)
client_utf8 (str | None)
client_width (str | None)
client_written (str | None)
command_list_alias (str | None)
command_list_name (str | None)
command_list_usage (str | None)
config_files (str | None)
copy_cursor_line (str | None)
copy_cursor_word (str | None)
copy_cursor_x (str | None)
copy_cursor_y (str | None)
current_file (str | None)
cursor_character (str | None)
cursor_flag (str | None)
cursor_x (str | None)
cursor_y (str | None)
history_bytes (str | None)
history_limit (str | None)
history_size (str | None)
insert_flag (str | None)
keypad_cursor_flag (str | None)
keypad_flag (str | None)
last_window_index (str | None)
line (str | None)
mouse_all_flag (str | None)
mouse_any_flag (str | None)
mouse_button_flag (str | None)
mouse_sgr_flag (str | None)
mouse_standard_flag (str | None)
next_session_id (str | None)
origin_flag (str | None)
pane_active (str | None)
pane_at_bottom (str | None)
pane_at_left (str | None)
pane_at_right (str | None)
pane_at_top (str | None)
pane_bg (str | None)
pane_bottom (str | None)
pane_current_command (str | None)
pane_current_path (str | None)
pane_dead (str | None)
pane_dead_signal (str | None)
pane_dead_status (str | None)
pane_dead_time (str | None)
pane_fg (str | None)
pane_format (str | None)
pane_height (str | None)
pane_id (str | None)
pane_in_mode (str | None)
pane_index (str | None)
pane_input_off (str | None)
pane_last (str | None)
pane_left (str | None)
pane_marked (str | None)
pane_marked_set (str | None)
pane_mode (str | None)
pane_path (str | None)
pane_pid (str | None)
pane_pipe (str | None)
pane_right (str | None)
pane_search_string (str | None)
pane_start_command (str | None)
pane_start_path (str | None)
pane_synchronized (str | None)
pane_tabs (str | None)
pane_title (str | None)
pane_top (str | None)
pane_tty (str | None)
pane_width (str | None)
pid (str | None)
scroll_position (str | None)
scroll_region_lower (str | None)
scroll_region_upper (str | None)
search_match (str | None)
selection_end_x (str | None)
selection_end_y (str | None)
selection_start_x (str | None)
selection_start_y (str | None)
session_activity (str | None)
session_alerts (str | None)
session_attached (str | None)
session_attached_list (str | None)
session_created (str | None)
session_format (str | None)
session_group (str | None)
session_group_attached (str | None)
session_group_attached_list (str | None)
session_group_list (str | None)
session_group_many_attached (str | None)
session_group_size (str | None)
session_grouped (str | None)
session_id (str | None)
session_last_attached (str | None)
session_many_attached (str | None)
session_marked (str | None)
session_name (str | None)
session_path (str | None)
session_stack (str | None)
session_windows (str | None)
socket_path (str | None)
start_time (str | None)
uid (str | None)
user (str | None)
version (str | None)
window_active (str | None)
window_active_clients (str | None)
window_active_clients_list (str | None)
window_active_sessions (str | None)
window_active_sessions_list (str | None)
window_activity (str | None)
window_activity_flag (str | None)
window_bell_flag (str | None)
window_bigger (str | None)
window_cell_height (str | None)
window_cell_width (str | None)
window_end_flag (str | None)
window_flags (str | None)
window_format (str | None)
window_height (str | None)
window_id (str | None)
window_index (str | None)
window_last_flag (str | None)
window_layout (str | None)
window_linked (str | None)
window_linked_sessions (str | None)
window_linked_sessions_list (str | None)
window_marked_flag (str | None)
window_name (str | None)
window_offset_x (str | None)
window_offset_y (str | None)
window_panes (str | None)
window_raw_flags (str | None)
window_silence_flag (str | None)
window_stack_index (str | None)
window_start_flag (str | None)
window_visible_layout (str | None)
window_width (str | None)
window_zoomed_flag (str | None)
wrap_flag (str | None)

Return type:

None

_refresh(obj_key, obj_id, list_cmd='list-panes', list_extra_args=None) ¶ method[source] method[source] _refresh(obj_key, obj_id, list_cmd='list-panes', list_extra_args=None) ¶

Refresh dataclass fields from a single list-* row.

Used by the public refresh() methods on Pane, Window, Session, and Client. Each subclass guards its identity field (pane_id, window_id, session_id, client_name) against None before delegating here; this base method enforces the same precondition explicitly so the guarantee survives python -O, where an assert would be stripped.

Raises:

ValueError – When obj_id is None. Surfaces a clear error under python -O, matching the contract of the public refresh() methods.

Parameters:

obj_key (str)
obj_id (str)
list_cmd (ListCmd)
list_extra_args (ListExtraArgs)

Return type:

None