An Elixir library for controlling tmux. The core provides exact target references, shared deadlines, command encoding, bounded protocol parsing, Linux one-shot execution, immutable graph capture, Enumerable selections and portable filters. The domain client API remains under development.

Contributing · First task · Design · Encoding · Mental model · Observations · Filtering · Ownership · Writing · Artwork

Status and requirements

.tool-versions selects the development toolchain ranges for mise and CI. Linux builds require a C11 compiler for the helper. See setup for installation and upgrades. tmux is not required for the pure checks. Capture, command execution and the complete example require an external tmux executable. The supported client API and compatibility matrix remain under qualification.

Installation

Add the alpha release to your Mix dependencies:

{:libtmux, "== 0.0.1-alpha.1"}

Fetch dependencies:

$ mix deps.get

Capture, select and execute

From a source checkout, run the complete public API example from the packed core on a new isolated tmux server. This requires Linux, a C11 compiler, Python 3 and tmux 3.3 or newer:

$ MIX_ENV=test mix run scripts/check_package.exs --examples

The example captures one graph, selects its active pane, and reads that exact pane through one-shot and control commands. It checks the acknowledged result, retires its connection, and verifies owned server cleanup. The check uses a temporary socket and empty configuration. See the complete program and failure behavior.

Check the implementation

From the checkout, with the development toolchain on PATH, check formatting:

$ mix format --check-formatted

Run the pure unit suite:

$ mix test

Compile with warnings treated as errors:

$ mix compile --warnings-as-errors

With Hex installed, build a local package archive:

$ mix hex.build

Check public core imports from a packed archive outside the checkout:

$ mix run scripts/check_package.exs

The unit and packed-core checks validate the current foundations. Real integration checks cover owned startup/teardown and hostile command/format bytes through real tmux. They do not qualify the future client API or a complete compatibility matrix. See Contributing for setup, timing budgets, and the checks required as implementation arrives.

Planned package boundaries

The core provides immutable observations and explicit tmux operations, using Elixir and OTP without third-party runtime dependencies. Workspace loading and an MCP server have separate Mix projects under packages/. Their runtime implementations remain planned. MCP also consumes workspace behavior rather than maintaining a second loader or planner.

The design note records these boundaries and the contracts that implementation must prove. It is not an API reference.

Contributing and references

Follow the contribution guide and writing guide. Agent instructions start in AGENTS.md.

Related projects: libtmux for Python, libtmux ports, and tmux.

Licensed under the MIT License.