xa.tmux

Pure tmux wrappers.

No Claude Code knowledge lives here. Every public function takes a binary keyword so callers can override the tmux executable (tests, cross-platform installs, remote-host bridges).

Key gotchas encoded below:

• session_target(name) returns f"{name}:" — the trailing colon is essential. A bare session name can be silently resolved as a window or pane spec and mis-target a different session.

• list_sessions returns an empty list (not raises) when the tmux server isn’t running; tmux exits non-zero in that case and we absorb it.

class xa.tmux.TmuxPane(target: str, pid: int, current_command: str, current_path: str)

Minimal view of one tmux pane, from list-panes -a.

class xa.tmux.TmuxSession(name: str, created: int, activity: int, attached: bool)

Minimal view of one tmux session, from list-sessions.

xa.tmux.capture_pane(name: str, *, lines: int = 200, binary: str = 'tmux') → str

Return the last lines of the targeted pane, or ‘’ on failure.

name may be a session name (targets its active pane) or a full pane ref (session:@w.%p) for an exact pane.

xa.tmux.descendants(pid: int) → list[int]

All transitive descendant PIDs of pid.

Scans /proc/*/status; silently tolerates races (processes dying mid-scan). Not available on non-Linux platforms — returns [] if /proc is absent.

xa.tmux.list_panes(*, binary: str = 'tmux') → list[TmuxPane]

Every pane on the server, or [] when no server is running.

target is the full pane ref, the same shape claude records in its ephemeral session file, so the two views join without parsing.

xa.tmux.list_sessions(*, binary: str = 'tmux') → list[TmuxSession]

Return all live tmux sessions; empty list if server isn’t running.

xa.tmux.new_session(name: str, *, command: str, binary: str = 'tmux') → None

Create a detached tmux session running command as its pane’s program.

command is passed to a shell: the caller is responsible for quoting. Use shlex.quote for untrusted parts.

xa.tmux.pane_count(name: str, *, binary: str = 'tmux') → int

Number of panes (across all windows) in the session; 0 if gone.

xa.tmux.pane_current_path(name: str, *, binary: str = 'tmux') → str | None

Working directory of the targeted pane’s program, or None.

This is where a pane’s shell would run a command, which is what claude remote-control -c keys its per-directory record on.

xa.tmux.pane_pid(name: str, *, binary: str = 'tmux') → int | None

Return the pid of the first pane’s program, or None if the session is gone.

xa.tmux.pane_pids(name: str, *, binary: str = 'tmux') → list[int]

PIDs of every pane program in the session (all windows, all panes).

Empty list when the session is gone. name may be a session name or a full pane ref — -s scopes to the containing session either way.

xa.tmux.pane_target(ref: str) → str

Target string for pane-scoped commands (capture, send-keys).

Accepts either a bare session name or a full tmux pane ref (session:@window.%pane — the shape claude records in its ephemeral session file). A bare name targets the session’s active pane, which may not be the claude pane in a multi-window session — pass the full ref whenever you have one. Session names in xa match [A-Za-z0-9_.-] so they can never contain a :.

>>> pane_target('foo')
'foo:'
>>> pane_target('foo:@1.%2')
'foo:@1.%2'

xa.tmux.pipe_pane_to_file(name: str, *, path: Path, binary: str = 'tmux') → None

Start streaming the pane’s output to path (append mode).

Uses -o so a duplicate call toggles the pipe off, matching edualc’s behavior. tmux stops piping automatically when the pane dies.

xa.tmux.proc_comm(pid: int) → str

Return the comm name of a pid (kernel-level process name), ‘’ if unreadable.

xa.tmux.rename_session(old_name: str, new_name: str, *, binary: str = 'tmux') → None

Rename a live tmux session.

Both names must match the strict [A-Za-z0-9_.-]{1,48} pattern used elsewhere in xa; callers should validate before calling.

xa.tmux.send_keys(name: str, *keys: str, binary: str = 'tmux') → None

Send one or more keys/strings to the targeted pane.

Always pass "Enter" for newline. name may be a session name (targets its active pane) or a full pane ref for an exact pane.

xa.tmux.session_target(name: str) → str

Return the canonical target string for a session.

>>> session_target('foo')
'foo:'