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.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 session’s first pane, or ‘’ on failure.

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_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_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.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 pane. Always pass "Enter" for newline.

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

Return the canonical target string for a session.

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