# Architecture

Source: https://libtmux.org/en/tmux/topics/architecture/

> Locate operations, distinguish snapshots from live commands, and find their implementation.

A server handle selects a tmux server. Object IDs select sessions, windows, and
panes within it. For the object hierarchy and stable IDs, start with [Server,
session, window, pane](https://libtmux.org/en/tmux/concepts/server-session-window-pane/).

<a id="where-behavior-lives-on-the-object-or-through-the-server"></a>

## Calling operations

Session, window, and pane handles carry their ID and server context. Call an
operation on the object you want to change. The examples below send input and
kill that pane.

```python
pane.send_keys("echo hi")
pane.kill()
```

```typescript
await pane.sendKeys("echo hi");
await pane.kill();
```

```go
cmd := "printf 'hello\\n'"
if err := pane.SendKeys(ctx, tmux.SendKeysRequest{Command: &cmd, Literal: true}); err != nil {
    return err
}
if err := pane.Kill(ctx); err != nil {
    return err
}
```

```rust
pane.send_line("echo hi").await?;
pane.kill().await?; // consumes the handle: see Context managers
```

```java
pane.sendLine("echo hi");
pane.kill();
```

```csharp
await pane.SendTextAsync("echo hi");
await pane.KillAsync();
```

```cpp
pane->send_text("echo hi");
pane->kill();
```

Swift's [`Session`](<https://libtmux.org/en/swift/latest/reference/session/>), [`Window`](<https://libtmux.org/en/swift/latest/reference/window/>), and [`Pane`](<https://libtmux.org/en/swift/latest/reference/pane/>) are [`Sendable`](<https://developer.apple.com/documentation/swift/sendable>) value types holding IDs
and state fields. [Format-token fields](https://libtmux.org/en/tmux/topics/format-tokens/) lists their fields.
Perform operations through [`Server`](<https://libtmux.org/en/swift/latest/reference/server/>), passing the target value:

```swift
try await server.sendKeys(["echo hi", "Enter"], to: pane)
try await server.kill(pane)
```

Keep the [`Server`](<https://libtmux.org/en/swift/latest/reference/server/>) that produced the snapshot. Pass its captured values back to
that server for operations.

<a id="a-generated-data-table-under-a-hand-written-surface"></a>

## Reading tmux fields

Object IDs become tmux targets (`-t`). Format variables (`#{...}`) provide
the state returned by tmux.

### Python
[`libtmux.constants`](<https://libtmux.org/en/py/latest/reference/#libtmux.constants>) defines the format fields and their scope and tmux-version
requirements. [`Obj`](<https://libtmux.org/en/py/latest/reference/libtmux-neo-obj/>) in [`libtmux.neo`](<https://libtmux.org/en/py/latest/reference/#libtmux.neo>) exposes the captured values as dataclass
fields. A field excluded by those requirements is [`None`](<https://docs.python.org/3/library/constants.html#None>).

### TypeScript
[`packages/libtmux/src/_generated/format_fields.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/_generated/format_fields.ts>) records each token's scope
and first tmux version. [`packages/libtmux/src/_generated/field_aliases.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/_generated/field_aliases.ts>)
provides camelCase aliases for fields on [`Pane`](<https://libtmux.org/en/ts/latest/reference/pane-pane/>), [`Session`](<https://libtmux.org/en/ts/latest/reference/session-session/>), and [`Window`](<https://libtmux.org/en/ts/latest/reference/window-window/>).

### Go
[`tmux/format_generated.go`](<https://github.com/libtmux/libtmux-go/blob/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/format_generated.go>) defines format fields, and
[`tmux/option_generated.go`](<https://github.com/libtmux/libtmux-go/blob/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/option_generated.go>) defines options. The format generator lives in
[`tmux/internal/generate/formats/`](<https://github.com/libtmux/libtmux-go/tree/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/internal/generate/formats>). Accessors return a value and a boolean
when a field can be unavailable; check the boolean before using the value.

### Rust
[`crates/libtmux/src/formats.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/formats.rs>) defines the format catalog. Each entry records
the tmux name, required context, first supported release, decoder, and handling
of empty values. [`crates/libtmux/src/snapshot.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/snapshot.rs>) uses that catalog to decode
captured fields.

Handle accessors such as [`Pane.current_command`](<https://libtmux.org/en/rs/latest/reference/pane-pane-current_command/>) return `Option<T>` when a
value can be absent. Typed field queries return [`Availability`](<https://libtmux.org/en/rs/latest/reference/snapshot-availability/>), which also
distinguishes an unsupported field from an absent value. See
[Format-token fields](https://libtmux.org/en/tmux/topics/format-tokens/) for field availability.

### Java
Typed field classes such as [`Pane_`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-pane_-pane_/>) and [`Session_`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-session_-session_/>) support the query layer.
Accessors use `Optional<T>` for fields that may be unavailable on the running
tmux version. [Filtering and queries](https://libtmux.org/en/java/latest/concepts/queries/) explains how to
select and query those fields.

### C#
Typed properties read a dictionary captured from tmux. A property throws
[`IncompleteSnapshotException`](<https://libtmux.org/en/csharp/latest/reference/libtmux-incompletesnapshotexception/>) when the capture did not request its field.
This differs from a captured field whose value is absent.

### Swift
Snapshots capture a fixed set of non-optional fields, including indices,
dimensions, active state, command, path, and edge flags.
[Format-token fields](https://libtmux.org/en/tmux/topics/format-tokens/) covers other tokens.

### C++
Handles capture a fixed set of non-optional fields. Use
[`pane->expand("#{...}")`](<https://libtmux.org/en/cxx/latest/reference/libtmux-pane-expand/>) for tokens outside those fields.
[Format-token fields](https://libtmux.org/en/tmux/topics/format-tokens/) covers their interpretation.

<a id="module-layout-by-port"></a>

## Source layout

### Python
[`Server`](<https://libtmux.org/en/py/latest/reference/libtmux-server/>), [`Session`](<https://libtmux.org/en/py/latest/reference/libtmux-session/>), [`Window`](<https://libtmux.org/en/py/latest/reference/libtmux-window/>), [`Pane`](<https://libtmux.org/en/py/latest/reference/libtmux-pane/>), and [`Client`](<https://libtmux.org/en/py/latest/reference/libtmux-client/>) each have their own module:
[`src/libtmux/server.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/server.py>), [`src/libtmux/session.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/session.py>), [`src/libtmux/window.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/window.py>),
[`src/libtmux/pane.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/pane.py>), and [`src/libtmux/client.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/client.py>).

[`src/libtmux/common.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/common.py>) holds shared behavior. [`src/libtmux/neo.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/neo.py>) defines
the dataclass query layer, [`src/libtmux/options.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/options.py>) and [`src/libtmux/hooks.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/hooks.py>)
provide mixins, and [`src/libtmux/exc.py`](<https://github.com/tmux-python/libtmux/blob/9fdd083a8181a827889337b63cd4e6daea661a8c/src/libtmux/exc.py>) defines the exception hierarchy.

### TypeScript
The public classes live in [`packages/libtmux/src/server.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/server.ts>),
[`packages/libtmux/src/session.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/session.ts>), [`packages/libtmux/src/window.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/window.ts>),
[`packages/libtmux/src/pane.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/pane.ts>), and [`packages/libtmux/src/client.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/client.ts>).

Their operations are split by concern under
[`packages/libtmux/src/_internal/operations/`](<https://github.com/libtmux/libtmux-ts/tree/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/_internal/operations>), including
[`packages/libtmux/src/_internal/operations/pane_io.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/_internal/operations/pane_io.ts>),
[`packages/libtmux/src/_internal/operations/hooks.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/_internal/operations/hooks.ts>),
[`packages/libtmux/src/_internal/operations/options.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/_internal/operations/options.ts>), and
[`packages/libtmux/src/_internal/operations/topology.ts`](<https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/_internal/operations/topology.ts>).
[`packages/libtmux/src/_generated/`](<https://github.com/libtmux/libtmux-ts/tree/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/_generated>) contains the generated field catalogs.
Workspaces and the MCP server have separate packages in the same repository.

### Go
The [`tmux`](<https://libtmux.org/en/go/latest/reference/#tmux>) package groups its implementation by concern. [`tmux/model.go`](<https://github.com/libtmux/libtmux-go/blob/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/model.go>)
defines the core structs. [`tmux/lifecycle_kill.go`](<https://github.com/libtmux/libtmux-go/blob/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/lifecycle_kill.go>), [`tmux/pane_capture.go`](<https://github.com/libtmux/libtmux-go/blob/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/pane_capture.go>),
[`tmux/pane_geometry.go`](<https://github.com/libtmux/libtmux-go/blob/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/pane_geometry.go>), and [`tmux/hierarchy.go`](<https://github.com/libtmux/libtmux-go/blob/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/hierarchy.go>) implement lifecycle,
capture, geometry, and traversal. [`tmux/plan_server.go`](<https://github.com/libtmux/libtmux-go/blob/6f3df55f8a41999e41225eefb3940545b834e6a2/tmux/plan_server.go>) combines commands
into fewer invocations.

[`tmuxq/`](<https://github.com/libtmux/libtmux-go/tree/6f3df55f8a41999e41225eefb3940545b834e6a2/tmuxq>) provides predicate queries over an already-read snapshot; see
[Filtering and queries](https://libtmux.org/en/go/latest/concepts/queries/). Workspace support lives in
[`workspace/`](<https://github.com/libtmux/libtmux-go/tree/6f3df55f8a41999e41225eefb3940545b834e6a2/workspace>).

### Rust
[`Server`](<https://libtmux.org/en/rs/latest/reference/server-server/>), [`Session`](<https://libtmux.org/en/rs/latest/reference/session-session/>), [`Window`](<https://libtmux.org/en/rs/latest/reference/window-window/>), and [`Pane`](<https://libtmux.org/en/rs/latest/reference/pane-pane/>) are defined in
[`crates/libtmux/src/server.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/server.rs>), [`crates/libtmux/src/session.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/session.rs>),
[`crates/libtmux/src/window.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/window.rs>), and [`crates/libtmux/src/pane.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/pane.rs>).
Their additional operations live in [`crates/libtmux/src/server/`](<https://github.com/libtmux/libtmux-rs/tree/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/server>),
[`crates/libtmux/src/session/`](<https://github.com/libtmux/libtmux-rs/tree/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/session>), [`crates/libtmux/src/window/`](<https://github.com/libtmux/libtmux-rs/tree/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/window>), and
[`crates/libtmux/src/pane/`](<https://github.com/libtmux/libtmux-rs/tree/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/pane>).

The [options and hooks](https://libtmux.org/en/tmux/topics/options-and-hooks/) methods are grouped in
[`crates/libtmux/src/server/settings.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/server/settings.rs>),
[`crates/libtmux/src/session/settings.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/session/settings.rs>),
[`crates/libtmux/src/window/settings.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/window/settings.rs>), and
[`crates/libtmux/src/pane/settings.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/pane/settings.rs>).
[`crates/libtmux/src/hooks.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/hooks.rs>) defines [`IndexedHooks`](<https://libtmux.org/en/rs/latest/reference/hooks-indexedhooks/>) and [`SparseValues`](<https://libtmux.org/en/rs/latest/reference/hooks-sparsevalues/>);
[`crates/libtmux/src/options.rs`](<https://github.com/libtmux/libtmux-rs/blob/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/libtmux/src/options.rs>) defines option schemas and values.
Workspaces and the MCP server are separate crates under
[`crates/tmux-workspace/`](<https://github.com/libtmux/libtmux-rs/tree/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/tmux-workspace>) and [`crates/tmux-mcp/`](<https://github.com/libtmux/libtmux-rs/tree/a6fc2a65674177b92b17fa380757155d2ba150fd/crates/tmux-mcp>).

### Java
[`libtmux/src/main/java/io/github/libtmux/`](<https://github.com/libtmux/libtmux-java/tree/a0ecbc16da00140e2520462d478a2af470878272/libtmux/src/main/java/io/github/libtmux>) holds the [`Server`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-server-server/>), [`Session`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-session-session/>),
[`Window`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-window-window/>), and [`Pane`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-pane-pane/>) classes. Their `options()` and `hooks()` accessors
return [`Options`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-options-options/>) and [`Hooks`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-hooks-hooks/>) views scoped to the object.
[`Session_`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-session_-session_/>), [`Window_`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-window_-window_/>), and [`Pane_`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-pane_-pane_/>) are typed-field classes for the query layer.

### C#
[`src/LibTmux/`](<https://github.com/libtmux/libtmux-dotnet/tree/ec8b6ab2a4f65e23664f43fba538ba200d4ae8bc/src/LibTmux>) splits each entity into partial-class files by concern.
For example, [`src/LibTmux/Pane.cs`](<https://github.com/libtmux/libtmux-dotnet/blob/ec8b6ab2a4f65e23664f43fba538ba200d4ae8bc/src/LibTmux/Pane.cs>), [`src/LibTmux/Pane.Capture.cs`](<https://github.com/libtmux/libtmux-dotnet/blob/ec8b6ab2a4f65e23664f43fba538ba200d4ae8bc/src/LibTmux/Pane.Capture.cs>),
[`src/LibTmux/Pane.Input.cs`](<https://github.com/libtmux/libtmux-dotnet/blob/ec8b6ab2a4f65e23664f43fba538ba200d4ae8bc/src/LibTmux/Pane.Input.cs>), [`src/LibTmux/Pane.Relations.cs`](<https://github.com/libtmux/libtmux-dotnet/blob/ec8b6ab2a4f65e23664f43fba538ba200d4ae8bc/src/LibTmux/Pane.Relations.cs>),
[`src/LibTmux/Pane.Scopes.cs`](<https://github.com/libtmux/libtmux-dotnet/blob/ec8b6ab2a4f65e23664f43fba538ba200d4ae8bc/src/LibTmux/Pane.Scopes.cs>), and [`src/LibTmux/Pane.Topology.cs`](<https://github.com/libtmux/libtmux-dotnet/blob/ec8b6ab2a4f65e23664f43fba538ba200d4ae8bc/src/LibTmux/Pane.Topology.cs>) contribute
to one [`Pane`](<https://libtmux.org/en/csharp/latest/reference/libtmux-pane/>) type. `Options` and `Hooks` views are reached through the
object's properties.

### C++
[`include/libtmux/entities.hpp`](<https://github.com/libtmux/libtmux-cxx/blob/3f93b021cb51e8349bfb9cecc6fd4091f6e79a0f/include/libtmux/entities.hpp>) declares [`Session`](<https://libtmux.org/en/cxx/latest/reference/libtmux-session/>), [`Window`](<https://libtmux.org/en/cxx/latest/reference/libtmux-window/>), and [`Pane`](<https://libtmux.org/en/cxx/latest/reference/libtmux-pane/>).
Their method bodies live in [`src/`](<https://github.com/libtmux/libtmux-cxx/tree/3f93b021cb51e8349bfb9cecc6fd4091f6e79a0f/src>). [`include/libtmux/server.hpp`](<https://github.com/libtmux/libtmux-cxx/blob/3f93b021cb51e8349bfb9cecc6fd4091f6e79a0f/include/libtmux/server.hpp>),
[`include/libtmux/options.hpp`](<https://github.com/libtmux/libtmux-cxx/blob/3f93b021cb51e8349bfb9cecc6fd4091f6e79a0f/include/libtmux/options.hpp>), and [`include/libtmux/capabilities.hpp`](<https://github.com/libtmux/libtmux-cxx/blob/3f93b021cb51e8349bfb9cecc6fd4091f6e79a0f/include/libtmux/capabilities.hpp>)
define server operations, options, and capability checks.

The [`include/libtmux/testing/`](<https://github.com/libtmux/libtmux-cxx/tree/3f93b021cb51e8349bfb9cecc6fd4091f6e79a0f/include/libtmux/testing>) component is separate from the library;
[Context managers](https://libtmux.org/en/tmux/topics/context-managers/) explains its test-server ownership.

### Swift
[`Sources/LibTmux/Server.swift`](<https://github.com/libtmux/libtmux-swift/blob/7993e7044347629b08020e9b02ae8bcffa0e5898/Sources/LibTmux/Server.swift>) defines [`Server`](<https://libtmux.org/en/swift/latest/reference/server/>). [`Sources/LibTmux/Session.swift`](<https://github.com/libtmux/libtmux-swift/blob/7993e7044347629b08020e9b02ae8bcffa0e5898/Sources/LibTmux/Session.swift>),
[`Sources/LibTmux/Window.swift`](<https://github.com/libtmux/libtmux-swift/blob/7993e7044347629b08020e9b02ae8bcffa0e5898/Sources/LibTmux/Window.swift>), and [`Sources/LibTmux/Pane.swift`](<https://github.com/libtmux/libtmux-swift/blob/7993e7044347629b08020e9b02ae8bcffa0e5898/Sources/LibTmux/Pane.swift>) define the
snapshot value types. [`Sources/LibTmux/Snapshot.swift`](<https://github.com/libtmux/libtmux-swift/blob/7993e7044347629b08020e9b02ae8bcffa0e5898/Sources/LibTmux/Snapshot.swift>) implements the
[relationship queries](https://libtmux.org/en/tmux/topics/traversal/).

Extensions on [`Server`](<https://libtmux.org/en/swift/latest/reference/server/>) group related operations:
[`Sources/LibTmux/Options.swift`](<https://github.com/libtmux/libtmux-swift/blob/7993e7044347629b08020e9b02ae8bcffa0e5898/Sources/LibTmux/Options.swift>) implements options and hooks,
[`Sources/LibTmux/PaneInteraction.swift`](<https://github.com/libtmux/libtmux-swift/blob/7993e7044347629b08020e9b02ae8bcffa0e5898/Sources/LibTmux/PaneInteraction.swift>) handles input and capture, and
[`Sources/LibTmux/Mutations.swift`](<https://github.com/libtmux/libtmux-swift/blob/7993e7044347629b08020e9b02ae8bcffa0e5898/Sources/LibTmux/Mutations.swift>) handles changes such as killing a pane.

## Naming conventions

Method names follow language conventions: Python, Rust, and C++ use
`snake_case`; TypeScript, Java, and Swift use `camelCase`; Go and C# use
`PascalCase`. Option and hook names remain tmux's dash-separated strings, such
as `automatic-rename`, regardless of the method's spelling.