# tmux_session

- **Package:** libtmux_erlang
- **Language:** Erlang
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-erlang/blob/d1b6308440cf9eb8f6647e7ae434bce60e849368/apps/libtmux_erlang/src/tmux_session.erl#L1
- **Page:** https://libtmux.org/en/erlang/latest/reference/tmux_session/

Create and observe sessions, or act on a session's registered stable ID.

`create/2` accepts name, window_name, width, height, cwd, env,
launch and detach. Creation defaults to detached with tmux's configured
shell/command. launch is default_shell, an argv map, or an explicit shell map.
env augments tmux's inherited environment. tmux supplies PATH, SHELL, PWD and
TMUX_PANE after that merge, so those entries may be replaced. Names and cwd
are literal format values; tmux's stored name rules still apply. Creation
never adopts an existing session by name.

An empty shell command can exit immediately and remove its session. It does
not request the empty-pane behavior of [split-window](/en/tmux/latest/manual/split-window/). Use a running program
when later operations require the session to remain alive.

`create/2` and `get/2` explicitly read the
new/current row through several one-shot commands. These reads are not atomic.
If creation succeeds but observation fails, the error retains mutation =
completed and the original command result. `rename/2` and
`kill/1` return command results without refreshing the input
record. Detached rows require `tmux_server:bind/2` before actions.
`rename_command/2` builds a reusable value without tmux I/O; the other calls
perform I/O after validation.

`select/2` switches one explicitly named attached client to a session. It
never attaches a client or infers the current client. Use
`tmux_window_link:select/1` to select a session's window membership instead.

## Members

### Common operations

- [`create/2`](/en/erlang/latest/reference/tmux_session-create-2/) (function): Create a detached session by default and explicitly observe the returned row. Options include name, window_name, dimensions, cwd, env and launch. Performs I/O; an observation failure after successful creation retains mutation = completed and the original command result. Existing names are not adopted.
- [`kill/1`](/en/erlang/latest/reference/tmux_session-kill-1/) (function): Destroy this registered session. Performs I/O and returns the command result; this is a destructive session action, not endpoint cleanup. References must belong to a live registered owner.
- [`rename/2`](/en/erlang/latest/reference/tmux_session-rename-2/) (function): Rename the registered session using a literal name and return the command result. Performs I/O. Previously captured records keep their old names; detached or stale references fail validation before the action.
- [`get/2`](/en/erlang/latest/reference/tmux_session-get-2/) (function): Read fresh session fields through explicit one-shot commands. The session ID is stable within the observed server incarnation. Returns target_gone when tmux no longer has that session; it never refreshes an existing record.
- [`select/2`](/en/erlang/latest/reference/tmux_session-select-2/) (function): Switch an explicitly named attached client to this registered session, preserving the session environment. Performs I/O. See `select/3` for client lookup, environment updates and disconnection races.
- [`select/3`](/en/erlang/latest/reference/tmux_session-select-3/) (function): Switch one attached client, selected by its literal native client name or TTY path, to the session's registered stable ID. Performs I/O and returns the command result; existing rows remain captured values. Obtain the name from the caller's own client context, such as tmux's `client_name` format. There is no default client and this call never attaches one.
- [`rename_command/2`](/en/erlang/latest/reference/tmux_session-rename_command-2/) (function): Build a literal rename command without tmux I/O. Validates the row and keeps its captured origin; endpoint liveness is checked during execution. Submit the value to `tmux_server:command/3` or `tmux_operation:start/3` with its original endpoint. Existing session records retain their captured name.

### Other members

- [`create_options/0`](/en/erlang/latest/reference/t-tmux_session-create_options-0/) (typealias): Session creation options. Launch defaults to the configured shell; creation defaults to detached.
- [`select_options/0`](/en/erlang/latest/reference/t-tmux_session-select_options-0/) (typealias): Session selection options. update_environment defaults to false, preserving the destination environment.

## Guides

Pages that discuss `tmux_session`.

- [Native API documentation](/en/erlang/latest/guides/api-documentation/)