tmux client library for Julia

Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents.

Topics

Subject-by-subject, with Julia in every code block.

Examples

Complete programs, sourced from the code each port tests.

Install

using Pkg
Pkg.add(PackageSpec(url="https://github.com/libtmux/libtmux-julia.git", rev="master"))

At a glance

Server → Session → Window → Pane. Each level of the tmux hierarchy has its own entry in the Julia API, with the tmux object it wraps.

Type	Wraps
`LibTmux.Server`	A tmux server
`LibTmux.SessionSnapshot`	A session, ID `$n`
`LibTmux.WindowSnapshot`	A window in a session, ID `@n`
`LibTmux.PaneSnapshot`	A pane in a window, ID `%n`

What it does

Start with Julia

+ Error handling + Cleanup

using LibTmux

owned = open_server()
server = owned.server

session = new_session(server; name="demo", command=["/bin/cat"])
pane = only(panes(snapshot(server))).ref
split_window(server, pane; direction=:below, command=["/bin/cat"])
new_window(server, session; name="logs", command=["/bin/cat"])

snap = snapshot(server)
@assert isempty(strip(capture_pane(server, pane)))
println(only(sessions(snap)).name, ": ",
        length(windows(snap)), " windows, ",
        length(panes(snap)), " panes")

using LibTmux

try
    owned = open_server()
    server = owned.server

    session = new_session(server; name="demo", command=["/bin/cat"])
    pane = only(panes(snapshot(server))).ref
    split_window(server, pane; direction=:below, command=["/bin/cat"])
    new_window(server, session; name="logs", command=["/bin/cat"])

    snap = snapshot(server)
    @assert isempty(strip(capture_pane(server, pane)))
    println(only(sessions(snap)).name, ": ",
            length(windows(snap)), " windows, ",
            length(panes(snap)), " panes")
catch error
    println(stderr, "tmux quickstart failed: ", sprint(showerror, error))
    rethrow()
end

using LibTmux

with_server() do server
    session = new_session(server; name="demo", command=["/bin/cat"])
    pane = only(panes(snapshot(server))).ref
    split_window(server, pane; direction=:below, command=["/bin/cat"])
    new_window(server, session; name="logs", command=["/bin/cat"])

    snap = snapshot(server)
    @assert isempty(strip(capture_pane(server, pane)))
    println(only(sessions(snap)).name, ": ",
            length(windows(snap)), " windows, ",
            length(panes(snap)), " panes")
end

using LibTmux

try
    with_server() do server
        session = new_session(server; name="demo", command=["/bin/cat"])
        pane = only(panes(snapshot(server))).ref
        split_window(server, pane; direction=:below, command=["/bin/cat"])
        new_window(server, session; name="logs", command=["/bin/cat"])

        snap = snapshot(server)
        @assert isempty(strip(capture_pane(server, pane)))
        println(only(sessions(snap)).name, ": ",
                length(windows(snap)), " windows, ",
                length(panes(snap)), " panes")
    end
catch error
    println(stderr, "tmux quickstart failed: ", sprint(showerror, error))
    rethrow()
end

Run this example

Julia 1.13.0, Git, POSIX shell and tmux on Linux.

Save the program above as quickstart.jl in a new directory, along with the files below.

Cleanup is omitted; the private tmux server and its temporary files may remain. Select Cleanup to remove them when the program finishes. The program stops its private tmux server and removes any temporary files it created when it finishes. Error handling adds diagnostics; every version checks required results and deadlines.

Setup and run

git init -q source
git -C source fetch -q --depth=1 \
  https://github.com/libtmux/libtmux-julia.git \
  6f62bd72cb8d99f3759ca5e2cc3591165a03c768
git -C source checkout -q --detach FETCH_HEAD

unset TMUX TMUX_PANE
export ENV=/dev/null BASH_ENV=/dev/null SHELL=/bin/sh
julia --startup-file=no --project=source quickstart.jl

Expected output

demo: 2 windows, 3 panes

Library revision: 6f62bd72cb8d.

Typed API

Typed objects instead of parsed format strings: LibTmux.PaneSnapshot
Addressing by tmux ID: LibTmux.TmuxID
Filtering and queries over tmux objects: LibTmux.PaneWhere
Typed errors instead of exit codes and stderr: LibTmux.LibTmuxError

What you get over the tmux CLI

Connect to or start a tmux server: LibTmux.open_server
Traversal from a server down to its panes: LibTmux.panes
Send keys to a pane: LibTmux.send_keys
Watch for changes through tmux control mode: LibTmux.open_control
Capture pane contents: LibTmux.capture_pane
Arguments passed as a list, with no shell quoting: LibTmux.TmuxCommand
A typed error when the running tmux lacks a feature: LibTmux.UnsupportedCapability

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

tmux client library for Julia

Guides

Topics

Examples

API reference

Install

At a glance

What it does

Start with Julia

Setup and run

Expected output

Typed API

What you get over the tmux CLI