# Installation and requirements

Source: https://libtmux.org/en/scala/latest/guides/overview/

> Installation and requirements: io.github.libtmux:libtmux-scala_3 documentation.

**Scala 3 collections and opaque handles over libtmux for Java.**

Use Scala collections and explicit effects to inspect and operate tmux through
libtmux for Java. The direct-style facade's handles are opaque aliases of the
Java ones — lossless by construction, never a hand-copied parallel type — and
return immutable [`Vector`](<https://docs.oracle.com/en/java/javase/21/docs/api/java/util/Vector.html>) and [`Option`](<https://www.scala-lang.org/api/3.x/scala/Option.html>) values. The
[separate Cats module](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/libtmux-scala-cats/README.md) supplies scoped
effects and FS2 observations. Both retain the original Java handles, targeting
rules and command engine.

**This project is alpha.** Releases carry an `-alpha` prerelease tag. The API is
not settled, and any release may change or remove exported identifiers without a
deprecation period. Pin an exact version rather than a range. Not recommended
for production.

## Requirements

Scala 3.9 and JDK 25 or newer; there is no Scala 2.13 build. tmux 3.2a through
3.7c, which the Java library supports and every tmux lane in CI runs these
suites against. See [Compatibility](https://libtmux.org/en/scala/latest/guides/compatibility/).

## Installation

<!-- snippet: scala-build: readme-install -->
```sbt
libraryDependencies += "io.github.libtmux" %% "libtmux-scala" % "<version>"
```

From Gradle or Maven the coordinate is `io.github.libtmux:libtmux-scala_3`.
The version is always `libtmux`'s own: the Scala artifacts are on Maven Central
and release with the Java ones. Core depends on `libtmux` and the Scala 3 library only; Cats, FS2
and Ox arrive through [`libtmux-scala-cats`](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/libtmux-scala-cats/) and
[`libtmux-scala-ox`](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/libtmux-scala-ox/).

## Inspect captured panes

Start with [a first client](https://libtmux.org/en/scala/latest/guides/getting-started/#a-first-client) to construct
[`ServerConfig`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-serverconfig-serverconfig/>) from your tmux executable, owned socket and configuration file.
Here `config` selects an existing server. Opening the client does not create a
session. This operation closes its owned client while leaving the daemon
running.

<!-- snippet: scala-sync: readme-inspect-panes -->
```scala
import io.github.libtmux.scaladsl.{config => _, *}
import scala.util.Using

Using.resource(Server.open(config)) { server =>
  val panes = server.panes()
  val named = panes.filter(_.info.title().nonEmpty)
  val commands = named.map(_.info.currentCommand())
  assert(commands.size <= panes.size)
  assert(panes.forall(p => p.window.info.context().equals(p.info.context())))
}
```

[`server.panes()`](<https://libtmux.org/en/scala/latest/reference/io-github-libtmux-scaladsl-cats-server-panes/>) acquires state. Reading `info`, traversing `window`, or
filtering the captured vector performs no further tmux commands. `refresh()`
returns a new capture. A failed acquisition raises the original Java error;
it does not become an empty vector.

## Documentation

- [Getting started](https://libtmux.org/en/scala/latest/guides/getting-started/): installation, a
  first owned client, and building from source.
- [Queries](https://libtmux.org/en/scala/latest/guides/query/): native collections, the typed field
  DSL and strict cardinality.
- [Ownership](https://libtmux.org/en/scala/latest/guides/ownership/): captured handles, borrowing and
  cleanup.
- [Execution](https://libtmux.org/en/scala/latest/guides/execution/): direct-style calls, bounded
  effects and command outcomes.
- [Streaming](https://libtmux.org/en/scala/latest/guides/streaming/): subscriptions, cancellation and
  visible loss.
- [Compatibility](https://libtmux.org/en/scala/latest/guides/compatibility/): compilers, runtimes and
  what CI runs.
- [Examples](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/examples/): runnable programs, each executed against a real tmux.

The [Java guide](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/docs/guide/scala.md) shows direct Java use without the
facade. Source contracts live beside [direct-style operations][server]
and [Cats resources][cats-server]. For changes to existing APIs, see the
repository's [migration notes](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/MIGRATION.md).

[server]: https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/libtmux-scala/src/main/scala/io/github/libtmux/scaladsl/Server.scala
[cats-server]: https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/libtmux-scala-cats/src/main/scala/io/github/libtmux/scaladsl/cats/Server.scala