# libtmux for Raku

> The Raku library (LibTmux). These pages include its guides, tested examples and API documentation.

- [Raku API reference](https://libtmux.org/en/raku/latest/reference/): every public symbol, generated from the source. Hosted on libtmux.org.

---

# tmux client library for Raku

Source: https://libtmux.org/en/raku/latest/core/

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

LibTmux gives Raku programs typed snapshots of a tmux server, ordinary
predicates over them, and explicit commands that change tmux. Reading a
snapshot makes no further tmux calls; an operation through a reference does.

The LibTmux distribution from the zef:libtmux authority is published on Raku Land. Its API
is experimental and may change between `0.x` releases. CI qualifies Rakudo
2026.09 on Linux with tmux 3.3a and 3.8; other platforms and compiler versions
are unverified. The library has no workspace manager or MCP server.Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents.

## At a glance

| Type | Wraps |
| ---- | ----- |
| [`LibTmux::Server`](https://libtmux.org/en/raku/latest/reference/libtmux-server/) | A tmux server |
| [`LibTmux::Model::Session`](https://libtmux.org/en/raku/latest/reference/libtmux-model-session/) | A session, ID `$n` |
| [`LibTmux::Model::Window`](https://libtmux.org/en/raku/latest/reference/libtmux-model-window/) | A physical window linked into sessions, ID `@n` |
| [`LibTmux::Model::Pane`](https://libtmux.org/en/raku/latest/reference/libtmux-model-pane/) | A pane in a window, ID `%n` |
| [`LibTmux::Model::WindowLink`](https://libtmux.org/en/raku/latest/reference/libtmux-model-windowlink/) | A session-window association, with its index and active state |

## Typed API

- Typed objects instead of parsed format strings: [`LibTmux::Model::Pane`](https://libtmux.org/en/raku/latest/reference/libtmux-model-pane/)
- Addressing by tmux ID: [`LibTmux::Model::Pane.id`](https://libtmux.org/en/raku/latest/reference/libtmux-model-pane-id/)
- Filtering and queries over tmux objects: [`LibTmux::Model::PaneSelection.where`](https://libtmux.org/en/raku/latest/reference/libtmux-model-paneselection-where/)
- Typed errors instead of exit codes and stderr: [`X::LibTmux::InvalidFilter`](https://libtmux.org/en/raku/latest/reference/x-libtmux-invalidfilter/)

## What you get over the tmux CLI

- Connect to or start a tmux server: [`LibTmux::Server.start`](https://libtmux.org/en/raku/latest/reference/libtmux-server-start/)
- Traversal from a server down to its panes: [`LibTmux::Server.snapshot`](https://libtmux.org/en/raku/latest/reference/libtmux-server-snapshot/)
- Send keys to a pane: [`LibTmux::Model::PaneRef.send-keys`](https://libtmux.org/en/raku/latest/reference/libtmux-model-paneref-send-keys/)
- Watch for changes through tmux control mode: [`LibTmux::Server.open-control-async`](https://libtmux.org/en/raku/latest/reference/libtmux-server-open-control-async/)
- Capture pane contents: [`LibTmux::Model::PaneRef.capture`](https://libtmux.org/en/raku/latest/reference/libtmux-model-paneref-capture/)
- Arguments passed as a list, with no shell quoting: [`LibTmux::Server.command`](https://libtmux.org/en/raku/latest/reference/libtmux-server-command/)
- A typed error when the running tmux lacks a feature: [`X::LibTmux::Unsupported`](https://libtmux.org/en/raku/latest/reference/x-libtmux-unsupported/)
- Async operations: [`LibTmux::Server.snapshot-async`](https://libtmux.org/en/raku/latest/reference/libtmux-server-snapshot-async/)

- [Getting started](https://libtmux.org/en/raku/latest/guides/getting-started/): Install LibTmux, create and split panes, and find them through typed snapshots.
- [Examples](https://libtmux.org/en/raku/latest/examples/programs/): Run six complete programs against private tmux servers and compare their output.
- [tmux compatibility](https://libtmux.org/en/raku/latest/topics/compatibility/): Check the supported tmux releases and how the library handles newer ones.
- [API reference](https://libtmux.org/en/raku/latest/reference/): Native signatures, RakuDoc and links for every public module, class and method.

---

# Examples

Source: https://libtmux.org/en/raku/latest/examples/

> Run complete Raku programs with their documented results and cleanup.

Run complete Raku programs with their documented results and cleanup.

- [Runnable programs](https://libtmux.org/en/raku/latest/examples/programs/): Run the checked Raku programs and compare each with its expected result.

---

# Runnable programs

Source: https://libtmux.org/en/raku/latest/examples/programs/

> Run the checked Raku programs and compare each with its expected result.

Complete programs that start a private tmux server, do one job and close it.
Run them from the repository root after the
[toolchain setup](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/.github/CONTRIBUTING.md#toolchain), with tmux on `PATH`:

```console
$ zef install .
```

| Task | Program | Raku facilities |
| --- | --- | --- |
| Create and find panes | [Quickstart](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/quickstart.raku) | Objects, `LEAVE`, a native predicate |
| Resize and remove panes | [Resize panes](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/resize-panes.raku) | `resize`, `kill`, fresh snapshots |
| Select wide panes | [Pane queries](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/query-panes.raku) | Typed selections, query hashes, `grep`, `map`, `sort` |
| Choose where a query runs | [Query plan](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/explain-query.raku) | `explain-panes`, `:pushdown` |
| Add a status pane | [Floating panes](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/floating-panes.raku) | Capability checks and a tiled fallback |
| Watch pane output | [Watch output](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/watch-output.raku) | [`Promise`](<https://docs.raku.org/type/Promise>), [`Supply`](<https://docs.raku.org/type/Supply>), `react`, `whenever` |
| Combine the workflow | [Session workflow](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/session-workflow.raku) | Events, captured graphs and query plans |
| Recover after a command fails | [Batch recovery](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/batch-recovery.raku) | Typed outcomes and explicit recovery |

## Create and find panes

[`quickstart.raku`](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/quickstart.raku) splits one pane, titles both and finds
`editor` in a fresh snapshot. The earlier snapshot still has one pane.

```console
$ raku -I. examples/quickstart.raku
```

It prints `editor: 2 panes`.

## Resize and remove panes

[`resize-panes.raku`](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/resize-panes.raku) splits a pane, resizes the window and
the first pane, then kills the second pane. A fresh snapshot reads each result.

```console
$ raku -I. examples/resize-panes.raku
```

It prints `window: 100x20`, `editor: 30 columns` and `panes: 1`.

## Select wide panes

[`query-panes.raku`](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/query-panes.raku) creates `editor`, `tests` and `logs`.
`.where` selects wide panes, `.filter` finds `editor`, `.single` checks the
count, and `.grep`, `.map` and `.sort` list the rest.

```console
$ raku -I. examples/query-panes.raku
```

It prints `Wide pane: editor` and `Other panes: logs, tests`.

- Bind a typed selection with `:=`; `=` copies it into a plain array.
- Repeated traversal reads the captured members and does not refresh tmux.

## Choose where a query runs

[`explain-query.raku`](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/explain-query.raku) explains two pane queries, runs one,
and shows `:pushdown<require>` refusing the query that keeps a title test local.

```console
$ raku -I. examples/explain-query.raku
```

It prints whether each query is fully pushed to tmux, the filter tmux gets,
the match, and the refusal.

## Add a status pane

[`floating-panes.raku`](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/floating-panes.raku) creates an empty [`status`](<https://libtmux.org/en/raku/latest/reference/libtmux-capabilities-status/>) pane:
floating when the daemon reports `pane-floating`, tiled otherwise.

```console
$ raku -I. examples/floating-panes.raku
```

It prints `Status pane: floating` or `Status pane: tiled`, then [`status`](<https://libtmux.org/en/raku/latest/reference/libtmux-capabilities-status/>).

## Watch pane output

[`watch-output.raku`](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/watch-output.raku) subscribes to pane-output events, sends
text to `cat` and collects the echoed bytes with `react` and `whenever`. Then it
checks the captured screen.

```console
$ raku -I. examples/watch-output.raku
```

It prints `hello from Raku` and `Screen capture confirmed`.

- A deadline bounds the wait.
- Several subscribers can share one connection.
- Sending text and pressing Enter are separate calls.

## Run the complete session workflow

[`session-workflow.raku`](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/session-workflow.raku) creates panes, sends input,
watches control-mode output and captures the screen. It filters a snapshot,
then compares an exact source query with the captured pane.

```console
$ raku -I. examples/session-workflow.raku
```

The output includes `Session: 2 panes`, `editor: hello from Raku` and
`Owned clients, daemon and socket cleaned up`.

## Recover after a command fails

[`batch-recovery.raku`](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/batch-recovery.raku) sets an option, sends an invalid
command and checks that the next command was skipped. It then removes the
first effect.

```console
$ raku -I. examples/batch-recovery.raku
```

It prints the [`Complete`](<https://libtmux.org/en/raku/latest/reference/libtmux-types-outcome-complete/>), [`Failed`](<https://libtmux.org/en/raku/latest/reference/libtmux-types-outcome-failed/>) and [`Skipped`](<https://libtmux.org/en/raku/latest/reference/libtmux-types-outcome-skipped/>) outcomes, then
`Recovery: removed the first effect explicitly` and
`Owned daemon and socket cleaned up`.

A failed batch does not undo commands that already succeeded.

## Select a tmux executable

Every program except the quickstart takes `--tmux=PATH`. The quickstart runs
`tmux` from `PATH`.

The [example check](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/tools/check-examples.raku) runs every program against
`LIBTMUX_TEST_TMUX`, compares its output and rejects leftover sockets. See
[Contributing](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/.github/CONTRIBUTING.md#checks).

---

# Getting started

Source: https://libtmux.org/en/raku/latest/guides/getting-started/

> Start a private tmux server, split panes, send input, find panes with plain Raku predicates, and react to terminal output as it arrives.

[![LibTmux](https://raku.land/zef:libtmux/LibTmux/badges/version)](https://raku.land/zef:libtmux/LibTmux)
[![license](https://libtmux.org/en/badges/8378cbe3d7aa.svg)](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/LICENSE)

Start a private tmux server, split panes, send input, find panes with plain
Raku predicates, and react to terminal output as it arrives.

## Install

Needs Raku 6.d or newer, tmux 3.3a or newer and Linux. Install from
[Raku Land][raku-land] with its Fez authority:

```console
$ zef install 'LibTmux:auth<zef:libtmux>'
```

To install a checkout instead:

```console
$ zef install .
```

The [toolchain guide][repo-github-contributing-md-toolchain] covers Raku and
zef setup. The [changelog][repo-changelog-md] lists each release.

## Create sessions and panes

### [`Server.start`][api-server-start] and [`PaneRef.split`][api-pane-split]: create and arrange panes

Start a private server, split its first pane and title both panes. Each runs
`cat`, and `LEAVE` closes the server on any exit.

[`Server.new-session`][api-server-new-session] and
[`SessionRef.new-window`][api-session-new-window] add sessions and windows.

<!-- runs: examples/quickstart.raku -->

```raku
use LibTmux;

my $server = Server.start(:name<work>, :shell-command('exec cat'));
LEAVE $server.close if $server.defined;

my $before = $server.snapshot;
my $left = $before.panes.single.ref;
my $right = $left.split(:horizontal, :shell-command('exec cat'));
$left.set-title('editor');
$right.set-title('logs');

my $after = $server.snapshot;
my $editor = $after.panes.filter(*.title eq 'editor').single;
say "{$editor.title}: {$after.panes.elems} panes";
```

It prints `editor: 2 panes`. The earlier snapshot still has one pane: `.ref`
commands change tmux, while a snapshot keeps what it captured.

Save it as `quickstart.raku` and run it:

```console
$ raku quickstart.raku
```

From a checkout:

```console
$ raku -I. examples/quickstart.raku
```

More: the [native API guide][repo-lib-libtmux-rakumod].

## Resize and remove panes

### [`PaneRef.resize`][api-pane-resize] and [`PaneRef.kill`][api-pane-kill]: size and remove panes

Split a pane, size the window and the first pane, then kill the second pane.
[`WindowRef.resize`][api-window-resize] sizes a window. A window, a session
and the daemon go with [`WindowRef.kill`][api-window-kill],
[`SessionRef.kill`][api-session-kill] and
[`Server.kill-server`][api-server-kill-server].

<!-- runs: examples/resize-panes.raku -->

```raku
use v6.d;
use LibTmux;

sub MAIN(Str:D :$tmux = 'tmux') {
    my $server = Server.start(:binary($tmux), :name<work>,
        :width(120), :height(30), :shell-command('exec cat'));
    LEAVE $server.close if $server.defined;

    my $before = $server.snapshot;
    my $window = $before.windows.single.ref;
    my $editor = $before.panes.single.ref;
    my $logs = $editor.split(:horizontal, :shell-command('exec cat'));

    $window.resize(:width(100), :height(20));
    $editor.resize(:width(30));
    my $sized = $server.snapshot;
    say "window: {$sized.windows.single.width}x{$sized.windows.single.height}";
    say "editor: {$sized.panes.where(%(id => $editor.id)).single.width} columns";

    $logs.kill;
    say "panes: {$server.snapshot.panes.elems}";
}
```

It prints `window: 100x20`, `editor: 30 columns` and `panes: 1`.

- `resize` takes `:width` and `:height`, or `:direction` with `:amount`. It
  refuses a mix of the two.

More: the [native API guide][repo-lib-libtmux-rakumod].

## Query captured panes

### [`PaneSelection.where`][api-pane-selection-where]: select panes from a snapshot

Select wide panes with query data, then find `editor` with a Raku predicate
through [`filter`][api-pane-selection-filter]. Native `.grep`, `.map` and
`.sort` list the rest.

[`Server.query-panes`][api-server-query-panes] asks tmux for a fresh selection
instead of reading a snapshot.

<!-- runs: examples/query-panes.raku -->

```raku
use v6.d;
use LibTmux;

sub MAIN(Str:D :$tmux = 'tmux') {
    my $server = Server.start(:binary($tmux), :name<work>,
        :width(160), :height(40), :shell-command('exec cat'));
    LEAVE $server.close if $server.defined;

    my $editor = $server.snapshot.panes.single.ref;
    my $tests = $editor.split(:horizontal, :shell-command('exec cat'));
    my $logs = $tests.split(:shell-command('exec cat'));
    $editor.set-title('editor');
    $tests.set-title('tests');
    $logs.set-title('logs');

    my $snapshot = $server.snapshot;
    my @wide := $snapshot.panes.where(%(width => %(gte => 60)));
    my $selected = @wide.filter(*.title eq 'editor').single;
    say "Wide pane: {$selected.title}";

    my @others = $snapshot.panes.grep(*.id ne $selected.id).map(*.title).sort;
    say 'Other panes: ' ~ @others.join(', ');
}
```

It prints `Wide pane: editor` and `Other panes: logs, tests`.

- Bind with `:=` to keep a typed selection; `=` makes a plain array.
- `where` checks fields and operators; `filter` returns the same selection type.
- `.single` wants exactly one match, `.single-or-nil` allows none. `.one` stays
  Raku's junction.

More: the [native API guide][repo-lib-libtmux-rakumod] covers relations and
portable filters.

## Choose where a query runs

### [`Server.explain-panes`][api-server-explain-panes]: what tmux filters and what Raku filters

[`Server.query-panes`][api-server-query-panes] takes `:pushdown`:

- `auto` (the default) has tmux apply the restrictions it can match exactly,
  then rechecks every result in Raku.
- `never` lists first and filters in Raku.
- [`require`](<https://libtmux.org/en/raku/latest/reference/libtmux-capabilities-require/>) throws when any part would stay local.

<!-- runs: examples/explain-query.raku -->

```raku
use v6.d;
use LibTmux;

sub MAIN(Str:D :$tmux = 'tmux') {
    my $server = Server.start(:binary($tmux), :name<work>, :shell-command('exec cat'));
    LEAVE $server.close if $server.defined;
    $server.snapshot.panes.single.ref.set-title('editor');

    my %wide = width => %(gte => 60);
    my %titled = AND => [%wide, %(title => %(contains => 'edit'))];

    say 'width: fully pushed = ' ~ $server.explain-panes(:where(%wide)).fully-pushed;
    my $plan = $server.explain-panes(:where(%titled));
    say 'width and title: fully pushed = ' ~ $plan.fully-pushed;
    say 'tmux filter: ' ~ $plan.source-filter;

    say 'Matches: ' ~ $server.query-panes(:where(%titled)).map(*.title).join(', ');
    try {
        $server.query-panes(:where(%titled), :pushdown<require>);
        CATCH { when X::LibTmux::Unsupported { say 'require: refused, title stays local' } }
    }
}
```

It prints:

```text
width: fully pushed = True
width and title: fully pushed = False
tmux filter: #{e|>=:#{pane_width},60}
Matches: editor
require: refused, title stays local
```

More: the [native API guide][repo-lib-libtmux-rakumod].

## Adapt to the running daemon

### [`Capabilities.supports`][api-capabilities-supports]: choose a supported operation

Create an empty [`status`](<https://libtmux.org/en/raku/latest/reference/libtmux-capabilities-status/>) pane: floating when the daemon supports it, tiled
otherwise. [`Snapshot.capabilities`][api-snapshot-capabilities] holds what the
daemon, not the client binary, can do.

[`Options.describe`][api-options-describe] gives an option's type, scopes and
first release; [`Server.options`][api-server-options] and
[`Server.hooks`][api-server-hooks] read and set options and hooks.

<!-- runs: examples/floating-panes.raku -->

```raku
use v6.d;
use LibTmux;

sub MAIN(Str:D :$tmux = 'tmux') {
    my $server = Server.start(:binary($tmux), :name<work>,
        :width(120), :height(36), :shell-command('exec cat'));
    LEAVE $server.close if $server.defined;

    my $snapshot = $server.snapshot;
    my $main = $snapshot.panes.single.ref;
    my $floating = $snapshot.capabilities.supports('pane-floating');
    my $auxiliary = $floating
        ?? $main.new-floating(:width(40), :height(12), :x(2), :y(2), :empty)
        !! $main.split(:horizontal, :empty);
    $auxiliary.set-title('status');

    my $after = $server.snapshot;
    die 'The auxiliary pane was not captured' unless $after.panes.elems == 2;
    say 'Status pane: ' ~ ($floating ?? 'floating' !! 'tiled');
    say $after.panes.where(%(id => $auxiliary.id)).single.title;
}
```

It prints `Status pane: floating` or `Status pane: tiled`, then [`status`](<https://libtmux.org/en/raku/latest/reference/libtmux-capabilities-status/>).

More: the [compatibility policy][repo-docs-adr-0001-tmux-compatibility-md] and
the [field, option, hook and capability
reference][repo-docs-reference-catalogue-rakudoc].

## Watch pane output

### [`ControlConnection.events`][api-connection-events]: receive output through a `Supply`

[`Server.open-control-async`][api-server-open-control-async] (or
[`Server.open-control`][api-server-open-control]) opens a persistent control
connection. Its events are one shared [`Supply`](<https://docs.raku.org/type/Supply>), so `react` and `whenever` read
them. This program subscribes, sends text with
[`PaneRef.send-text`][api-pane-send-text] and checks the screen with
[`PaneRef.capture`][api-pane-capture].

<!-- runs: examples/watch-output.raku -->

```raku
use v6.d;
use LibTmux;
use LibTmux::Control;

sub MAIN(Str:D :$tmux = 'tmux') {
    my $server = Server.start(:binary($tmux), :name<output>, :shell-command('exec cat'));
    LEAVE $server.close if $server.defined;
    my $snapshot = await $server.snapshot-async;
    my $pane = $snapshot.panes.single.ref;
    my $connection = await $server.open-control-async(:session-id($snapshot.sessions.single.id));
    LEAVE $connection.close if $connection.defined;

    my $message = 'hello from Raku';
    my $received = '';
    react {
        whenever $connection.events.grep(PaneOutput) -> $event {
            if $event.pane-id eq $pane.id {
                $received ~= $event.data.decode('utf8-c8');
                die 'Pane output exceeded its bound' if $received.chars > 65536;
                done if $received.contains($message);
            }
        }
        whenever start { $pane.send-text($message); $pane.send-keys('Enter') } { }
        whenever Promise.in(2) { die 'Pane output timed out' }
    }

    die 'The captured screen did not contain the message'
        unless $pane.capture.decode('utf8').contains($message);
    say $message;
    say 'Screen capture confirmed';
}
```

It prints `hello from Raku` and `Screen capture confirmed`.

- [`send-text`](<https://libtmux.org/en/raku/latest/reference/libtmux-model-paneref-send-text/>) sends literal text; [`send-keys('Enter')`][api-pane-send-keys]
  submits it.
- Output arrives as bytes, so split or invalid UTF-8 survives.

More: the longer [session workflow program][repo-examples-session-workflow-raku]
also queries and explains.

## Run commands in a batch

### [`Server.run-batch`][api-server-run-batch]: run commands in order, keep every outcome

Build a [`Batch`][api-batch] of [`Operation`][api-operation] values. Each one
reports [`Complete`](<https://libtmux.org/en/raku/latest/reference/libtmux-types-outcome-complete/>), [`Failed`](<https://libtmux.org/en/raku/latest/reference/libtmux-types-outcome-failed/>) or [`Skipped`](<https://libtmux.org/en/raku/latest/reference/libtmux-types-outcome-skipped/>). Here the second fails, the third is
skipped, and the program removes the first effect itself.

<!-- runs: examples/batch-recovery.raku -->

```raku
use v6.d;
use LibTmux;

sub MAIN(Str:D :$tmux = 'tmux') {
    my $server = Server.start(:binary($tmux), :name<recovery>, :shell-command('exec cat'));
    LEAVE $server.close if $server.defined;
    my $before = $server.snapshot;
    my $batch = Batch.new(:operations([
        Operation.new(:name<set-option>, :acknowledgement-only,
            :command(Invocation.new(:argv(['set-option', '-s', '@before-failure', 'set'])))),
        Operation.new(:name<invalid-command>, :acknowledgement-only,
            :command(Invocation.new(:argv(['libtmux-example-unknown-command='])))),
        Operation.new(:name<skipped-option>, :acknowledgement-only,
            :command(Invocation.new(:argv(['set-option', '-s', '@after-failure', 'set'])))),
    ]));
    my $report = $server.run-batch($batch);
    die 'Batch attribution was wrong'
        unless $report.operations.map(*.outcome).List eqv (Complete, Failed, Skipped);
    my $options = $server.options;
    die 'The successful first effect disappeared' unless $options.get('@before-failure') eq 'set';
    die 'A skipped operation ran' if $options.entries(:name<@after-failure>).elems;
    say .name ~ ': ' ~ .outcome ~ ' (scope: ' ~ .completion-scope ~ ')' for $report.operations;

    $options.unset('@before-failure');
    die 'Explicit recovery failed' if $options.entries(:name<@before-failure>).elems;
    say 'Recovery: removed the first effect explicitly';
    my $pid = $before.incarnation.pid;
    my $directory = $server.endpoint.socket-path.IO.parent;
    $server.close;
    die 'Owned daemon or socket directory survived cleanup' if "/proc/$pid".IO.e || $directory.e;
    say 'Owned daemon and socket cleaned up';
}
```

It prints:

```text
set-option: Complete (scope: command)
invalid-command: Failed (scope: command)
skipped-option: Skipped (scope: command)
Recovery: removed the first effect explicitly
Owned daemon and socket cleaned up
```

A failed batch does not roll back earlier commands.

More: the [examples guide][repo-examples-readme-md].

## Close what you open

### [`Server.close`][api-server-close]: stop a server you started

- [`Server.start`][api-server-start] owns a private server; `close` stops it.
- [`Server.new`][api-server-new] borrows a server; `close` leaves it running.
- Control connections and attachments have their own lifetimes. Close them too.
- A reference refuses a replacement server that reuses its ids.

## What it leaves out

- **Live objects.** A snapshot is what tmux said when you asked. It does not
  change when tmux does.
- **Rollback.** A failed batch does not undo commands that already ran.
- **Callbacks in tmux.** Raku predicates always run locally.

## Support and status

- **Experimental.** The API may change between `0.x` releases. The
  [changelog][repo-changelog-md] marks each break.
- **tmux 3.3a or newer.** A release the library does not list yet is refused.
- **Linux.** Other platforms are unverified.

## Documentation

Headings above link to the native declarations and their RakuDoc comments.

- [Native API guide][repo-lib-libtmux-rakumod]: the object graph, queries,
  capabilities, async execution, control events and recovery.
- [Examples][repo-examples-readme-md]: complete Raku programs with checked results.
- [Contributing][repo-github-contributing-md]: compiler setup and validation.
- [API documentation authoring][repo-docs-documentation-rakudoc] and
  [writing conventions][repo-github-writing-md].
- [MIT license][repo-license] and [artwork provenance][repo-docs-assets-readme-md].

[api-batch]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Batch.rakumod#L206
[api-capabilities-supports]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Capabilities.rakumod#L126
[api-connection-events]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Control/Connection.rakumod#L147
[api-operation]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Batch.rakumod#L53
[api-options-describe]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Configuration.rakumod#L166
[api-pane-capture]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L257
[api-pane-kill]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L495
[api-pane-resize]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L316
[api-pane-selection-filter]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Selection.rakumod#L68
[api-pane-selection-where]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Selection.rakumod#L78
[api-pane-send-keys]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L248
[api-pane-send-text]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L244
[api-pane-split]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L279
[api-server-close]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L685
[api-server-explain-panes]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L432
[api-server-hooks]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L565
[api-server-kill-server]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L538
[api-server-new]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L290
[api-server-new-session]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L452
[api-server-open-control]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L575
[api-server-open-control-async]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L579
[api-server-options]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L551
[api-server-query-panes]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L430
[api-server-run-batch]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L608
[api-server-start]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Server.rakumod#L622
[api-session-kill]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L169
[api-session-new-window]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L135
[api-snapshot-capabilities]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L662
[api-window-kill]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L239
[api-window-resize]: https://github.com/libtmux/libtmux-raku/blob/f543ca5de32e04445f4d6e29c66e5dba94ac9a63/lib/LibTmux/Model.rakumod#L179
[raku-land]: https://raku.land/zef:libtmux/LibTmux
[repo-changelog-md]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/CHANGELOG.md
[repo-docs-adr-0001-tmux-compatibility-md]: https://libtmux.org/en/raku/latest/topics/compatibility/
[repo-docs-assets-readme-md]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/docs/assets/README.md
[repo-docs-documentation-rakudoc]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/docs/documentation.rakudoc
[repo-docs-reference-catalogue-rakudoc]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/docs/reference/catalogue.rakudoc
[repo-examples-readme-md]: https://libtmux.org/en/raku/latest/examples/programs/
[repo-examples-session-workflow-raku]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/examples/session-workflow.raku
[repo-github-contributing-md]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/.github/CONTRIBUTING.md
[repo-github-contributing-md-toolchain]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/.github/CONTRIBUTING.md#toolchain
[repo-github-writing-md]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/.github/WRITING.md
[repo-lib-libtmux-rakumod]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/lib/LibTmux.rakumod
[repo-license]: https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/LICENSE

---

# Guides

Source: https://libtmux.org/en/raku/latest/guides/

> Install LibTmux and create, find and arrange tmux sessions and panes.

Install LibTmux and create, find and arrange tmux sessions and panes.

- [Getting started](https://libtmux.org/en/raku/latest/guides/getting-started/): Start a private tmux server, split panes, send input, find panes with plain Raku predicates, and react to terminal output as it arrives.

---

# Linking and consuming our docs

Source: https://libtmux.org/en/raku/latest/meta/linking/

> Find documentation exports for search engines, bots, LLMs and other documentation sites.

We welcome bots, search engines, SEO tools, LLMs and other clients to use our
documentation. Read a page in your browser, fetch its Markdown, discover
pages through a manifest, or link to documented objects from another site.

## Choose an export

The page footer links to the exports for its documentation tree. Use those
links to select a language, version or preview.

| File or format | Use it for |
| --- | --- |
| [llms.txt](https://libtmux.org/en/llms.txt) | Discover guides, API references and agent prompts through a Markdown index. |
| [llms-full.txt](https://libtmux.org/en/llms-full.txt) | Fetch the guides together as Markdown. API references are linked separately. |
| [docs.json](https://libtmux.org/en/docs.json) | Discover page titles, URLs, descriptions, headings and Markdown URLs in a structured manifest. |
| Markdown | Read one page as text using its footer's **Markdown** link. |
| Raw source | Inspect the source file using its footer's **Raw source** link, where available. |
| [objects-full.inv](https://libtmux.org/en/objects-full.inv) | Resolve Sphinx references across shared docs, each port's default version, or its latest until the default has published a catalog, and tmux reference versions. |
| objects.inv | Resolve Sphinx references within one port and version, or one tmux documentation tree. |
| [targets.json](https://libtmux.org/en/targets.json) | Browse inventory keys, display names and destination URLs as JSON. A scoped catalog sits beside each root inventory. The root one lists fallbacks and ports left out. |

The root exports above cover the assembled site. Port exports describe the
selected port and version. For a single API declaration, start with
`docs.json` and follow its reference and symbol-index links.

## Link from Sphinx

The [Intersphinx guide](https://libtmux.org/en/meta/intersphinx/) explains how to configure
inventories, choose native roles or portable labels, and preserve references
when a page moves or changes its title.

Browse [Intersphinx examples](https://libtmux.org/en/meta/intersphinx/examples/) for copyable RST
and MyST references to library APIs, tmux C declarations, hooks, format
variables, CLI commands and schema fields, paired with their destinations.

## Discover and index pages

Use the [sitemap](https://libtmux.org/en/sitemap-index.xml) to discover indexable pages. Follow
[robots.txt](https://libtmux.org/robots.txt) and each page's robots metadata:
pull-request previews, component demos and search-index shards are excluded
from crawling, and alternate versions can carry `noindex`.

Choose a versioned documentation tree when a reference needs a particular
release. The full inventory follows each port's advertised default; a
port's `objects.inv` describes the selected version.

---

# Link to libtmux from Sphinx

Source: https://libtmux.org/en/raku/latest/meta/intersphinx/

> Use Intersphinx inventories to reference libtmux APIs and documentation.

Sphinx can resolve references to libtmux APIs, guides, headings, MCP objects,
schema fields, and other documented targets. The footer links to the full
inventory and the inventory for the page's port or tmux version.

Browse [Intersphinx examples](https://libtmux.org/en/meta/intersphinx/examples/) for copyable RST
and MyST references paired with their destinations.

For Markdown exports, manifests and crawler discovery, see
[Linking and consuming our docs](https://libtmux.org/en/meta/linking/).

## Configure Intersphinx

Enable the built-in extension in your project's `conf.py`:

Python's [`None`](<https://docs.python.org/3/builtins/constants.html#None>) discovers `objects.inv` at the configured base URL. The port mapping
above selects the Python `latest` tree. Copy the base URL of another port
or version to select its inventory.

The full inventory includes shared documentation, the configured default
version of each assembled port, and distinct tmux reference versions.
It is generated after site assembly. Each port inventory includes the
rendered targets in that exact version.

The tmux inventory includes the shared tmux guides and the latest CLI manual,
options, hooks, formats, and C source reference. A version mapping such as
`tmux-3-7c` includes only that release's manual, catalog, and C declarations.
Manual and C reference pages link to the same version inventory in the footer.
Use mapping names without dots when writing MyST reference roles.

## Choose a reference

Every exported target has a portable label that works with `std:ref`, without
installing a language or MCP domain. Open `targets.json` beside the inventory
and copy its `key`. Its `href` and `display` identify the destination.

For example, the Python [`libtmux.Pane`](<https://libtmux.org/en/py/latest/reference/libtmux-pane/>) declaration has this reStructuredText
reference:

```rst
:external+libtmux:ref:`Pane <py:core:api:libtmux.%50ane>`
```

With MyST enabled in your project, the same label works in Markdown:

```markdown
{external+libtmux:ref}`Pane <py:core:api:libtmux.%50ane>`
```

Native Python, C++, JavaScript, and C objects also have aliases for their
built-in roles. A scoped Python inventory supports:

```rst
:external+libtmux-python:py:class:`libtmux.Pane`
```

The tmux mapping provides native C roles and portable manual references:

```rst
:external+tmux:c:struct:`cmd`
:external+tmux:ref:`capture-pane <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fcapture-pane>`
```

Command options also work with Sphinx's program context:

```rst
.. program:: tmuxp load

:external+libtmux-python:option:`--append`
```

The full inventory qualifies native names by port, such as
[`py:libtmux.Pane`](<https://libtmux.org/en/raku/latest/reference/libtmux-model-pane/>). A fully qualified alias includes the product too:
[`py:core:libtmux.Pane`](<https://libtmux.org/en/raku/latest/reference/libtmux-model-pane/>). Short aliases are offered only when they identify
one destination. Configuration values, command options, environment
variables, and glossary terms use standard-domain types where their
renderers identify those semantics.

## Stable labels

A portable key contains `scope:product:category:identity`. Its encoding
preserves uppercase letters, punctuation, and Unicode, because `std:ref`
lowercases targets. `%50ane` and `pane` therefore remain distinct.
Copy the key from the catalog without decoding its percent escapes.

Keys are independent of display titles and destination URLs. API public IDs,
protocol wire identities, JSON Pointers, named parameters, and native method
identities supply their names. Authored documents can retain `inventoryId`
and explicit HTML fragment IDs when their titles or routes change.
Contributors preserve renamed keys in the inventory alias catalog and use
the existing page redirect mechanism for retired routes.

### Preserve published links

If `meta/intersphinx.md` moves to `meta/linking.md`, retain its logical ID
and list the retired route in the new page's frontmatter:

```yaml
inventoryId: intersphinx
aliases:
  - meta/intersphinx
```

The document key remains `site:core:doc:intersphinx`, and the old route
redirects to the new page. Retain existing heading fragment IDs when their
text changes.

When an identity or fragment changes intentionally, map the former keys to
current targets in `site/src/data/inventory-aliases.json`. For example,
choosing `inventoryId: linking` and changing `stable-labels` to
`stable-references` needs these entries:

```json
[
  {
    "scope": "site",
    "from": "site:core:doc:intersphinx",
    "to": "site:core:doc:linking"
  },
  {
    "scope": "site",
    "from": "site:core:heading:intersphinx%23stable-labels",
    "to": "site:core:heading:linking%23stable-references",
    "fragment": "stable-labels"
  }
]
```

The document entry preserves `std:ref` and `std:doc` references. The heading
entry preserves `std:ref`; `fragment` also installs the retired HTML anchor
at the new destination. Keep the route alias too: inventory aliases do not
redirect retired URLs.

Copy `to` from the current target catalog. Retain earlier `from` entries
and update their destinations when renaming again. Former native role names,
such as a Python class name, need preservation in the native metadata.

Existing `objects.inv` and `reference/objects.inv` endpoints remain compatibility
exports. New integrations should use the full inventory, a port's root
inventory, or a tmux root inventory to obtain the complete target catalog
and case-safe labels.

See the [Sphinx Intersphinx documentation](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html)
for named inventories and cross-reference syntax.

---

# Intersphinx examples

Source: https://libtmux.org/en/raku/latest/meta/intersphinx/examples/

> Compare Sphinx and MyST references to APIs, tmux C declarations, hooks, format variables, CLI commands and schema fields.

import { referenceHref } from '../../../../lib/api-models'

Copy a reference and compare its destination below. These examples cover
native language roles, portable labels, full and scoped inventories, and
links into tmux C declarations, hooks, format variables and CLI commands.

## Configure the inventories

Add these mappings to your Sphinx project's `conf.py`:

Python's [`None`](<https://docs.python.org/3/builtins/constants.html#None>) discovers `objects.inv` at the mapping's base URL. The full inventory
uses each port's advertised default version. The `py` mapping explicitly
selects `latest`; `tmux` selects the latest tmux manual and C reference.
Use the root URL from an inventory's footer link when selecting a preview
or another release.

## Native Python roles

A named inventory selects the Python tree:

```rst
:external+py:py:class:`libtmux.Pane`
```

Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane).

The full inventory qualifies native names by port:

```rst
:external+full:py:class:`py:libtmux.Pane`
```

Destination: <a href={`${referenceHref('py', 'libtmux.Pane')}#libtmux.Pane`}>Pane in the Python default version</a>.

For automatic lookup, use the ordinary role. A local definition takes
precedence over Intersphinx:

```rst
:py:class:`libtmux.Pane`
```

Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane).

## Portable labels

Portable labels work with the standard reference role, including languages
that have no built-in Sphinx domain. Copy the key from `targets.json`.

```rst
:external+full:ref:`Pane <py:core:api:libtmux.%50ane>`
:external+py:ref:`Pane <py:core:api:libtmux.%50ane>`
```

Destinations: <a href={`${referenceHref('py', 'libtmux.Pane')}#libtmux.Pane`}>Full inventory: Pane</a>,
[Scoped inventory: Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane).

The external role searches the configured inventories without selecting one.
This native name is unqualified only in the scoped Python inventory:

```rst
:external:py:class:`libtmux.Pane`
```

Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane).

## MyST roles and inventory URLs

Enable `myst_parser` alongside
[`sphinx.ext.intersphinx`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html)
for Markdown sources.
Named roles accept the same targets as reStructuredText:

```markdown
{external+py:py:class}`libtmux.Pane`
```

Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane).

Portable labels retain their percent escapes inside reference roles:

```markdown
{external+full:ref}`Pane <py:core:api:libtmux.%50ane>`
```

Destination: <a href={`${referenceHref('py', 'libtmux.Pane')}#libtmux.Pane`}>Pane in the Python default version</a>.

MyST's inventory URL syntax also supports native aliases:

```markdown
[Pane](inv:py:py:class#libtmux.Pane)
```

Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane).

Use role syntax for percent-encoded portable keys: MyST normalizes escapes
in `inv:` URLs. Keep mapping names free of dots, as in `tmux-3-7c`, so MyST
can parse the role name. When using an inventory URL, specify its domain and
object type if a name is both a document and a label.

## tmux C declarations

The tmux mapping provides Sphinx's built-in C roles:

```rst
:external+tmux:c:struct:`cmd`
:external+tmux:c:func:`cmd_find_target`
```

Destinations: [cmd](https://libtmux.org/en/tmux/latest/reference/c-struct-cmd/#c%3Astruct%3Acmd),
[cmd_find_target](https://libtmux.org/en/tmux/latest/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target).

Select a release with its own mapping. The full inventory also offers
version-qualified native aliases:

```rst
:external+tmux-3-7c:c:func:`cmd_find_target`
:external+full:c:func:`tmux@3.7c:cmd_find_target`
:external+full:c:func:`tmux@latest:cmd_find_target`
```

Destinations: [Scoped: cmd_find_target in 3.7c](https://libtmux.org/en/tmux/3.7c/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target),
[Full: cmd_find_target in 3.7c](https://libtmux.org/en/tmux/3.7c/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target),
[Full: cmd_find_target in latest](https://libtmux.org/en/tmux/latest/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target).

MyST supports the same C roles and a typed inventory URL:

```markdown
{external+tmux:c:struct}`cmd`
{external+tmux:c:func}`cmd_find_target`
{external+full:c:func}`tmux@3.7c:cmd_find_target`
[cmd_find_target](inv:tmux:c:function#cmd_find_target)
```

Destinations: [MyST: cmd](https://libtmux.org/en/tmux/latest/reference/c-struct-cmd/#c%3Astruct%3Acmd),
[MyST: cmd_find_target](https://libtmux.org/en/tmux/latest/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target),
[MyST full: cmd_find_target in 3.7c](https://libtmux.org/en/tmux/3.7c/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target),
[Inventory URL: cmd_find_target](https://libtmux.org/en/tmux/latest/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target).

The C reference links each declaration to its source file and revision.
Portable labels also address its signatures, parameters, and sections.

## tmux hooks

Link a hook name to its catalog page with a portable label. The same key
works in the scoped tmux inventory and the full inventory:

```rst
:external+tmux:ref:`after-new-session <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fhooks%2fafter-new-session>`
:external+full:ref:`after-new-session <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fhooks%2fafter-new-session>`
```

Destinations: [Scoped: after-new-session](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-session/),
[Full: after-new-session](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-session/).

In MyST, use the same key inside a reference role. Preserve its percent
escapes:

```markdown
{external+tmux:ref}`after-new-session <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fhooks%2fafter-new-session>`
{external+full:ref}`after-new-session <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fhooks%2fafter-new-session>`
```

Destinations: [MyST scoped: after-new-session](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-session/),
[MyST full: after-new-session](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-session/).

## tmux formats

Link a format variable such as [`#{session_name}`](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/) to its catalog entry:

```rst
:external+tmux:ref:`session_name <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fformats%2fsession_name>`
:external+full:ref:`session_name <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fformats%2fsession_name>`
```

Destinations: [Scoped: session_name](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/),
[Full: session_name](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/).

The MyST references select the same scoped or full inventory:

```markdown
{external+tmux:ref}`session_name <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fformats%2fsession_name>`
{external+full:ref}`session_name <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fformats%2fsession_name>`
```

Destinations: [MyST scoped: session_name](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/),
[MyST full: session_name](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/).

## tmux CLI manual

The same tmux inventory covers command pages:

```rst
:external+tmux:ref:`capture-pane <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fcapture-pane>`
```

Destination: [capture-pane](https://libtmux.org/en/tmux/latest/manual/capture-pane/).

The document role works when the target is a whole page:

```rst
:external+tmux:doc:`Full manual <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2ffull>`
```

Destination: [Full tmux manual](https://libtmux.org/en/tmux/latest/manual/full/).

Select a command's manual page with the document role. Its portable key
also works in the full inventory:

```rst
:external+tmux:doc:`tmux new-session <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fnew-session>`
:external+full:doc:`tmux new-session <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fnew-session>`
```

Destinations: [Scoped: new-session](https://libtmux.org/en/tmux/latest/manual/new-session/),
[Full: new-session](https://libtmux.org/en/tmux/latest/manual/new-session/).

Use the same document role in MyST:

```markdown
{external+tmux:doc}`tmux new-session <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fnew-session>`
{external+full:doc}`tmux new-session <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fnew-session>`
```

Destinations: [MyST scoped: new-session](https://libtmux.org/en/tmux/latest/manual/new-session/),
[MyST full: new-session](https://libtmux.org/en/tmux/latest/manual/new-session/).

## Command options, environment variables, and terms

The Python port's workspace documentation exports standard-domain objects.
Set the program context before referencing an option:

```rst
.. program:: tmuxp load

:external+py:option:`--append`
```

Destination: [tmuxp load --append](https://libtmux.org/en/py/latest/workspace/cli/load/#arguments-and-flags-a-append).

Environment variables and glossary terms use their own roles. Qualify the
product when a term appears in more than one glossary:

```rst
:external+py:envvar:`COLUMNS`
:external+py:term:`async <py:core:async>`
```

Destinations: [COLUMNS](https://libtmux.org/en/py/latest/workspace/configuration/environment/#cli-and-runtime-variables-columns-lines-rows),
[async](https://libtmux.org/en/py/latest/reference/glossary/#async).

## MCP tools and schema fields

Portable labels also address protocol objects and individual JSON Schema
fields. No custom MCP domain is required:

```markdown
{external+py:ref}`Read tools batch <py:mcp:tool:call_read_tools_batch>`
{external+py:ref}`on_error <py:mcp:schema:mcp.tool.call_read_tools_batch.input%2fproperties%2fon_error>`
```

Destinations: [Read tools batch](https://libtmux.org/en/py/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch),
[on_error](https://libtmux.org/en/py/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Fon_error).

## Shared documentation and headings

The full inventory includes the shared documentation:

```rst
:external+full:doc:`Inventory guide <site:core:doc:intersphinx>`
:external+full:ref:`Configure Intersphinx <site:core:heading:intersphinx%23configure-intersphinx>`
```

Destinations: [Inventory guide](https://libtmux.org/en/meta/intersphinx/),
[Configure Intersphinx](https://libtmux.org/en/meta/intersphinx/#configure-intersphinx).

## Local files and fallback locations

Download an inventory and pass its filename as the second mapping value.
The first value remains the documentation URL used in generated links:

An ordered list tries a local copy before the HTTP inventory:

See the [inventory guide](https://libtmux.org/en/meta/intersphinx/) for key stability and the
[Sphinx Intersphinx reference](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html)
for configuration options.

---

# AI policy

Source: https://libtmux.org/en/raku/latest/meta/ai-policy/

> Use the libtmux packages with AI tools. When contributing, check what you submit and wait for a maintainer's invitation before preparing a pull request.

Last revised October 25, 2026

Use these packages with AI tools as you like. When contributing, check what
you submit and wait for a maintainer's invitation before preparing a pull
request.

This policy covers the libraries, ports, and documentation in the
[libtmux](https://github.com/libtmux) and
[tmux-python](https://github.com/tmux-python) organizations, including their
issues, comments, discussions, reviews, and pull requests.

## 1. For users: About these packages

We encourage you to use AI tools with our libraries and documentation,
including to generate code that calls the libraries. We want these projects to
be useful in the way you work. Some of what we publish supports that workflow:

- [MCP integrations](https://libtmux.org/en/py/latest/mcp/) that let assistants interact with tmux.
- Markdown documentation and `llms.txt` and `llms-full.txt` resources linked
  from documentation pages.
- `AGENTS.md` and other repository instructions for tools working on the
  codebase.

Use the documentation for the package, language, and version you are working
with.

### How the ports are made

The ports build on [tmuxp](https://tmuxp.git-pull.com/), started in 2013, and
[libtmux](https://libtmux.git-pull.com/), started in 2016. Both projects
predate today's LLM coding tools. Current work on the original projects and the
ports uses AI assistance.

Maintainers guide the design, review changes, test behavior against real tmux,
and decide what ships. They remain responsible for what the projects include
and maintain.

### Stability

Packages in the [libtmux organization](https://github.com/libtmux) are
experimental unless their README says otherwise. Names and APIs may change
between releases. Pin an exact version and review changes before upgrading.

## 2. For contributors: How to report issues, ideas, suggestions, and security issues

A useful issue is a contribution in its own right. Your experience helps us see
what breaks, what feels awkward, and what is missing. You do not need to arrive
with a patch.

Open bugs, ideas, and suggestions in the repository of the package they
concern. Report suspected security vulnerabilities privately using the route
below.

### Bugs

Tell us what you tried, what happened, and what you expected. Include a small
example we can run, the library and tmux versions, and the actual output.
Include relevant logs and error messages as they appeared, and distinguish what
you observed from possible explanations.

Bug reports are welcome whether the code you were running was handwritten or
generated. Include the code that ran. A conversation transcript is usually
unnecessary; include relevant prompts or tool calls when they are needed to
reproduce the problem.

### Ideas and suggestions

Explain what you wanted to accomplish and where the current design gets in
your way. We welcome feedback on:

- Usability: what was hard to find or get right, and where the documentation
  misled you.
- Language conventions: whether a port feels natural in the language you use.
- Aesthetics: how an API, a page, or an error message reads.
- Missing capabilities: what you could not accomplish with the current API.

If an API you expected is missing, describe the task and why that API would
help.

### Security issues

Report suspected security vulnerabilities privately. Use **Report a
vulnerability** on the affected repository's security page where available.

Include the affected package and version, the tmux version, what you observed,
and reproduction steps or relevant code references if available. Distinguish
verified behavior from suspected impact. Please coordinate public disclosure
with us so we can investigate and, where needed, prepare a fix.

Command execution explicitly requested through documented features is expected
behavior and does not, by itself, establish a vulnerability. Explain any
additional failure, such as data being interpreted as commands unexpectedly or
an intended security boundary being crossed.

### Writing your report

Short reports, typos, and imperfect English are fine. Translation and writing
assistance are welcome; check that the result says what you mean and preserves
the facts you observed. Your experience matters more than a polished report.

### Using AI tools

If AI materially helped prepare your issue, comment, discussion, review, or
pull request, say which tools you used, what they did, and what you checked
yourself. Using these tools does not count against a contribution. You remain
responsible for what you submit.

Do not send generated code, reports, or explanations you have not checked.

### Pull requests

Before preparing a pull request, open an issue or comment on an existing issue
about the proposed change. Wait for a maintainer to invite a PR for an agreed
scope. Opening an issue alone is not an invitation. PRs submitted without that
agreement may be closed without review. Arrange security fixes through the
private reporting route.

Even when we agree that something should change, we may prefer to write the
implementation ourselves. Review must consider correctness, supported tmux
versions, language conventions, documentation, and ongoing maintenance.
Checking those can take more time than writing the change, whether it was
handwritten or generated.

If we invite a PR, understand the changes, test them, and be able to explain
them. Follow the project's contribution instructions, and describe the tests
you ran and the versions you used. Generated code and tests can share the same
mistake, so passing tests alone do not show that a change fits the project.

Submit only material you have the right to contribute on terms compatible with
the project's license. Identify outside code, tests, or text incorporated into
the contribution, including material adapted with AI assistance, and provide
its source and license. Keep required notices, and raise unclear permissions
before including the material. These source and licensing requirements apply
to maintainers too.

<p class="site-credit">Acknowledgments: Informed by <a href="https://palletsprojects.com/contributing/llm-ai">Pallets’ LLM and AI Policy</a>, <a href="https://github.com/tmux/tmux/wiki/Contributing#use-of-ai">tmux’s AI contribution guidelines</a>, and <a href="https://openjdk.org/legal/ai">OpenJDK’s Interim Policy on Generative AI</a>. Licensing references: the GNU GPL FAQ on <a href="https://www.gnu.org/licenses/gpl-faq.en.html#TranslateCode">translating code</a> and <a href="https://www.gnu.org/licenses/gpl-faq.en.html#WhatDoesCompatMean">license compatibility</a>. All sources consulted <time datetime="2026-10">October 2026</time>.</p>

---

# Third-party notices

Source: https://libtmux.org/en/raku/latest/meta/third-party-notices/

> Thanks to tmux's creator and contributors, with licences and attribution for the software behind libtmux.org.

## tmux

First and foremost, thank you to **[Nicholas Marriott (nicm)](https://github.com/nicm)**,
the creator of tmux, and to the many
[tmux contributors](https://github.com/tmux/tmux/graphs/contributors).
We are grateful for the work that makes tmux possible.

libtmux is a separate project. Our libraries and supporting tools control a
real tmux server; tmux itself provides the terminal multiplexer. This is the
libtmux website. Visit the [official tmux website](https://github.com/tmux/tmux/wiki)
for the upstream project and its documentation.

See tmux's [COPYING file](https://github.com/tmux/tmux/blob/master/COPYING)
and the copyright and permission notices in its source files for its licensing.

### tmux artwork

The tmux logomark is by Jason Long. The site uses the unmodified
[upstream SVG](https://github.com/tmux/tmux/blob/8f25579c5aef8d93924a20681f394e2a582fd3ad/logo/tmux-logomark.svg)
under its [copyright and permission notice](https://libtmux.org/en/brand/tmux/LICENSE.txt).

## Programming-language artwork

The homepage language selector uses local copies of the following artwork
to identify the selected language. Each source record includes the download
URL, retrieval time, file hash, copyright information and usage terms.
These marks identify their respective languages and do not imply endorsement
of libtmux.

The SVG files are copied unchanged except for Scala and Rust. Scala's empty
surrounding canvas is cropped; its paths, gradients and colors are preserved,
and the original SVG is retained beside the cropped copy. Rust's supplied SVG
turns its mark white when the device is in dark mode. A browser does not
reliably apply that rule to this site's color setting when the file is shown
as an image. The rule is removed, its paths are unchanged, and the page
lightens the mark on a dark theme instead.

| Language | Credit and terms | Local source record |
|---|---|---|
| Python | Python Software Foundation. The [PSF logo terms](https://www.python.org/psf/trademarks/) permit the unaltered mark to identify Python. | [Python provenance](https://libtmux.org/en/brand/languages/py/provenance.json) |
| Ruby | Copyright © 2006, Yukihiro Matsumoto. The [Ruby logo](https://www.ruby-lang.org/en/about/logo/) is licensed under [CC BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/). | [Ruby provenance](https://libtmux.org/en/brand/languages/ruby/provenance.json) |
| Lua | Copyright © 1998 Lua.org; graphic design by Alexandre Nakonechnyj. The Devicon copy carries its [MIT notice](https://libtmux.org/en/brand/languages/lua/LICENSE.txt); [Lua's logo terms](https://www.lua.org/images/) also apply. Visit [Lua.org](https://www.lua.org/). | [Lua provenance](https://libtmux.org/en/brand/languages/lua/provenance.json) |
| TypeScript | Microsoft. The [official branding terms](https://www.typescriptlang.org/branding/) govern the mark; the website repository licenses exclude logo and trademark rights. | [TypeScript provenance](https://libtmux.org/en/brand/languages/ts/provenance.json) |
| Rust | The Rust Foundation. [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) and the [Rust trademark policy](https://rustfoundation.org/policy/rust-trademark-policy/) apply. | [Rust provenance](https://libtmux.org/en/brand/languages/rs/provenance.json) |
| Go | The [Go gopher](https://go.dev/blog/gopher) is by Renee French, licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). | [Go provenance](https://libtmux.org/en/brand/languages/go/provenance.json) |
| C++ | Created by Jeremy Kratz and licensed by the Standard C++ Foundation under its [logo-use terms](https://isocpp.org/home/terms-of-use). | [C++ provenance](https://libtmux.org/en/brand/languages/cxx/provenance.json) |
| Swift | Apple Inc., under the [Swift Logo Guidelines](https://developer.apple.com/swift/downloads/swift-logo.zip). Swift and the Swift logo are trademarks of Apple Inc. | [Swift provenance](https://libtmux.org/en/brand/languages/swift/provenance.json) |
| Java | Devicon collection copyright (c) 2015 konpa, with its [MIT notice](https://libtmux.org/en/brand/languages/java/LICENSE.txt). This does not establish unrestricted rights to the underlying Java logo; [Oracle's logo terms](https://www.oracle.com/legal/logos/) apply. | [Java provenance](https://libtmux.org/en/brand/languages/java/provenance.json) |
| Kotlin | Kotlin Foundation brand guidelines preserve JetBrains copyrights. The [icon-use terms](https://kotlinfoundation.org/guidelines/) permit identifying Kotlin alongside other programming-language icons. | [Kotlin provenance](https://libtmux.org/en/brand/languages/kotlin/provenance.json) |
| Scala | Copyright EPFL. [Historical permission](https://groups.google.com/g/scala-user/c/bCC-R0FQn1w) covers noncommercial Scala promotion; the [general artwork-license question](https://github.com/scala/scala-lang/issues/1040) remains unresolved. | [Scala provenance](https://libtmux.org/en/brand/languages/scala/provenance.json) |
| C# | Copyright the .NET authors. [Brand-use permission](https://github.com/dotnet/brand/issues/10#issuecomment-669465301) allows the unmodified logo to represent .NET. The repository's CC0 statement covers illustrations; no blanket CC0 claim is made for the logo. | [.NET provenance](https://libtmux.org/en/brand/languages/csharp/provenance.json) |
| F# | The F# Software Foundation. Its [logo terms](https://foundation.fsharp.org/logo) require unchanged shape, colors and proportions, without implying Foundation representation. | [F# provenance](https://libtmux.org/en/brand/languages/fsharp/provenance.json) |

## Terminal artwork

The tmux CLI selector displays the Windows Terminal artwork by Microsoft
Corporation, licensed under [CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/).
The SVG is unmodified. See the [source and provenance](https://libtmux.org/en/brand/tools/terminal/provenance.json)
and [copyright and license](https://libtmux.org/en/brand/tools/terminal/LICENSE.txt).

## Documentation toolchain

libtmux and this site are built with open-source software. The following
tools have their own licences and attribution requirements.

| Tool | Licence | Role |
|---|---|---|
| [Astro](https://astro.build/) | MIT | The site shell |
| [Tailwind CSS](https://tailwindcss.com/) | MIT | Styling |
| [Pagefind](https://pagefind.app/) | MIT | Site-wide search |
| [Expressive Code](https://expressive-code.com/) | MIT | Code blocks |
| [Sphinx](https://www.sphinx-doc.org/) | BSD-2-Clause | Python and C++ reference |
| [Furo](https://github.com/pradyunsg/furo) | MIT | Sphinx theme |
| [Breathe](https://github.com/breathe-doc/breathe) | BSD-3-Clause | Doxygen XML into Sphinx |
| [Doxygen](https://www.doxygen.nl/) | GPL-2.0-only | Parses C++ headers to XML |
| [API Extractor](https://api-extractor.com/) | MIT | TypeScript API model |
| [IBM Plex](https://github.com/IBM/plex) | OFL-1.1 | Typeface |

### A note on Doxygen

Doxygen is licensed GPL-2.0-only. It runs as a build step that reads libtmux's
own headers and emits XML; that XML is rendered by Breathe and Sphinx, and no
Doxygen-generated HTML is published. Running a GPL program over your own input
does not place its licence on the output, and libtmux does not distribute
Doxygen or any modified version of it.

## Syntax highlighting

Haskell code is highlighted with a copy of the TextMate grammar from the
[Haskell syntax-highlighting extension](https://github.com/haskell/vscode-haskell-syntax-highlighting).
Copyright © 2017 Justus Adam, licensed under
[BSD-3-Clause](https://github.com/haskell/vscode-haskell-syntax-highlighting/blob/36c48222a4b6d09ff7b7747fbf7f06f14a1d3046/LICENSE).
The grammar is unchanged apart from conversion to JSON; the site's repository
keeps it with the license text and a source record in
`site/src/vendor/haskell-grammar/`.

## Reference hosting

The [PyPI blocks logo](https://pypi.org/trademarks/) is a trademark of the
Python Software Foundation and identifies links to the Python Package Index.
Other package-host icons use [Simple Icons](https://simpleicons.org/)
(CC0-1.0). The docs.rs mark is its
[`docsdotrs` icon](https://github.com/simple-icons/simple-icons/blob/16.35.0/icons/docsdotrs.svg),
inlined unchanged. The book beside javadoc.io links is original artwork for
this site: the host publishes no vector logo, and the mark does not imitate
its favicon.

Some ports deep-link to the canonical host their ecosystem already uses,
rather than duplicating it here:

- Rust: [docs.rs](https://docs.rs/libtmux), for each published crate
- Go: [pkg.go.dev](https://pkg.go.dev/github.com/libtmux/libtmux-go/tmux)
- Java, Kotlin and Scala: [javadoc.io](https://javadoc.io/doc/io.github.libtmux/libtmux)
- Swift: the [Swift Package Index](https://swiftpackageindex.com/libtmux/libtmux-swift/documentation/libtmux)
  copy of the DocC reference

Those sites are operated independently of this project and carry their own
terms.

## libtmux itself

Each port is MIT licensed. See the `LICENSE` file in that port's repository
for the authoritative text.

---

# API glossary

Source: https://libtmux.org/en/raku/latest/reference/glossary/

> Kinds, modifiers and package labels in the Raku API reference.

## Symbol kinds

Kinds identify declarations in the Raku API reference.

### module

A Raku compilation unit that declares packages and exports declarations with is export.

The module badge names a namespace. LibTmux re-exports the public declarations of its modules, so use LibTmux gives programs the common names. A distribution and a module are different identities.

References: [Raku modules](https://docs.raku.org/language/modules).

### class

A Raku class: a package that creates objects with its own attributes and methods.

A captured model class reads local state. A reference class such as PaneRef names a tmux object and sends commands on request.

References: [Raku type system](https://docs.raku.org/language/typesystem).

### enum

A Raku enumeration: a set of named constants of one type.

Members compare by identity and keep their declared order.

References: [Raku type system](https://docs.raku.org/language/typesystem).

### trait

A Raku trait modifies a declaration with is, does or of.

A trait changes how the declaration behaves; it is not a Rust or Java trait.

References: [Raku traits](https://docs.raku.org/language/traits).

### function

A Raku sub: a routine called by name with no invocant.

A function with a hyphenated name is called as written, such as decode-layout.

References: [Raku functions](https://docs.raku.org/language/functions).

### method

A Raku method invoked on an object or a type object with a dot.

The invocant is implicit. A method that talks to tmux says so in its summary; one that reads a captured snapshot does not. A name ending in -async returns a Promise.

References: [Raku objects](https://docs.raku.org/language/objects).

### property

A public attribute accessor or a method declared as a field of a captured record.

Reading it returns the value the snapshot captured and performs no I/O.

References: [Raku objects](https://docs.raku.org/language/objects).

### constant

A named Raku value or enumeration member that cannot be reassigned.

An enumeration member is also listed under its enum.

References: [Raku variables](https://docs.raku.org/language/variables).

### typealias

A Raku subset or type constraint that gives a checked name to a narrower type.

The constraint runs when a value is bound. It does not create a new class.

References: [Raku type system](https://docs.raku.org/language/typesystem).

### exception

A Raku exception class that callers throw, catch with CATCH or try, and inspect by type.

LibTmux exceptions live under X::LibTmux and carry the fields the failure produced.

References: [Raku exceptions](https://docs.raku.org/language/exceptions).

## Modifiers

Modifiers add information about calling, implementing, or accessing a declaration. Their precise effect follows the language and the signature.

### async

An operation that returns a Promise and completes on the Raku scheduler.

Await the Promise or consume it with react and whenever. Completion of the Promise and release of its resources are separate; close what the operation owns.

References: [Raku concurrency](https://docs.raku.org/language/concurrency).

### overload

One of several multi declarations that share a name and differ in their signatures.

Raku selects the candidate from the argument types at the call. Read each signature for the types it accepts.

References: [Raku functions](https://docs.raku.org/language/functions).

### inherited

A method found through Raku class inheritance.

The page names the declaring class. A subclass reuses the method and its documented behavior unchanged.

References: [Raku type system](https://docs.raku.org/language/typesystem).

## Package context

Package labels identify where an API is supplied.

### package

The installable Raku distribution supplying this API, identified by name and authority.

The distribution LibTmux:auth<zef:libtmux> provides these modules.

References: [Raku modules](https://docs.raku.org/language/modules).

---

# Topics

Source: https://libtmux.org/en/raku/latest/topics/

> Check which tmux releases and platforms the library supports.

Check which tmux releases and platforms the library supports.

- [tmux compatibility](https://libtmux.org/en/raku/latest/topics/compatibility/): Status: accepted.

---

# tmux compatibility

Source: https://libtmux.org/en/raku/latest/topics/compatibility/

> Status: accepted.

Status: accepted.

## Decision

Support Linux and the declared stable tmux releases from 3.3a through 3.8.
Use the daemon's version and observed capabilities when selecting commands,
fields, codecs and layouts. A newer client executable does not upgrade the
daemon. Unknown and vendor releases require an explicit support decision.

Keep release profiles in [LibTmux::Catalogue](https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/lib/LibTmux/Catalogue.rakumod).
Each profile names its upstream commit. The oldest and newest profiles define
the required live CI jobs; intermediate releases retain pure compatibility
fixtures. Feature boundaries and known defects belong in the field catalogue.

## Rationale

Runtime checks and CI must agree on supported releases. Typed release records
provide one source for both without a separate configuration format. CI verifies
the fetched tag against the pinned commit; it does not need a second inventory
of individual [source-file](https://libtmux.org/en/tmux/latest/manual/source-file/) hashes.

Adding a supported release requires reviewing its feature and defect policies,
updating its profile, and passing the relevant fixtures and endpoint tests.