Attaching to tmux

Connect a Server to an explicit socket and find the existing work session. The program prints its name and leaves the tmux server running. It reports an error if the connection fails or the session is absent.

This controls tmux from your program. To open a session in your terminal, use tmux attach-session; the shared guide covers interactive attachment and detaching.

Connect to an existing server¶

Save the complete program as Connect.kt. LIBTMUX_SOCKET_PATH selects the existing server. The launcher below supplies a private socket for trying the example.

import io.github.libtmux.ServerConfig
import io.github.libtmux.ServerEndpoint
import io.github.libtmux.kotlin.sessions
import io.github.libtmux.kotlin.withServer
import java.nio.file.Path
import java.time.Duration
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val socket = requireNotNull(System.getenv("LIBTMUX_SOCKET_PATH")) {
        "Set LIBTMUX_SOCKET_PATH to an existing socket"
    }
    val config = ServerConfig.builder()
        .endpoint(ServerEndpoint.socketPath(Path.of(socket)))
        .defaultTimeout(Duration.ofSeconds(5))
        .build()
    withServer(config) { server ->
        val session = server.sessions().single { it.name == "work" }
        println(session.name)
    }
}

Setup and run¶

Use an empty directory on Linux with Git and tmux 3.2a or newer installed.

This example was checked with JDK 25.0.3, Kotlin 2.4.10.

Save this file beside the program using the displayed filename.

plugins {
    application
    kotlin("jvm") version "2.4.10"
}

repositories { mavenCentral() }
dependencies {
    implementation("io.github.libtmux:libtmux-kotlin:0.0.1-alpha.17-SNAPSHOT")
}
kotlin {
    jvmToolchain(25)
    sourceSets.main { kotlin.srcDir("."); kotlin.include("Connect.kt") }
}
application { mainClass.set("ConnectKt") }

Save this file beside the program using the displayed filename.

rootProject.name = "connect"
includeBuild("libtmux-source")

Save this file beside the program using the displayed filename.

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

Save the launcher as run.sh. It starts an isolated tmux server, runs the program, checks that the session still exists, then stops only that server. Cleanup runs after failures too. A failed shutdown keeps its socket directory and prints its location for inspection.

#!/bin/sh
set -eu

binary=$(command -v tmux)
directory=$(mktemp -d "${TMPDIR:-/tmp}/libtmux-kotlin-attach.XXXXXX")
socket="$directory/tmux.sock"

cleanup() {
    status=$?
    trap - 0 HUP INT TERM
    if [ -S "$socket" ] && ! "$binary" -S "$socket" kill-server; then
        printf 'Cannot stop tmux; kept %s\n' "$directory" >&2
        exit 1
    fi
    rm -rf "$directory" || exit 1
    exit "$status"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM

unset TMUX TMUX_PANE
export LIBTMUX_SOCKET_PATH="$socket" TMUX_BIN="$binary"
"$binary" -S "$socket" -f /dev/null new-session -d -s work /bin/cat
"$@"
"$binary" -S "$socket" has-session -t '=work'

Fetch the verified library revision, build, and run:

$ git clone https://github.com/libtmux/libtmux-java libtmux-source &&
  git -C libtmux-source checkout 85ebf6955e56703c5be74e2afd34a18309044741 &&
  sh run.sh ./libtmux-source/gradlew --project-dir . run --console=plain --max-workers=2

The program prints work. To use an existing server of your own, set LIBTMUX_SOCKET_PATH to its socket and run the program without the launcher. That launcher is responsible for the demonstration server’s lifetime.

Find or create a session¶

The example only looks up a session. If your application creates a session after an unsuccessful lookup, another client may create the same name between those operations. Handle the creation error instead of assuming the lookup reserves the name.

For a complete program that starts and owns its server, see Capture pane output.

Scripting & web

Compiled & native

JVM

.NET

tmux

Attaching to tmux

Connect to an existing server¶

Setup and run¶

Find or create a session¶