tmux client library for Java

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

Quickstart

Install the package and run a complete program.

Topics

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

Examples

Complete programs, sourced from the code each port tests.

Testing

Test code that uses tmux with an isolated server.

Install

implementation("io.github.libtmux:libtmux:0.1.0")

At a glance

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

Type	Wraps
`io.github.libtmux.Server`	A tmux server
`io.github.libtmux.Session`	A session, ID `$n`
`io.github.libtmux.Window`	A window in a session, ID `@n`
`io.github.libtmux.Pane`	A pane in a window, ID `%n`

What it does

Start with Java

+ Error handling + Cleanup

import io.github.libtmux.Server;
import io.github.libtmux.ServerConfig;
import io.github.libtmux.ServerEndpoint;
import io.github.libtmux.TextOutcome;
import java.nio.file.Path;
import java.time.Duration;
import java.util.UUID;

public final class Main {
    public static void main(String[] args) throws Exception {
        var socket = "libtmux-home-" + UUID.randomUUID();
        var config = ServerConfig.builder()
                .endpoint(ServerEndpoint.namedSocket(socket))
                .configFile(Path.of("/dev/null"))
                .defaultTimeout(Duration.ofSeconds(5))
                .build();

        try (Server server = Server.open(config)) {
            var session = server.newSession("demo");
            var window = session.newWindow("build");
            var pane = window.split();

            pane.sendLine("printf '\\nhello from %s\\n' libtmux");
            var seen = pane.awaitText(
                    "hello from libtmux",
                    Duration.ofSeconds(5));
            if (seen == TextOutcome.TIMED_OUT) {
                throw new IllegalStateException("output did not arrive");
            }

            var lines = pane.capture();
            if (lines.stream().noneMatch(
                    line -> line.strip().equals("hello from libtmux"))) {
                throw new IllegalStateException(
                        "capture is missing the output line");
            }

            System.out.println("hello from libtmux");
        }
    }
}

import io.github.libtmux.Server;
import io.github.libtmux.ServerConfig;
import io.github.libtmux.ServerEndpoint;
import io.github.libtmux.TextOutcome;
import java.nio.file.Path;
import java.time.Duration;
import java.util.UUID;

public final class Main {
    public static void main(String[] args) throws Exception {
        var socket = "libtmux-home-" + UUID.randomUUID();
        var config = ServerConfig.builder()
                .endpoint(ServerEndpoint.namedSocket(socket))
                .configFile(Path.of("/dev/null"))
                .defaultTimeout(Duration.ofSeconds(5))
                .build();

        try (Server server = Server.open(config)) {
            try {
                var session = server.newSession("demo");
                var window = session.newWindow("build");
                var pane = window.split();

                pane.sendLine("printf '\\nhello from %s\\n' libtmux");
                var seen = pane.awaitText(
                        "hello from libtmux",
                        Duration.ofSeconds(5));
                if (seen == TextOutcome.TIMED_OUT) {
                    throw new IllegalStateException("output did not arrive");
                }

                var lines = pane.capture();
                if (lines.stream().noneMatch(
                        line -> line.strip().equals("hello from libtmux"))) {
                    throw new IllegalStateException(
                            "capture is missing the output line");
                }

                System.out.println("hello from libtmux");
            } catch (Exception error) {
                throw new IllegalStateException(
                        "tmux quickstart failed", error);
            }
        }
    }
}

import io.github.libtmux.Server;
import io.github.libtmux.ServerConfig;
import io.github.libtmux.ServerEndpoint;
import io.github.libtmux.TextOutcome;
import java.nio.file.Path;
import java.time.Duration;
import java.util.UUID;

public final class Main {
    public static void main(String[] args) throws Exception {
        var socket = "libtmux-home-" + UUID.randomUUID();
        var config = ServerConfig.builder()
                .endpoint(ServerEndpoint.namedSocket(socket))
                .configFile(Path.of("/dev/null"))
                .defaultTimeout(Duration.ofSeconds(5))
                .build();

        try (Server server = Server.open(config)) {
            try {
                var session = server.newSession("demo");
                var window = session.newWindow("build");
                var pane = window.split();

                pane.sendLine("printf '\\nhello from %s\\n' libtmux");
                var seen = pane.awaitText(
                        "hello from libtmux",
                        Duration.ofSeconds(5));
                if (seen == TextOutcome.TIMED_OUT) {
                    throw new IllegalStateException("output did not arrive");
                }

                var lines = pane.capture();
                if (lines.stream().noneMatch(
                        line -> line.strip().equals("hello from libtmux"))) {
                    throw new IllegalStateException(
                            "capture is missing the output line");
                }

                System.out.println("hello from libtmux");
            } finally {
                server.killServer();
            }
        }
    }
}

import io.github.libtmux.Server;
import io.github.libtmux.ServerConfig;
import io.github.libtmux.ServerEndpoint;
import io.github.libtmux.TextOutcome;
import java.nio.file.Path;
import java.time.Duration;
import java.util.UUID;

public final class Main {
    public static void main(String[] args) throws Exception {
        var socket = "libtmux-home-" + UUID.randomUUID();
        var config = ServerConfig.builder()
                .endpoint(ServerEndpoint.namedSocket(socket))
                .configFile(Path.of("/dev/null"))
                .defaultTimeout(Duration.ofSeconds(5))
                .build();

        try (Server server = Server.open(config)) {
            try {
                var session = server.newSession("demo");
                var window = session.newWindow("build");
                var pane = window.split();

                pane.sendLine("printf '\\nhello from %s\\n' libtmux");
                var seen = pane.awaitText(
                        "hello from libtmux",
                        Duration.ofSeconds(5));
                if (seen == TextOutcome.TIMED_OUT) {
                    throw new IllegalStateException("output did not arrive");
                }

                var lines = pane.capture();
                if (lines.stream().noneMatch(
                        line -> line.strip().equals("hello from libtmux"))) {
                    throw new IllegalStateException(
                            "capture is missing the output line");
                }

                System.out.println("hello from libtmux");
            } catch (Exception error) {
                throw new IllegalStateException(
                        "tmux quickstart failed", error);
            } finally {
                server.killServer();
            }
        }
    }
}

Run this example

JDK 25 and tmux on Linux/macOS

Save the program above as src/main/java/Main.java 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.

build.gradle.kts

plugins {
    application
}

repositories { mavenCentral() }

dependencies {
    implementation("io.github.libtmux:libtmux:0.1.0")
}

java { toolchain { languageVersion.set(JavaLanguageVersion.of(25)) } }

application { mainClass.set(providers.gradleProperty("exampleMain")) }

settings.gradle.kts

rootProject.name = "api-example"

gradle.properties

org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=768m -Dfile.encoding=UTF-8
kotlin.daemon.jvmargs=-Xmx2g
org.gradle.workers.max=2

Setup and run

# Save the files above at their displayed relative paths.
git clone https://github.com/libtmux/libtmux-java.git libtmux-source
git -C libtmux-source checkout --detach 5c181887918351119bfdb3a046719fa792048e59
./libtmux-source/gradlew --project-dir . --console=plain --no-daemon --max-workers=2 \
  installDist -PexampleMain=Main
SHELL=/bin/sh build/install/api-example/bin/api-example

Expected output

hello from libtmux

Library revision: 5c1818879183.

Typed API

Typed objects instead of parsed format strings: io.github.libtmux.snapshot.PaneState
Addressing by tmux ID: io.github.libtmux.PaneId
Filtering and queries over tmux objects: io.github.libtmux.query.FilterExpr
Typed errors instead of exit codes and stderr: io.github.libtmux.exception.LibTmuxException

What you get over the tmux CLI

Connect to or start a tmux server: io.github.libtmux.Server.open
Traversal from a server down to its panes: io.github.libtmux.Server.panes
Send keys to a pane: io.github.libtmux.Pane.sendKeys
Watch for changes through tmux control mode: io.github.libtmux.control.ControlClient
Capture pane contents: io.github.libtmux.Pane.capture
Arguments passed as a list, with no shell quoting: io.github.libtmux.Server.cmd
A typed error when the running tmux lacks a feature: io.github.libtmux.exception.UnsupportedFeatureException

Testing

Run tests against an isolated tmux server: io.github.libtmux.junit5.TmuxExtension.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

tmux client library for Java

Quickstart

Guides

Topics

Examples

API reference

Testing

Install

At a glance

What it does

Start with Java

Setup and run

Expected output

Typed API

What you get over the tmux CLI

Testing