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.
import io.github.libtmux.{ServerConfig, ServerEndpoint, TextOutcome}import io.github.libtmux.scaladsl.{config => _, *}import java.nio.file.Pathimport java.time.Durationimport java.util.UUIDimport scala.concurrent.duration.DurationIntimport 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.Pathimport java.time.Durationimport java.util.UUIDimport scala.concurrent.duration.DurationIntimport scala.jdk.CollectionConverters.*import scala.util.Usingimport 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.Pathimport java.time.Durationimport java.util.UUIDimport scala.concurrent.duration.DurationIntimport 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.Pathimport java.time.Durationimport java.util.UUIDimport scala.concurrent.duration.DurationIntimport scala.jdk.CollectionConverters.*import scala.util.Usingimport 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() } } }}tmux before the first call: no server is running.
tmux after Server.open: no server is running; the call sent no command.
tmux after Server.newSession: added session demo.
tmux after Session.activeWindow: unchanged, the call sent no command.
tmux after Window.rename: renamed window 0:sh to 0:editor.
tmux after Window.activePane: unchanged, the call sent no command.
tmux after Pane.split: added pane %1 to window 0:editor.
tmux after Session.newWindow: added window 1:logs.
tmux after Pane.sendLine: sent keys to pane %1.
$ printf 'hello from %s\n' tmux hello from tmux $
tmux after Pane.awaitText: read pane %1.
$ printf 'hello from %s\n' tmux hello from tmux $
tmux after Pane.select: selected pane %1 in window 0:editor.
$ printf 'hello from %s\n' tmux hello from tmux $
tmux after Window.select: selected window 1:logs.
$ printf 'hello from %s\n' tmux hello from tmux $
tmux after Server.snapshot: unchanged.
$ printf 'hello from %s\n' tmux hello from tmux $
tmux after ServerSnapshot.sessions: unchanged, the call sent no command.
$ printf 'hello from %s\n' tmux hello from tmux $
tmux after Pane.window: unchanged, the call sent no command.
$ printf 'hello from %s\n' tmux hello from tmux $
tmux after Window.session: unchanged, the call sent no command.
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
-
new-session -d -s demo -P -F #{session_id}$0 -
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
-
rename-window -t @0 -- editorno output -
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
-
split-window -h -d -t %0 -P -F #{pane_id}08e6c667aad5096b7eaed054a715126a%108e6c667aad5096b7eaed054a715126a -
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
-
new-window -d -n logs -t $0 -P -F #{session_id}9148a05946b44cf7c476eaa5be4f2326#{window_id}9148a05946b44cf7c476eaa5be4f2326#{window_index}08e6c667aad5096b7eaed054a715126a$09148a05946b44cf7c476eaa5be4f2326@19148a05946b44cf7c476eaa5be4f2326108e6c667aad5096b7eaed054a715126a -
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
null2 tmux commands, 1 that changes tmux
-
display-message -p -t %1 -- #{version}0000-version#{pane_synchronized}9148a05946b44cf7c476eaa5be4f2326-end3.8a9148a05946b44cf7c476eaa5be4f2326-version09148a05946b44cf7c476eaa5be4f2326-end -
send-keys -l -t %1 -- 'printf '\''hello from %s\n'\'' tmux\r'no output
Pane.awaitText returned TextOutcome
"PRESENT_AT_ENTRY"1 tmux command
-
capture-pane -p -J -t %1$ printf 'hello from %s\n' tmux hello from tmux $
Pane.select returned Unit
null1 tmux command, 1 that changes tmux
-
select-pane -t %1no output
Window.select returned Unit
null1 tmux command, 1 that changes tmux
-
select-window -t $0:1no output
Server.snapshot returned ServerSnapshot
{ "sessions": 1, "windows": 2, "panes": 3}1 tmux command
-
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
null1 tmux command, 1 that changes tmux
-
display-message -p #{pid} ; kill-server3056886
libtmux/libtmux-java
at e8a39689d on a private tmux 3.8a server.
A person matched each call to its lines; the values, commands and tmux states are what the run produced.
Commands appear without the library's if-shell guard, and the socket name and paths are set to fixed values.
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-8kotlin.daemon.jvmargs=-Xmx2gorg.gradle.workers.max=2Setup and run
# Save the files above at their displayed relative paths.git clone https://github.com/libtmux/libtmux-java.git libtmux-sourcegit -C libtmux-source checkout --detach e8a39689d8d60968ac978a1dd2a89c6112333896./libtmux-source/gradlew --project-dir . --console=plain --no-daemon --max-workers=2 \ installDist -PexampleMain=MainSHELL=/bin/sh build/install/api-example/bin/api-exampleExpected output
session demo window 0:editor: %0 %1 window 1:logs: %2%1 is in window editor of session demoLibrary 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")Guides
Task guides for Scala.
Examples
Complete programs, sourced from the code each port tests.
Concepts
The domain model every port shares.