ScalaHome

Choose documentation 1

latest

Current version

latest
English

Early release libtmux is released, and its APIs may still change between releases. This site's structure and URLs may change too.

libtmux for Scala

Scala-based tmux client

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

Built on the Java library for JVM. The packages share their source repository and releases.

Example details
import io.github.libtmux.{ServerConfig, ServerEndpoint, TextOutcome}
import io.github.libtmux.scaladsl.{config => _, *}
import java.nio.file.Path
import java.time.Duration
import java.util.UUID
import scala.concurrent.duration.DurationInt
import scala.jdk.CollectionConverters.*
import scala.util.Using
object Main {
def main(args: Array[String]): Unit = {
val socket = s"libtmux-home-${UUID.randomUUID()}"
val config = ServerConfig.builder()
.endpoint(ServerEndpoint.namedSocket(socket))
.configFile(Path.of("/dev/null"))
.defaultTimeout(Duration.ofSeconds(5))
.build()
Using.resource(Server.open(config)) { server =>
val session = server.newSession("demo")
val active = session.activeWindow.get
val editor = active.rename("editor")
val left = editor.activePane.get
val right = left.split(_.toRight().detached())
val logs = session.newWindow(_.named("logs").detached())
right.sendLine("printf 'hello from %s\\n' tmux")
val seen = right.awaitText("hello from tmux", 5.seconds)
assert(seen != TextOutcome.TIMED_OUT)
right.select()
logs.select()
val snapshot = server.snapshot()
val sessions = snapshot.sessions().asScala
for (found <- sessions) {
println(s"session ${found.name()}")
for (win <- snapshot.windowsOf(found.id()).asScala) {
val at = win.context().index().value()
val panes = snapshot.panesOf(win.context()).asScala
val ids = panes.map(_.id().value()).mkString(" ")
println(s" window $at:${win.name()}: $ids")
}
}
val window = right.window
val owner = window.session
val id = right.id.value()
println(s"$id is in window ${window.name} of session ${owner.name}")
}
}
}
import io.github.libtmux.{ServerConfig, ServerEndpoint, TextOutcome}
import io.github.libtmux.scaladsl.{config => _, *}
import java.nio.file.Path
import java.time.Duration
import java.util.UUID
import scala.concurrent.duration.DurationInt
import scala.jdk.CollectionConverters.*
import scala.util.Using
import scala.util.control.NonFatal
object Main {
def main(args: Array[String]): Unit = {
val socket = s"libtmux-home-${UUID.randomUUID()}"
val config = ServerConfig.builder()
.endpoint(ServerEndpoint.namedSocket(socket))
.configFile(Path.of("/dev/null"))
.defaultTimeout(Duration.ofSeconds(5))
.build()
Using.resource(Server.open(config)) { server =>
try {
val session = server.newSession("demo")
val active = session.activeWindow.get
val editor = active.rename("editor")
val left = editor.activePane.get
val right = left.split(_.toRight().detached())
val logs = session.newWindow(_.named("logs").detached())
right.sendLine("printf 'hello from %s\\n' tmux")
val seen = right.awaitText("hello from tmux", 5.seconds)
assert(seen != TextOutcome.TIMED_OUT)
right.select()
logs.select()
val snapshot = server.snapshot()
val sessions = snapshot.sessions().asScala
for (found <- sessions) {
println(s"session ${found.name()}")
for (win <- snapshot.windowsOf(found.id()).asScala) {
val at = win.context().index().value()
val panes = snapshot.panesOf(win.context()).asScala
val ids = panes.map(_.id().value()).mkString(" ")
println(s" window $at:${win.name()}: $ids")
}
}
val window = right.window
val owner = window.session
val id = right.id.value()
println(s"$id is in window ${window.name} of session ${owner.name}")
} catch {
case NonFatal(error) =>
throw new IllegalStateException(
"tmux quickstart failed", error
)
}
}
}
}
import io.github.libtmux.{ServerConfig, ServerEndpoint, TextOutcome}
import io.github.libtmux.scaladsl.{config => _, *}
import java.nio.file.Path
import java.time.Duration
import java.util.UUID
import scala.concurrent.duration.DurationInt
import scala.jdk.CollectionConverters.*
import scala.util.Using
object Main {
def main(args: Array[String]): Unit = {
val socket = s"libtmux-home-${UUID.randomUUID()}"
val config = ServerConfig.builder()
.endpoint(ServerEndpoint.namedSocket(socket))
.configFile(Path.of("/dev/null"))
.defaultTimeout(Duration.ofSeconds(5))
.build()
Using.resource(Server.open(config)) { server =>
try {
val session = server.newSession("demo")
val active = session.activeWindow.get
val editor = active.rename("editor")
val left = editor.activePane.get
val right = left.split(_.toRight().detached())
val logs = session.newWindow(_.named("logs").detached())
right.sendLine("printf 'hello from %s\\n' tmux")
val seen = right.awaitText("hello from tmux", 5.seconds)
assert(seen != TextOutcome.TIMED_OUT)
right.select()
logs.select()
val snapshot = server.snapshot()
val sessions = snapshot.sessions().asScala
for (found <- sessions) {
println(s"session ${found.name()}")
for (win <- snapshot.windowsOf(found.id()).asScala) {
val at = win.context().index().value()
val panes = snapshot.panesOf(win.context()).asScala
val ids = panes.map(_.id().value()).mkString(" ")
println(s" window $at:${win.name()}: $ids")
}
}
val window = right.window
val owner = window.session
val id = right.id.value()
println(s"$id is in window ${window.name} of session ${owner.name}")
} finally {
server.killServer()
}
}
}
}
import io.github.libtmux.{ServerConfig, ServerEndpoint, TextOutcome}
import io.github.libtmux.scaladsl.{config => _, *}
import java.nio.file.Path
import java.time.Duration
import java.util.UUID
import scala.concurrent.duration.DurationInt
import scala.jdk.CollectionConverters.*
import scala.util.Using
import scala.util.control.NonFatal
object Main {
def main(args: Array[String]): Unit = {
val socket = s"libtmux-home-${UUID.randomUUID()}"
val config = ServerConfig.builder()
.endpoint(ServerEndpoint.namedSocket(socket))
.configFile(Path.of("/dev/null"))
.defaultTimeout(Duration.ofSeconds(5))
.build()
Using.resource(Server.open(config)) { server =>
try {
val session = server.newSession("demo")
val active = session.activeWindow.get
val editor = active.rename("editor")
val left = editor.activePane.get
val right = left.split(_.toRight().detached())
val logs = session.newWindow(_.named("logs").detached())
right.sendLine("printf 'hello from %s\\n' tmux")
val seen = right.awaitText("hello from tmux", 5.seconds)
assert(seen != TextOutcome.TIMED_OUT)
right.select()
logs.select()
val snapshot = server.snapshot()
val sessions = snapshot.sessions().asScala
for (found <- sessions) {
println(s"session ${found.name()}")
for (win <- snapshot.windowsOf(found.id()).asScala) {
val at = win.context().index().value()
val panes = snapshot.panesOf(win.context()).asScala
val ids = panes.map(_.id().value()).mkString(" ")
println(s" window $at:${win.name()}: $ids")
}
}
val window = right.window
val owner = window.session
val id = right.id.value()
println(s"$id is in window ${window.name} of session ${owner.name}")
} catch {
case NonFatal(error) =>
throw new IllegalStateException(
"tmux quickstart failed", error
)
} finally {
server.killServer()
}
}
}
}
No tmux server yet

tmux before the first call: no server is running.

No tmux server yet

tmux after Server.open: no server is running; the call sent no command.

%0 sh
[demo]

tmux after Server.newSession: added session demo.

%0 sh
[demo]

tmux after Session.activeWindow: unchanged, the call sent no command.

%0 sh
[demo]

tmux after Window.rename: renamed window 0:sh to 0:editor.

%0 sh
[demo]

tmux after Window.activePane: unchanged, the call sent no command.

%0 sh
%1 sh
[demo]

tmux after Pane.split: added pane %1 to window 0:editor.

%0 sh
%1 sh
[demo]

tmux after Session.newWindow: added window 1:logs.

%0 sh
%1 sh
[demo]

tmux after Pane.sendLine: sent keys to pane %1.

%0 sh
%1 sh
$ printf 'hello from %s\n' tmux
hello from tmux
$
[demo]

tmux after Pane.awaitText: read pane %1.

%0 sh
%1 sh
$ printf 'hello from %s\n' tmux
hello from tmux
$
[demo]

tmux after Pane.select: selected pane %1 in window 0:editor.

%2 sh
[demo]

tmux after Window.select: selected window 1:logs.

%2 sh
[demo]

tmux after Server.snapshot: unchanged.

%2 sh
[demo]

tmux after ServerSnapshot.sessions: unchanged, the call sent no command.

%2 sh
[demo]

tmux after Pane.window: unchanged, the call sent no command.

%2 sh
[demo]

tmux after Window.session: unchanged, the call sent no command.

No sessions

tmux after Server.killServer: the server has exited.

Before the first call

No tmux server is running yet.

Server.open returned Server

{
"endpoint": "named socket",
"configFile": "/dev/null"
}

The call sent no tmux command.

Server.newSession returned Session

{
"id": "$0",
"name": "demo"
}
2 tmux commands, 1 that changes tmux
  1. new-session -d -s demo -P -F #{session_id} $0
  2. list-sessions -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{session_name}9148a05946b44cf7c476eaa5be4f2326#{session_attached}9148a05946b44cf7c476eaa5be4f2326#{session_windows}08e6c667aad5096b7eaed054a715126a ; display-message -p 9148a05946b44cf7c476eaa5be4f2326:0 ; list-windows -a -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{window_id}9148a05946b44cf7c476eaa5be4f2326#{window_index}9148a059… $09148a05946b44cf7c476eaa5be4f2326demo9148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326108e6c667aad5096b7eaed054a715126a 9148a05946b44cf7c476eaa5be4f2326:0 $09148a05946b44cf7c476eaa5be4f2326@09148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326sh9148a05946b44cf7c476eaa5be4f232619148a05946b44cf7c476eaa5be4f232619148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be…

Before these, the library asked tmux about itself 4 times (its version, its daemon, how a control client reads escapes).

Session.activeWindow returned Window

{
"id": "@0",
"index": 0,
"name": "sh"
}

The call sent no tmux command.

Window.rename returned Window

{
"id": "@0",
"index": 0,
"name": "editor"
}
2 tmux commands, 1 that changes tmux
  1. rename-window -t @0 -- editor no output
  2. list-sessions -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{session_name}9148a05946b44cf7c476eaa5be4f2326#{session_attached}9148a05946b44cf7c476eaa5be4f2326#{session_windows}08e6c667aad5096b7eaed054a715126a ; display-message -p 9148a05946b44cf7c476eaa5be4f2326:0 ; list-windows -a -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{window_id}9148a05946b44cf7c476eaa5be4f2326#{window_index}9148a059… $09148a05946b44cf7c476eaa5be4f2326demo9148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326108e6c667aad5096b7eaed054a715126a 9148a05946b44cf7c476eaa5be4f2326:0 $09148a05946b44cf7c476eaa5be4f2326@09148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326editor9148a05946b44cf7c476eaa5be4f232619148a05946b44cf7c476eaa5be4f232619148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476ea…

Before these, the library asked tmux about itself 1 time (its version, its daemon, how a control client reads escapes).

Window.activePane returned Pane

{
"id": "%0"
}

The call sent no tmux command.

Pane.split returned Pane

{
"id": "%1"
}
2 tmux commands, 1 that changes tmux
  1. split-window -h -d -t %0 -P -F #{pane_id}08e6c667aad5096b7eaed054a715126a %108e6c667aad5096b7eaed054a715126a
  2. list-sessions -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{session_name}9148a05946b44cf7c476eaa5be4f2326#{session_attached}9148a05946b44cf7c476eaa5be4f2326#{session_windows}08e6c667aad5096b7eaed054a715126a ; display-message -p 9148a05946b44cf7c476eaa5be4f2326:0 ; list-windows -a -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{window_id}9148a05946b44cf7c476eaa5be4f2326#{window_index}9148a059… $09148a05946b44cf7c476eaa5be4f2326demo9148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326108e6c667aad5096b7eaed054a715126a 9148a05946b44cf7c476eaa5be4f2326:0 $09148a05946b44cf7c476eaa5be4f2326@09148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326editor9148a05946b44cf7c476eaa5be4f232619148a05946b44cf7c476eaa5be4f232629148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476ea…

Before these, the library asked tmux about itself 1 time (its version, its daemon, how a control client reads escapes).

Session.newWindow returned Window

{
"id": "@1",
"index": 1,
"name": "logs"
}
2 tmux commands, 1 that changes tmux
  1. new-window -d -n logs -t $0 -P -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{window_id}9148a05946b44cf7c476eaa5be4f2326#{window_index}08e6c667aad5096b7eaed054a715126a $09148a05946b44cf7c476eaa5be4f2326@19148a05946b44cf7c476eaa5be4f2326108e6c667aad5096b7eaed054a715126a
  2. list-sessions -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{session_name}9148a05946b44cf7c476eaa5be4f2326#{session_attached}9148a05946b44cf7c476eaa5be4f2326#{session_windows}08e6c667aad5096b7eaed054a715126a ; display-message -p 9148a05946b44cf7c476eaa5be4f2326:0 ; list-windows -a -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{window_id}9148a05946b44cf7c476eaa5be4f2326#{window_index}9148a059… $09148a05946b44cf7c476eaa5be4f2326demo9148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326208e6c667aad5096b7eaed054a715126a 9148a05946b44cf7c476eaa5be4f2326:0 $09148a05946b44cf7c476eaa5be4f2326@09148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326editor9148a05946b44cf7c476eaa5be4f232619148a05946b44cf7c476eaa5be4f232629148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476ea…

Before these, the library asked tmux about itself 1 time (its version, its daemon, how a control client reads escapes).

Pane.sendLine returned Unit

null
2 tmux commands, 1 that changes tmux
  1. display-message -p -t %1 -- #{version}0000-version#{pane_synchronized}9148a05946b44cf7c476eaa5be4f2326-end 3.8a9148a05946b44cf7c476eaa5be4f2326-version09148a05946b44cf7c476eaa5be4f2326-end
  2. send-keys -l -t %1 -- 'printf '\''hello from %s\n'\'' tmux\r' no output

Pane.awaitText returned TextOutcome

"PRESENT_AT_ENTRY"
1 tmux command
  1. capture-pane -p -J -t %1 $ printf 'hello from %s\n' tmux hello from tmux $

Pane.select returned Unit

null
1 tmux command, 1 that changes tmux
  1. select-pane -t %1 no output

Window.select returned Unit

null
1 tmux command, 1 that changes tmux
  1. select-window -t $0:1 no output

Server.snapshot returned ServerSnapshot

{
"sessions": 1,
"windows": 2,
"panes": 3
}
1 tmux command
  1. list-sessions -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{session_name}9148a05946b44cf7c476eaa5be4f2326#{session_attached}9148a05946b44cf7c476eaa5be4f2326#{session_windows}08e6c667aad5096b7eaed054a715126a ; display-message -p 9148a05946b44cf7c476eaa5be4f2326:0 ; list-windows -a -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{window_id}9148a05946b44cf7c476eaa5be4f2326#{window_index}9148a059… $09148a05946b44cf7c476eaa5be4f2326demo9148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326208e6c667aad5096b7eaed054a715126a 9148a05946b44cf7c476eaa5be4f2326:0 $09148a05946b44cf7c476eaa5be4f2326@09148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f2326editor9148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476eaa5be4f232629148a05946b44cf7c476eaa5be4f232609148a05946b44cf7c476ea…

Before these, the library asked tmux about itself 1 time (its version, its daemon, how a control client reads escapes).

ServerSnapshot.sessions returned Buffer[SessionState]

[
{
"id": "$0",
"name": "demo"
}
]

The call sent no tmux command.

Pane.window returned Window

{
"id": "@0",
"index": 0,
"name": "editor"
}

The call sent no tmux command.

Window.session returned Session

{
"id": "$0",
"name": "demo"
}

The call sent no tmux command.

Server.killServer returned Unit

null
1 tmux command, 1 that changes tmux
  1. display-message -p #{pid} ; kill-server 3056886
Run this example

JDK 25 and tmux on Linux/macOS; Scala 3.9.0 Direct facade

Save the program above as src/main/scala/Main.scala 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 {
scala
application
}
repositories { mavenCentral() }
dependencies {
implementation("io.github.libtmux:libtmux-scala_3:0.1.2")
implementation("org.scala-lang:scala3-library_3:3.9.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 e8a39689d8d60968ac978a1dd2a89c6112333896
./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

session demo
window 0:editor: %0 %1
window 1:logs: %2
%1 is in window editor of session demo

Library revision: e8a39689d8d6.

APIs used

Install io.github.libtmux:libtmux-scala_3

libraryDependencies += "io.github.libtmux" %% "libtmux-scala" % "0.1.0"
implementation("io.github.libtmux:libtmux-scala_3:0.1.0")
<dependency>
  <groupId>io.github.libtmux</groupId>
  <artifactId>libtmux-scala_3</artifactId>
  <version>0.1.0</version>
</dependency>

API references

All Scala versions and install instructions

Esc

Type to search.

Reference previewOpen reference