# Getting started

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

> Getting started: LibTmux documentation.

Control tmux with explicit commands, captured graphs, and ordinary Perl arrays.
Targets stable Perl 5.44.0 and Linux x86_64, including WSL. These development
distributions are not published on CPAN.

```perl
use v5.44;
use LibTmux::Server;

my $server = LibTmux::Server->new(socket_name => 'example');
my $snapshot = $server->snapshot;  # Explicit I/O; server must already exist.
my $active = $snapshot->panes
    ->where({ active => true, width => { -gte => 80 } })
    ->grep(sub ($pane) { $pane->current_command eq 'sleep' });

for my $pane ($active->@*) {
    say $pane->id, ' ', $pane->window->name;
}
```

| Distribution | Location | Runtime dependencies |
| --- | --- | --- |
| [`LibTmux`](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/packages/core/README.md) | [packages/core](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/packages/core) | Perl standard library. |
| [`LibTmux-Async`](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/packages/async/README.md) | [packages/async](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/packages/async) | Versioned core, Future, IO::Async::Loop::Ppoll and IO::Ppoll; caller-owned Ppoll loop. |
| [`LibTmux-Workspace`](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/packages/workspace/README.md) | [packages/workspace](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/packages/workspace) | Versioned core; packaged JSON loader CLI. |

Start with [installation](https://libtmux.org/en/perl/latest/guides/installation/),
[basic orchestration](https://libtmux.org/en/perl/latest/examples/orchestration/), and
[filtering](https://libtmux.org/en/perl/latest/guides/filtering/). Read [graph identity](https://libtmux.org/en/perl/latest/concepts/graph/) before
working with linked windows, [query planning](https://libtmux.org/en/perl/latest/topics/query-planning/) for
explicit native filters, [errors and recovery](https://libtmux.org/en/perl/latest/topics/errors/),
[async execution](https://libtmux.org/en/perl/latest/guides/async/), and [workspace loading](https://libtmux.org/en/perl/latest/workspace/source-guide/).
The [architecture decisions](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/docs/dev/adr/index.md) explain these contracts,
their alternatives, and the upstream source models behind them.
Installed API documentation uses native POD; for example `perldoc
LibTmux::Server` and `perldoc LibTmux::Selection`.

[Complete examples](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/examples) run against uniquely owned tmux sockets and
assert results and cleanup. [Compatibility](https://libtmux.org/en/perl/latest/topics/compatibility/) records
support for tmux 3.3a–3.8 and CI coverage of the range endpoints. Captured
selections perform no tmux I/O; their methods preserve order and duplicates
and return one fixed type in every calling context. Native array access
remains available.

MCP is excluded. Persistent control mode, streaming APIs, tmux command lists,
serialized regexes, and relation pushdown are deferred. Package publication
and shared-site deployment require separate authority.

See [contributing](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/.github/CONTRIBUTING.md) for exact checks and tool setup,
[Perl choices](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/.github/PERL.md) for source-backed decisions, and
[branding assets](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/docs/branding.md) for logos and social cards.