r/erlang • u/git-pull • 8h ago
libtmux-erlang 0.1: tmux client library for Erlang / BEAM
Hi all, I maintain libtmux, the Python library for tmux. I've been bringing the same sessions, windows and panes to Erlang. The core application is on Hex; it's still an early release.
It wraps tmux's CLI. Here I'm starting a server, finding a pane, sending some text and checking its screen. There's also an operation you can start and await separately, including a wait that times out while the work remains pending.
Compared with the released Python library, this has owned asynchronous operations, explicit cancellation, and query plans you can inspect before fetching. The objects are still tmux's sessions, windows and panes. I'm interested in how that fits Erlang's processes and ownership model.
A word on AI: It's experimental, and I used LLMs extensively to create this. Parts of this post were also drafted and tested with AI. My AI policy has more on that.
libtmux_erlang: tmux from Erlang
Hex · GitHub · Docs · API · Installation guide
Use a current Erlang/OTP 29 release, Rebar3, Linux and tmux 3.3a–3.8. Native records are experimental in OTP 29. You'll also need make and a C11 compiler. Installation builds an external helper for owning and retiring subprocesses; it isn't a NIF.
Start in an empty directory. Save as rebar.config; Rebar3 resolves this from Hex:
{deps, [libtmux_erlang]}.rebar3 compileKeep the resulting rebar.lock to retain the resolved package version and checksum.
Save as demo.erl. with_owned (source) starts a separate daemon and checks its cleanup, including when the callback raises.
-module(demo).
-export([run/0]).
run() ->
{ok, _} = application:ensure_all_started(libtmux_erlang),
Executable = list_to_binary(os:find_executable("tmux")),
{ok, ok} = tmux_server:with_owned(#{executable => Executable},
fun(Server) ->
{ok, _} = tmux_session:create(Server,
#{name => <<"demo">>, window_name => <<"editor">>,
launch => #{argv => [<<"/bin/cat">>]}}),
{ok, Initial} = tmux_server:snapshot(Server),
First = tmux_select:one_or_error(tmux_select:panes(Initial)),
{ok, Title} = tmux_command:raw(<<"select-pane">>,
[<<"-t">>, tmux_model:get(id, First), <<"-T">>, <<"build">>]),
{ok, _} = tmux_server:command(Server, Title, #{}),
{ok, Snapshot} = tmux_server:snapshot(Server),
Sessions = tmux_select:where(#{name => <<"demo">>},
tmux_select:sessions(Snapshot)),
Windows = tmux_select:where(#{name => <<"editor">>},
tmux_select:windows(Snapshot)),
Session = tmux_select:one_or_error(Sessions),
Window = tmux_select:one_or_error(Windows),
Panes = tmux_select:where(#{title => <<"build">>,
window => #{is => #{name => tmux_model:get(name, Window)}}},
tmux_select:panes(Snapshot)),
Pane = tmux_select:one_or_error(Panes),
io:format("~ts / ~ts / ~ts~n", [tmux_model:get(name, Session),
tmux_model:get(name, Window), tmux_model:get(title, Pane)]),
{ok, _} = tmux_pane:send_text(Pane, <<"build: complete">>),
{ok, _} = tmux_pane:send_keys(Pane, [enter]),
Deadline = erlang:monotonic_time(millisecond) + 5000,
ok = await_line(Pane, <<"build: complete">>, Deadline),
io:format("output: build: complete~n")
end),
ok.
await_line(Pane, Line, Deadline) ->
{ok, Bytes} = tmux_pane:capture(Pane, #{}),
case lists:member(Line, binary:split(Bytes, <<"\n">>, [global])) of
true -> ok;
false ->
case erlang:monotonic_time(millisecond) < Deadline of
true ->
receive after 20 -> await_line(Pane, Line, Deadline) end;
false -> error(output_timeout)
end
end.erlc -pa _build/default/lib/libtmux_erlang/ebin demo.erl &&
erl -noshell -pa . _build/default/lib/libtmux_erlang/ebin \
-eval 'demo:run(), halt().'demo / editor / build
output: build: completetmux_select:where (source) filters the captured graph. It doesn't contact tmux again. The pane example sends text to cat and reads the terminal's screen; it isn't isolated command stdout. Other clients can contribute output in a shared pane.
P.S. Change the window query from <<"editor">> to <<"editor2">>, keeping the creation name as it was. Compile and run it again. one_or_error raises:
no_matchone (source) instead returns a tagged result when you'd rather handle that branch yourself.
There is one core OTP application here. Persistent control attachments currently establish identity and manage the client lifetime. Sending commands and streaming pane output through that connection are still implementation work.
Query chaining and source plans
where (source) adds conditions to an immutable query. explain does no I/O; fetch is the point where the reads happen.
Save as query_demo.erl:
-module(query_demo).
-export([run/0]).
run() ->
{ok, _} = application:ensure_all_started(libtmux_erlang),
Executable = list_to_binary(os:find_executable("tmux")),
{ok, ok} = tmux_server:with_owned(#{executable => Executable},
fun(Server) ->
{ok, _} = tmux_session:create(Server,
#{name => <<"query-demo">>, window_name => <<"editor">>,
launch => #{argv => [<<"/bin/cat">>]}}),
Q0 = tmux_query:panes(Server),
Q1 = tmux_query:where(#{active => true}, Q0),
Q2 = tmux_query:where(
#{window => #{is => #{name => <<"editor">>}}}, Q1),
Query = tmux_query:pushdown(true, Q2),
Plan = tmux_query:explain(Query),
true = maps:get(pushdown, Plan),
complete_graph = maps:get(hydration, Plan),
io:format("native candidate filtering: ~p~n",
[maps:get(pushdown, Plan)]),
io:format("hydration: ~p~n", [maps:get(hydration, Plan)]),
{ok, Panes} = tmux_query:fetch(Query),
io:format("active editor panes: ~p~n", [tmux_select:size(Panes)])
end),
ok.erlc -pa _build/default/lib/libtmux_erlang/ebin query_demo.erl &&
erl -noshell -pa . _build/default/lib/libtmux_erlang/ebin \
-eval 'query_demo:run(), halt().'native candidate filtering: true
hydration: complete_graph
active editor panes: 1Native filtering is opt-in. It can add a candidate scan; the full graph is still read and the complete predicate is checked locally. So I wouldn't describe this as fewer subprocesses. Text and relationship conditions stay local, and reads of a changing server aren't atomic. The current snapshot path groups fields into framed entity scans; that is separate from grouping mutation commands.
Submit an operation, then await it
tmux_operation lets a process keep an operation handle while it does other work. An await timeout ends that wait, not the operation. This uses tmux's wait-for signal so there's something specific to await.
Save as operation_demo.erl:
-module(operation_demo).
-export([run/0]).
run() ->
{ok, _} = application:ensure_all_started(libtmux_erlang),
Executable = list_to_binary(os:find_executable("tmux")),
{ok, ok} = tmux_server:with_owned(#{executable => Executable},
fun(Server) ->
{ok, _} = tmux_session:create(Server,
#{name => <<"operation-demo">>,
launch => #{argv => [<<"/bin/cat">>]}}),
{ok, Wait} = tmux_command:raw(<<"wait-for">>, [<<"build-done">>]),
{ok, Operation} = tmux_operation:start(Server, Wait,
#{deadline_ms => 5000}),
{error, #{code := await_timeout}} =
tmux_operation:await(Operation, 0),
io:format("wait: pending; operation retained~n"),
{ok, Signal} = tmux_command:raw(<<"wait-for">>,
[<<"-S">>, <<"build-done">>]),
{ok, _} = tmux_server:command(Server, Signal, #{}),
{ok, #{exit_status := 0, cleanup := complete}} =
tmux_operation:await(Operation, 5000),
io:format("signal: received; client cleaned up~n")
end),
ok.erlc -pa _build/default/lib/libtmux_erlang/ebin operation_demo.erl &&
erl -noshell -pa . _build/default/lib/libtmux_erlang/ebin \
-eval 'operation_demo:run(), halt().'wait: pending; operation retained
signal: received; client cleaned upThis proves that the signal arrived. It doesn't prove a build ran: a real job needs to send its own completion signal and provide whatever result you need to check. Operations currently use bounded one-shot clients. Cancellation can leave an already-sent command's outcome unknown.
Control connection lifetime
The current control API owns an attachment and checks identity on that connection. It doesn't yet offer command submission or an output-event stream. Save as control_demo.erl:
-module(control_demo).
-export([run/0]).
run() ->
{ok, _} = application:ensure_all_started(libtmux_erlang),
Executable = list_to_binary(os:find_executable("tmux")),
{ok, ok} = tmux_server:with_owned(#{executable => Executable},
fun(Server) ->
{ok, Session} = tmux_session:create(Server,
#{name => <<"control-demo">>,
launch => #{argv => [<<"/bin/cat">>]}}),
{ok, Control} = tmux_control:attach(Server, Session, #{}),
try
{ok, #{phase := open, identity := same_connection}} =
tmux_control:status(Control),
{ok, Attached} = tmux_session:get(Server,
tmux_model:get(id, Session)),
io:format("attached clients: ~p~n",
[tmux_model:get(attached_count, Attached)])
after
ok = tmux_control:close(Control)
end,
{ok, #{phase := closed, cleanup := complete}} =
tmux_control:status(Control),
io:format("control client: closed~n")
end),
ok.erlc -pa _build/default/lib/libtmux_erlang/ebin control_demo.erl &&
erl -noshell -pa . _build/default/lib/libtmux_erlang/ebin \
-eval 'control_demo:run(), halt().'attached clients: 1
control client: closedThe attachment is closed before its parent server. We own this server and its session; attaching to somebody's existing session can also trigger their configured hooks.
I'd be interested in feedback on the operation handles and cleanup API from people using Erlang.
Related, I also released an elixir package for tmux as well!