term-wm

WORK IN PROGRESS.

A cross-platform terminal multiplexer, window manager, and Ratatui component library.

It is controllable via mouse and keyboard and works the same over SSH, Mac, Linux, and Windows.

pictured: term-wm 0.5.0-alpha on macOS

term-wm serves two distinct purposes:

• For Users: A standalone, keyboard-driven window manager for your terminal shell.
• For Developers: A reusable library of TUI primitives for building window-managed Ratatui applications.

Design Philosophy: Retro-Modern

term-wm is heavily inspired by the utilitarian beauty of 90's Unix user interfaces (like CDE) and the cooperative tiling of Windows 1.0.

It bridges the gap between standard terminal multiplexers and full desktop environments by adapting GUI metaphors to the command line.

Working with the terminal grid, the project aims to provide a rich window management experience despite the architectural constraints of a text-based terminal. Since terminals lack pixel-perfect positioning and rely on a rigid character cell grid, term-wm employs creative layout algorithms to make borders, resizing, and overlapping layers feel fluid and natural, even within the strict boundaries of ANSI/VT standards.

For Users: The Window Manager

As a standalone application, term-wm allows you to manage multiple shell sessions, panes, and floating windows with a philosophy centered on zero-conflict key bindings with your running applications.

The "No-Conflict" Philosophy (Esc)

Unlike other multiplexers that require complex prefix chords (like Ctrl+b), term-wm uses Esc as a context-aware modifier. This ensures that sub-shells and embedded apps (like vim, tmux, screen, etc.) retain their own keybindings without fighting the window manager.

Should the Esc key need to be sent to a child window, pressing Esc twice (double-Esc) will route it to the window as a single key press.

For Developers: The Library

term-wm exports its core logic as a crate, allowing you to build complex terminal user interface (TUI) applications without reinventing view navigation or layout engines.

It provides a framework to render Ratatui components in a fashion that automatically handles focus routing and view lifecycle, letting you focus on component creation while term-wm enforces consistent layout.

Layout Contracts

The library uses Layout Contracts to define how screen real estate is negotiated between your application logic and the term-wm engine:

• AppManaged: The application retains full control. You set regions and coordinates directly; the WM steps back.
• WindowManaged: The window manager (WM) takes ownership. It enforces tiling, floating rules, and standard constraints, managing the dimensions of your components automatically.

Integration

By using term-wm primitives, your application gains:

• Standardized focus cycles.
• Z-ordering for floating components.
• A pre-built "Command Palette" pattern for global actions.

Build & Installation

Requirements

• If building from source: Rust toolchain (stable)
• A terminal emulator supporting Raw Mode and standard ANSI escape sequences (most terminal emulators support this including Windows 11 Command Prompt, macOS, and Ubuntu).

Building from Source

git clone https://github.com/jzombie/term-wm.git
cd term-wm
cargo build --release

There is also a published Rust crate at: https://crates.io/crates/term-wm

Running from Source

The easiest way to run the latest build is via Cargo, which handles platform differences automatically:

cargo run --release

Installing from Source

To install term-wm as an executable system command, you can install it directly to your system.

cargo install --path .

To uninstall:

cargo uninstall term-wm

Performance & Benchmarking

The project emphasizes high-throughput rendering. Included in the repository is term-bench, a tool designed to stress-test terminal emulators and window managers.

1. Standalone (Native Terminal Performance)

cargo run -p term-bench --release -- --duration 15 --fps 120

2. Managed (Inside term-wm) This launches the window manager and immediately feeds the benchmark into the first pane.

cargo run --release -- "./target/release/term-bench --duration 15 --fps 120"

The benchmark reports frame pacing, render times (avg/1% lows), and cell-update throughput.

License

term-wm is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.