libtmux for Elixir
Capture and query tmux state, then act on exact session, window and pane references. Observations are immutable; enumeration never runs a command. Choose bounded one-shot execution or an explicitly qualified control connection.
Capture and filter · One-shot actions · Managed control · Owned examples
Status and requirements
The 0.0.1-alpha.2 core includes capture/filtering, domain actions, managed
execution and scoped connections. Workspace, MCP, Tracker and dependency
planners remain planned.
| Requirement | Scope |
|---|---|
| Elixir / OTP | Elixir 1.20.4 or later 1.20 patch, compiled for OTP 29; OTP 29.1.2 or later 29 patch |
| Runtime platform | Linux, with a C11 compiler and headers to build the external helper |
| tmux | Required compatibility cells: 3.3, 3.3a, 3.4 and 3.8; other versions need their own evidence |
| Dependencies | Zero third-party core runtime packages; no NIF |
The development selectors in .tool-versions do not extend
support to older OTP patches. Python is needed only for the optional owned
example runner and integration tooling. See setup.
Installation
Add the published alpha to your Mix dependencies:
{:libtmux, "== 0.0.1-alpha.2"}Fetch dependencies:
$ mix deps.getStart with the short installed-consumer capture/filter program. It accepts an absolute executable and the socket of the existing server you select. It does not create a server or attach a control client.
Choose a task
| Task | Guide |
|---|---|
| Capture and query locally | First task, filtering |
| Split, rename, send input, capture screen bytes | One-shot actions |
| Reuse a connection and reclaim completed work | Managed control |
| Run a private demonstration with verified cleanup | Owned server |
| Inspect retained operations and both transports | Advanced execution |
Default capture budgets are 5000ms, 512 commands, 1024 contextual rows and 8 MiB total encoded output. Limits fail explicitly. Managed execution reclaims records only after wire retirement; retained operations remain available when needed. Timeouts do not imply no effects or authorize replay. Domain bang functions return completed values or raise with failure evidence. Lower-level Control and Operation bangs preserve canonical outcomes as values. See the relevant task guide before handling failures.
Concepts and reference
Read the mental model for server, snapshot, reference and operation lifetimes. Observations and the generated schema describe captured coverage and relationships. Public modules carry specs, types and linked examples in the API reference.
Encoding and ownership explain runtime constraints. Design and implementation contracts distinguish implemented core behavior from planned consumer packages. The core never depends on workspace or MCP.
Contributing
Follow Contributing, Writing and AGENTS.md. Check a packed artifact and all public examples outside the checkout:
$ MIX_ENV=test mix run scripts/check_package.exs --examplesThat command requires the Linux development prerequisites and tmux. The contribution guide lists pure checks, the required runtime matrix, rendered docs and package verification. Local checks do not establish hosted delivery.
Related projects: libtmux for Python, libtmux ports, and tmux. Artwork. Licensed under the MIT License.