libtmux_erlang is an Erlang tmux client library. Create sessions, windows and panes, capture their relationships, and filter the captured values locally. Source queries and mutations execute explicitly through owned operations.

Inspect a captured graph · Server API · Changelog

Add the core application

Use Erlang/OTP 29.1.2, Rebar3 3.28.0, Linux x86_64 or arm64, tmux 3.3a–3.8, and make with a C11 compiler. The helper builds from packaged source. BEAM runtime dependencies are OTP libraries; native records are experimental in OTP 29.

This application is unreleased. Add its source dependency to rebar.config:

{deps, [
    {libtmux_erlang, {git_subdir,
        "https://github.com/libtmux/libtmux-erlang.git",
        {branch, "master"}, "apps/libtmux_erlang"}}
]}.

Commit rebar.lock and add libtmux_erlang to your application's applications list. The installation guide walks through a separate Rebar3 consumer.

Inspect a captured graph

This complete module counts physical sessions, windows and panes on an explicitly selected existing socket. Closing the library endpoint preserves the borrowed server and its sessions.

-module(inspect_demo).
-moduledoc "Inspect an existing tmux socket without changing its sessions.".
-export([run/2]).

-spec run(binary(), binary()) -> map().
run(Socket, Executable) ->
    {ok, _} = application:ensure_all_started(libtmux_erlang),
    Endpoint = #{socket_path => Socket, executable => Executable},
    {ok, Result} = tmux_server:with_server(Endpoint, fun(Server) ->
        {ok, Snapshot} = tmux_server:snapshot(Server),
        #{sessions => length(tmux_snapshot:sessions(Snapshot)),
          windows => length(tmux_snapshot:windows(Snapshot)),
          panes => length(tmux_snapshot:panes(Snapshot))}
    end),
    Result.

From the repository root, compile the applications:

$ mise exec -- rebar3 compile

Run the module against a temporary server owned by the example runner:

$ mise exec -- escript tools/run_examples.escript inspect

The runner checks its result and retires its server and clients. The installed consumer check repeats the same program outside the umbrella.

The server API documents endpoint ownership and observation. The snapshot API documents physical rows, session memberships and relationship coverage.

Create, query and act

• Create and query a workspace: build three panes, query their windows, rename one and compare captured values.
• Traverse linked windows: distinguish physical objects from session memberships and preserve counts and ordering.
• Filter captured data: map criteria, native Boolean functions, relation quantifiers and explicit source-query execution.
• Submit and cancel work: wait for completion, check the exit status and capture output bytes.
• Build the API browser: native module, function and type documentation with checked links to captured source.

Check support and ownership

Support covers tmux 3.3a–3.8; routine CI tests both endpoints on Ubuntu 24.04 x86_64 and arm64 with OTP 29.1.2. One-shot operations and explicit control attachment are qualified. Control command submission and output streams remain implementation work. See support and gaps.

Selections retain their captured graph. Convert to ordinary rows when storing results without that context. Actions can encounter a vanished target or an uncertain outcome; the ownership guide explains endpoint lifetimes and cleanup evidence.

The core depends on OTP applications. See project policy, contributor checks, and the MIT license.