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
| Component | Current scope |
|---|---|
| Mix application | :libtmux, version 0.0.1-alpha.1 |
| Development toolchain | Elixir 1.20.x (at least 1.20.4) on Erlang/OTP 29.x |
| Planned tmux floor | 3.3; fixture checks precede client compatibility qualification |
| Runtime dependencies | No third-party packages; own native I/O helper |
| Platforms | No runtime support matrix has been qualified |
.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.