# libtmux for Haskell > The Haskell library (libtmux-haskell). These pages include its guides, tested examples and API documentation. - [Haskell API reference](https://libtmux.org/en/haskell/latest/reference/): every public symbol, generated from the source. Hosted on libtmux.org. --- # Typed tmux values for Haskell Source: https://libtmux.org/en/haskell/latest/core/ > Typed tmux values for Haskell. Parse tmux entity IDs, validate dimensions and indices, and check stable tmux releases with pure Haskell functions Client, capture and mutation APIs are under development. The workspace library and CLI are planned as a separate package using the core. MCP is excluded from this port. Read the [implementation status](https://libtmux.org/en/haskell/latest/guides/status/) before choosing the package for automation.Parse tmux entity IDs, validate dimensions and indices, and check stable tmux releases with pure Haskell functions. ## At a glance | Module | Provides | | ------ | -------- | | [`LibTmux.Id`](https://libtmux.org/en/haskell/latest/reference/libtmux-id/) | Distinct session, physical-window and physical-pane IDs. | | [`LibTmux.Value`](https://libtmux.org/en/haskell/latest/reference/libtmux-value/) | Positive dimensions and nonnegative contextual indices. | | [`LibTmux.Version`](https://libtmux.org/en/haskell/latest/reference/libtmux-version/) | Parse stable tmux releases and check the supported release range. | - [Getting started](https://libtmux.org/en/haskell/latest/guides/getting-started/): Install the source package and run the complete values example. - [Typed values](https://libtmux.org/en/haskell/latest/guides/typed-values/): Understand entity IDs, indices, dimensions and version admission. - [API reference](https://libtmux.org/en/haskell/latest/reference/): Public modules, types, constructors and functions from Haddock. - [Implementation status](https://libtmux.org/en/haskell/latest/guides/status/): Check public capabilities, compatibility evidence and package boundaries. --- # Getting started Source: https://libtmux.org/en/haskell/latest/guides/getting-started/ > Getting started: libtmux-haskell documentation. The public package currently provides typed tmux IDs, checked dimensions and indices, and stable-release parsing. Start with the complete [typed-value program](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/examples/typed-values/Main.hs), then follow the signatures in the [API guide](https://libtmux.org/en/haskell/latest/guides/api-documentation/). | Task | Guide | | --- | --- | | Add the source package to a Cabal application | [Installation](https://libtmux.org/en/haskell/latest/guides/installation/) | | Parse IDs, validate geometry and admit a release | [Typed values](https://libtmux.org/en/haskell/latest/guides/typed-values/) | | Browse modules, declarations and source | [API documentation](https://libtmux.org/en/haskell/latest/guides/api-documentation/) | | Decide whether the current package meets your needs | [Implementation status](https://libtmux.org/en/haskell/latest/guides/status/) | The [behavior contracts](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/docs/contracts/README.md) describe the implementation scope. They include operations that are not yet public APIs. The proposed [native domain model ADR](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/docs/decisions/0001-native-domain-model.md) compares sibling ports and records the object graph, naming and lifecycle decisions awaiting expert review. Repository setup and test authoring live in [contributing](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/.github/CONTRIBUTING.md) and [testing](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/.github/TESTING.md). --- # Guides Source: https://libtmux.org/en/haskell/latest/guides/ > Guides for libtmux-haskell. Install the source package, run the public values example, and understand the available API. - [Getting started](https://libtmux.org/en/haskell/latest/guides/getting-started/): Read about using libtmux for haskell. - [Installation](https://libtmux.org/en/haskell/latest/guides/installation/): Read about add the package to a cabal application. - [Typed values](https://libtmux.org/en/haskell/latest/guides/typed-values/): Read about typed tmux values. - [API documentation](https://libtmux.org/en/haskell/latest/guides/api-documentation/): Read about api documentation. - [Implementation status](https://libtmux.org/en/haskell/latest/guides/status/): Read about implementation status. --- # Installation Source: https://libtmux.org/en/haskell/latest/guides/installation/ > Installation: libtmux-haskell documentation. Use GHC 9.14.1, GHC2024 and Cabal 3.18.2.0. The package targets this compiler series on Linux x86_64 only. Install the pinned tools through the [contributor setup](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/.github/CONTRIBUTING.md#toolchain) if needed. Pin the source revision in your application's [`cabal.project`](): ```cabal packages: . index-state: 2026-11-06T00:00:00Z source-repository-package type: git location: https://github.com/libtmux/libtmux-haskell tag: f910d69f92a156df3390956470a1a3cd8a69e0fe ``` Add the library to the executable's dependencies. The [example package](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/examples/typed-values/libtmux-typed-values.cabal) is a complete starting point: ```cabal cabal-version: 3.18 name: libtmux-typed-values version: 0.0.0 build-type: Simple license: MIT executable typed-values main-is: Main.hs default-language: GHC2024 ghc-options: -Wall -Werror build-depends: base >=4.22 && <4.23, libtmux-haskell ^>=0.1.0.0 ``` Save [Main.hs](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/examples/typed-values/Main.hs) beside the package file, then download the package index before the first build: ```console $ cabal update ``` Build and run the example: ```console $ cabal run --verbose=0 typed-values ``` The [typed-value guide](https://libtmux.org/en/haskell/latest/guides/typed-values/) explains the output and what each check establishes. This example requires no running tmux server. The source revision above contains the current public scalar API. Native client operations and workspace tooling require further implementation; check [status](https://libtmux.org/en/haskell/latest/guides/status/) before choosing the package for automation. ## Native backend host requirements The private native backend targets Linux x86_64 with glibc 2.39 or newer for `pidfd_spawn`, compatible kernel pidfd operations, and exclusive child reaping ownership. Missing host operations fail before launch. This is separate from the public pure scalar API. See the [process host contract](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/docs/contracts/process.md#launch-and-host-requirements). --- # Typed values Source: https://libtmux.org/en/haskell/latest/guides/typed-values/ > Typed values: libtmux-haskell documentation. [Run the complete example](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/examples/typed-values/Main.hs) from a checkout: ```console $ cabal run --verbose=0 typed-values ``` Program output: ```text ("3.3a","@17",120) ``` The program parses supplied text and constructs values. Its only [`IO`]() prints the result; it neither inspects an installed tmux binary nor contacts a server. ## IDs and indices describe different things [`SessionId`](https://libtmux.org/en/haskell/latest/reference/libtmux-id/), [`WindowId`](https://libtmux.org/en/haskell/latest/reference/libtmux-id/) and [`PaneId`](https://libtmux.org/en/haskell/latest/reference/libtmux-id/) are distinct types. Their parsers require the corresponding `$`, `@` or `%` prefix, canonical decimal spelling and the native unsigned 32-bit range. Leading zeroes and whitespace are rejected. Use the rendering functions when producing external target text. An ID alone carries no endpoint or server lifetime. Parsing `@17` does not prove that a window exists. The ID API does not yet provide generation-bound references for external operations. [`WindowIndex`](https://libtmux.org/en/haskell/latest/reference/libtmux-value/) identifies a window link's position within a session. [`PaneIndex`](https://libtmux.org/en/haskell/latest/reference/libtmux-value/) identifies a pane's position within its window. Neither is an entity ID. A physical window may have several links, including multiple indices in the same session. ## Validate values where they enter the program Constructors return [`Either`](): dimensions must be positive; indices must be nonnegative. Their numeric accessors return [`Integer`](), so reading a value does not narrow it to a machine-sized integer. [`mkDimension`](https://libtmux.org/en/haskell/latest/reference/libtmux-value/) checks the mathematical domain. A particular tmux command can impose a smaller numeric range; successful construction does not establish that command's capability or maximum. ## Release admission has a limited meaning [`parseVersion`](https://libtmux.org/en/haskell/latest/reference/libtmux-version/) accepts stable releases and the output format of `tmux -V`, including one final LF. Development versions and trailing data are rejected. [`requireSupported`](https://libtmux.org/en/haskell/latest/reference/libtmux-version/) admits the inclusive range from tmux 3.3a through 3.8. Intermediate releases are supported; CI tests the endpoints. These functions validate the supplied release identity. They do not inspect the host or qualify all features of that release. See [implementation status](https://libtmux.org/en/haskell/latest/guides/status/) for the boundary between the exposed package and the transport work. The [API guide](https://libtmux.org/en/haskell/latest/guides/api-documentation/) links the public modules and their error types. --- # API documentation Source: https://libtmux.org/en/haskell/latest/guides/api-documentation/ > API documentation: libtmux-haskell documentation. The public modules are: | Module | Read it for | | --- | --- | | [LibTmux.Id](https://libtmux.org/en/haskell/latest/reference/libtmux-id/) | Distinct entity IDs, canonical parsing, rendering and [`IdError`]() | | [LibTmux.Value](https://libtmux.org/en/haskell/latest/reference/libtmux-value/) | Checked dimensions/indices, numeric access and [`ValueError`]() | | [LibTmux.Version](https://libtmux.org/en/haskell/latest/reference/libtmux-version/) | Stable-release identity, admission and [`VersionError`]() | Build the native Haddock browser from a checkout: ```console $ cabal haddock lib:libtmux-haskell ``` Open the `index.html` path printed by Cabal. Module overviews explain the types; declaration documentation specifies input domains, results and errors. The project enables declaration-to-source links, interactive symbol search and a Hoogle index for this package. The current public functions are pure: no field access or parser starts a tmux process. Haddock 2.33.0 generates some derived-instance method self-links without targets. Follow the instance's class link for its method contract. Package declaration links, symbol search and declaration-to-source navigation have been checked separately. The complete [typed-value example](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/examples/typed-values/Main.hs) uses only these exports. Its source and output are checked against the source archive by the [consumer check](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/scripts/check_sdist.py). Private graph, framing and transport modules are implementation details. They do not constitute an available client API; see [status](https://libtmux.org/en/haskell/latest/guides/status/). --- # Implementation status Source: https://libtmux.org/en/haskell/latest/guides/status/ > Implementation status: libtmux-haskell documentation. Use the current package for typed input values. The public library cannot yet observe or mutate a tmux server. | Component | Available to consumers | | --- | --- | | Entity ID parsing/rendering | Yes, through [`LibTmux.Id`]() | | Checked dimensions and indices | Yes, through [`LibTmux.Value`]() | | Stable-release parsing and supported-range admission | Yes, through [`LibTmux.Version`]() | | Client, complete captures and generation-bound references | In progress | | Typed query evaluation and commands | Not implemented | | Control events, streams and cancellation API | Not implemented | | Workspace library/CLI | Planned as a separate Cabal package using the core | | MCP integration | Excluded from this port | The internal graph, socket pin and process owner have separate tests. Their passing results do not establish a public automation interface. The [behavior inventory](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/docs/contracts/README.md) records the intended scope. ## Package policy The core favors GHC boot libraries and ordinary [`IO`](). Additional dependencies need a concrete requirement; JSON/YAML loading and command-line concerns belong in the workspace package. MCP is outside this port's scope. See the [package and dependency policy](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/.github/CONTRIBUTING.md#package-and-dependency-policy). ## Compatibility evidence CI uses GHC 9.14.1, GHC2024 and Cabal 3.18.2.0 on Linux x86_64. Its current integration subset exercises owned fixtures, scalar framing, private socket pins and process ownership with one and two RTS capabilities on exact tmux releases 3.3a and 3.8. The supported range includes all intermediate releases; CI tests its endpoints. The [workflow](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/.github/workflows/ci.yml) and [test guide](https://github.com/libtmux/libtmux-haskell/blob/581f0ee45016ffb2283366bb1edc1658df26c5ed/.github/TESTING.md) describe those checks. This is evidence for the implemented subset, not complete tmux API compatibility. No package-performance benchmark results are published. Test and private probe durations do not measure an installed public transport. --- # API glossary Source: https://libtmux.org/en/haskell/latest/reference/glossary/ > Kinds, modifiers and package labels in the Haskell API reference. ## Symbol kinds Kinds identify declarations in the Haskell API reference. ### module A named Haskell module that imports and exports declarations. A module qualifies names such as LibTmux.Id.parsePaneId. Documentation ownership by a data type does not add that type to the source name. References: [Haskell modules](https://www.haskell.org/onlinereport/haskell2010/haskellch5.html). ### data type A distinct Haskell type introduced by a data or newtype declaration. An opaque Haddock data header exposes the type name without revealing whether its implementation uses data or newtype. References: [Haskell datatype declarations](https://www.haskell.org/onlinereport/haskell2010/haskellch4.html#x10-680004.2). ### data constructor A Haskell value constructor that builds one form of a data type. Constructors can carry fields and appear in patterns. A qualified constructor takes its module name, not its data type name. References: [Haskell algebraic datatypes](https://www.haskell.org/onlinereport/haskell2010/haskellch4.html#x10-690004.2.1). ### record field A Haskell record label used in construction, update and pattern matching. The qualified modules use NoFieldSelectors. Their exported record labels do not generate top-level selector functions. References: [GHC field selectors](https://downloads.haskell.org/ghc/9.14.1/docs/users_guide/exts/field_selectors.html). ### function A Haskell binding with a function type, applied to arguments by juxtaposition. Arguments are curried. Acquisition and mutation require an explicit effect such as IO in the signature. References: [Haskell function bindings](https://www.haskell.org/onlinereport/haskell2010/haskellch4.html#x10-830004.4.3). ## Modifiers Modifiers add information about calling, implementing, or accessing a declaration. Their precise effect follows the language and the signature. ### opaque A Haskell type exported without its data constructors. Callers use exported operations rather than hidden constructors or representation. This does not establish whether the implementation uses data or newtype. References: [Haskell abstract datatypes](https://www.haskell.org/onlinereport/haskell2010/haskellch5.html#x11-1150005.8). ## Package context Package labels identify where an API is supplied. ### package The Cabal package supplying these exposed Haskell modules. A package name and a module name are different identities. Availability from source does not imply publication on Hackage. References: [Cabal package descriptions](https://cabal.readthedocs.io/en/3.18/cabal-package-description-file.html). --- # Haskell workspace manager is not published Source: https://libtmux.org/en/haskell/latest/workspace/ > The Haskell workspace library and command-line tool are planned. No workspace package or loader command is available. Haskell has no published libtmux workspace manager. The planned library and command-line tool will live in a separate Cabal package and use the core library to operate on tmux. There is no workspace package to install, loader command to run, or workspace API reference yet. The current public core provides typed IDs, checked dimensions and indices, and tmux-version admission. Start with the [core library](https://libtmux.org/en/haskell/latest/core/) and its [tested values example](https://libtmux.org/en/haskell/latest/guides/typed-values/). Read the [implementation status](https://libtmux.org/en/haskell/latest/guides/status/) for the available capabilities and remaining work. --- # Linking and consuming our docs Source: https://libtmux.org/en/haskell/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 guides and MCP contracts 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/haskell/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`]() 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`]() declaration has this reStructuredText reference: ```rst :external+libtmux:ref:`Pane ` ``` With MyST enabled in your project, the same label works in Markdown: ```markdown {external+libtmux:ref}`Pane ` ``` 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 ` ``` 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`. A fully qualified alias includes the product too: `py:core:libtmux.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/haskell/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`]() 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: Pane in the Python default version. 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 ` :external+py:ref:`Pane ` ``` Destinations: Full inventory: Pane, [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 ` ``` Destination: Pane in the Python default version. 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 ` :external+full:ref:`after-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 ` {external+full:ref}`after-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 ` :external+full:ref:`session_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 ` {external+full:ref}`session_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 ` ``` 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 ` ``` 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 ` :external+full:doc:`tmux new-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 ` {external+full:doc}`tmux new-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 ` ``` 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 ` {external+py:ref}`on_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 ` :external+full:ref:`Configure 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/haskell/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.

Acknowledgments: Informed by Pallets’ LLM and AI Policy, tmux’s AI contribution guidelines, and OpenJDK’s Interim Policy on Generative AI. Licensing references: the GNU GPL FAQ on translating code and license compatibility. All sources consulted .

--- # Third-party notices Source: https://libtmux.org/en/haskell/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. ## 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.