Core LibraryAPI Reference

Choose documentation 1

latest

Current version

latest
English

Prerelease This site documents an alpha of libtmux. Its structure, URLs and APIs are subject to change.

class libtmux-kotlin latest

Server

Package io.github.libtmux.kotlin.Server io.github.libtmux.kotlin

Manages sessions, windows, and panes on a tmux server.

View as Markdown

Source and package
Module
io.github.libtmux.kotlin
Package
io.github.libtmux:libtmux-kotlin
Source
libtmux-kotlin/src/main/kotlin/io/github/libtmux/kotlin/Server.kt
Other languages
PythonRubyLuaTypeScriptRustGoJavaC#C++SwiftScala F#
public class Server : AutoCloseable
class [source]

Description#

Use open with a ServerConfig to select a server by socket name or path. From this object, create sessions or query the server's existing sessions, windows, and panes. Each Session contains windows, and each Window contains panes.

Operations that contact tmux are suspend functions dispatched through policy . Call close after the last operation to release resources owned by this object. The tmux server and its sessions keep running.

asJava exposes the underlying JavaServer for interoperability. Both objects share the same resources, so closing either closes both.

Examples#

Connect to a private tmux server. Use JDK 25, Git, and tmux 3.2a through 3.7c on Linux, with /bin/cat and /bin/sh available. In an empty directory, fetch the documented library revision:

Terminal window
$ git clone https://github.com/libtmux/libtmux-java.git libtmux-source && \
git -C libtmux-source checkout f56392b5d9bc7f1f9c1631842333fb90f3d82d40

Save this consumer setup as settings.gradle.kts: View source

rootProject.name = "api-example"
includeBuild("libtmux-source")

Save this consumer setup as build.gradle.kts: View source

plugins {
kotlin("jvm") version "2.4.10"
application
}
repositories { mavenCentral() }
dependencies {
implementation("io.github.libtmux:libtmux-kotlin:0.0.1-alpha.17-SNAPSHOT")
}
java { toolchain { languageVersion.set(JavaLanguageVersion.of(25)) } }
kotlin { jvmToolchain(25) }
application { mainClass.set(providers.gradleProperty("exampleMain")) }

Save this consumer setup as gradle.properties: View source

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

Save this launcher as run.sh. It creates and stops a private tmux server, including after program failure. A shutdown failure retains its socket directory and exits unsuccessfully. View source

#!/bin/sh
set -eu
if [ "$#" -eq 0 ]; then
printf 'Usage: sh run.sh program [arguments...]\n' >&2
exit 2
fi
binary=$(command -v "${TMUX_BIN:-tmux}")
mkdir -p /tmp/libtmux-java-dev
directory=$(mktemp -d /tmp/libtmux-java-dev/api.XXXXXX)
socket="$directory/tmux.sock"
config="$directory/tmux.conf"
alive() {
"$binary" -S "$socket" display-message -p '#{pid}' >/dev/null 2>&1
}
cleanup() {
status=$?
trap - 0 HUP INT TERM
if alive; then
if ! "$binary" -S "$socket" kill-server; then
printf 'Cannot stop tmux; kept %s\n' "$directory" >&2
exit 1
fi
attempts=0
while alive && [ "$attempts" -lt 100 ]; do
sleep 0.05
attempts=$((attempts + 1))
done
if alive; then
printf 'tmux is still responding; kept %s\n' "$directory" >&2
exit 1
fi
fi
rm -rf "$directory" || exit 1
exit "$status"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM
unset TMUX TMUX_PANE
printf 'set-option -g default-shell /bin/sh\n' > "$config"
"$binary" -S "$socket" -f "$config" new-session -d -s work-one -n editor /bin/cat
"$binary" -S "$socket" split-window -h -t '=work-one:editor' /bin/cat
"$binary" -S "$socket" new-window -d -t '=work-one' -n logs /bin/cat
"$binary" -S "$socket" new-session -d -s work-two -n editor /bin/cat
"$@" "$binary" "$socket" "$config"
"$binary" -S "$socket" has-session -t '=work-one'
"$binary" -S "$socket" has-session -t '=work-two'

Save this complete program as src/main/kotlin/Connect.kt. It opens an ordinary client for the launcher's server; closing the client releases its transport. View source

package io.github.libtmux.examples.api.kotlin
import io.github.libtmux.ServerConfig
import io.github.libtmux.ServerEndpoint
import io.github.libtmux.kotlin.*
import java.nio.file.Path
import kotlin.system.exitProcess
import kotlinx.coroutines.runBlocking
/** Connect to a private tmux server. */
fun main(args: Array<String>) {
try {
require(args.size == 3) { "expected: tmux-binary socket-path config-file" }
val config = ServerConfig.builder()
.binary(args[0])
.endpoint(ServerEndpoint.socketPath(Path.of(args[1])))
.configFile(Path.of(args[2]))
.build()
runBlocking {
withServer(config) { server ->
println("connected=${server.isAlive()}")
}
}
} catch (error: Exception) {
if (error is InterruptedException) Thread.currentThread().interrupt()
System.err.println("Example failed: ${error.message}")
exitProcess(1)
}
}

Build the minimal consumer and run the saved program with the private fixture. An operation or cleanup error makes the command exit unsuccessfully:

Terminal window
$ ./libtmux-source/gradlew --project-dir . --console=plain --quiet \
installDist -PexampleMain=io.github.libtmux.examples.api.kotlin.ConnectKt && \
sh run.sh build/install/api-example/bin/api-example

Expected output:

connected=true

Discussed in Server, session, window, pane · Attaching to tmux , Coroutines and flows , Getting started

In other ports A tmux server

Members49 members#

Collections and queries6 members#

  • sessions method Every session, captured now.
  • windows method Captures every winlink, preserving each session and index placement.
  • panes method Captures every pane on the server.
  • clients method Captures every attached client.
  • buffers method The server's paste buffers, which every session shares.
  • snapshot method Captures the whole hierarchy in at most four listings, retrying once if the server is replaced.

Common operations14 members#

  • newSession method Creates a detached session and returns that exact session.
  • killServer method Ends the tmux server and every session on it.
  • hooks method The global hooks every session inherits.
  • keys method The server's key bindings: prefix when binding, every table when listing.
  • liveState method A live, continuously rebuilt view of server , as a StateFlow .
  • batch method Collects several commands to run in one tmux invocation.
  • chain method Starts a chain of commands where each one acts on what the last one made.
  • commands method The commands this tmux knows.
  • messageLog method The server's message log.
  • prompt method The command prompt's history.
  • session method The one session this expression matches, captured now.
  • sessionOrNull method The one session this expression matches, or null when none does.
  • shell method Shell commands run by tmux, and tmux commands chosen by a shell exit status.
  • withLiveState method As liveState , scoped to block : opens the live view, runs block against it, and cancels the background pump before returning — the same withServer / withControl shape, for the one resource liveState itself cannot close on its own.

Other members29 members#

  • admissionBound property How many tmux commands this server's transport runs at once, from ExecutionPolicy.default.
  • asJava property The Java server this wraps, for an operation this class does not mirror or a Java API that takes one. The same object, not a copy: closing either closes both.
  • attachedSessions method Captures every session a client is attached to.
  • channel method One of this server's wait-for channels, which is where a signal is sent and waited for.
  • close method Releases an owned transport. Idempotent, and never kills tmux.
  • cmd method Runs one tmux command against this server.
  • Companion module
  • config property How this server was configured.
  • control method Attaches a control client to this session's server, and only to the process this capture named.
  • environment method The server's environment, which every session inherits and every new process is given.
  • expand method Expands a tmux format against the server, and answers with what it came to.
  • globalOptions method The global session options every session inherits unless it sets its own.
  • hasSession method Whether a session with this name exists.
  • identity property Which server this is. Every handle taken from it is scoped by this.
  • isAlive method Whether the server is running and answering.
  • killSession method Ends the session with this name, and everything in it.
  • lock method Locks every client attached to this server.
  • options method The server-wide options, the ones tmux keeps once per server.
  • pane method The one pane this expression matches, captured now.
  • paneFields method Chosen fields for every pane on the server, from one listing.
  • paneOrNull method The one pane this expression matches, or null when none does.
  • policy property
  • requireAlive method Requires a running tmux daemon that answers the liveness probe.
  • run method Runs a command that is expected to work, and raises when it did not.
  • sourceFile method Runs a file of tmux commands, as a configuration file would be run.
  • variables method Reads only validated tmux variable names, never caller-authored format syntax.
  • version method Which tmux this server is running.
  • window method The one window link this expression matches, captured now.
  • windowOrNull method The one window link this expression matches, or null when none does.
Esc

Type to search.