bmux
Build and TestA Rust terminal multiplexer and reusable terminal UI framework.
bmux combines server-backed terminal sessions with independent client views, modal interaction, typed plugin services, and composable themes. The UI framework can also be used without the multiplexer.
Early alpha. APIs, configuration, and terminal compatibility are evolving. Source installation is the supported path described here. Package-release workflows exist, but npm/package-server availability must not be inferred from those workflows.
Capabilities
- Persistent server-backed sessions and multi-client views.
- Plugin-owned session, window, workspace, permission, and command behavior.
- A domain-neutral TUI framework with layout, painting, input, selection, damage tracking, and reusable controls.
- Additive theme stacks, mode-aware overlays, and plugin-owned interactive components.
- Kitty, Sixel, and iTerm2 image handling, subject to host-terminal support and implemented protocol operations.
- Remote connections, recording/export, and runtime diagnostics.
Installation
Install Git, Nix, and a native build toolchain. macOS and Linux are primary terminal environments; the repository also contains Windows support and platform-specific release configuration. A release target is not a guarantee of identical behavior on every terminal/OS combination.
git clone https://github.com/BSteffaniak/bmux.git
cd bmux
nix develop
cargo build --locked --release -p bmux_cli --bin bmux
"$CARGO_TARGET_DIR/release/bmux" --help
"$CARGO_TARGET_DIR/release/bmux"
On Windows, use target\release\bmux.exe. Use the built binary’s full path, or add its directory to PATH before using the examples below.
Current CLI Workflow
Running without a subcommand starts or reuses a local server, creates a session when needed, and attaches.
bmux new-session dev
bmux list-sessions
bmux attach dev
Inside an attached session, bmux detach disconnects the client without intentionally terminating the session. Read configuration profiles for modal and tmux-compatible interaction rather than assuming another multiplexer’s keybindings.
Architecture
| Layer | Responsibility |
| bmux_tui | Domain-neutral geometry, layout, paint, scenes, and terminal presentation primitives |
| bmux_tui_components | Reusable controls with caller-owned state |
| bmux_tui_runtime | Scheduling, events, and presentation lifecycle |
| Plugin APIs and services | Typed product behavior and extension contracts |
| Theme plugin | Theme selection and composition |
| Image handling | Protocol interception, storage, and presentation |
Read the TUI framework guide for reusable APIs and ownership boundaries. Sessions surviving client disconnects do not imply that arbitrary foreground processes survive a machine restart.
Documentation
- CLI workflows and advanced examples
- Concepts and configuration profiles
- Plugins and window presentation
- Images and compression
- Operations and testing
Remote gateways and login startup are opt-in operations. Review their network exposure and supervision behavior before enabling them. Do not copy gateway examples into an internet-facing deployment without appropriate access controls.
Development
cargo fmt
cargo check -p bmux_cli
cargo test -p bmux_cli
For code changes, follow AGENTS.md: warning-free clippy, the nextest suite, dependency checks, and relevant PTY/compatibility tests. Docs-only changes use link, Markdown, and documentation-snippet checks. Report the platform and terminal alongside non-sensitive reproductions in GitHub Issues.
Native plugins are trusted code, not sandboxed extensions. Report security-sensitive issues privately to [email protected], without credentials or private recordings. No response-time guarantee is implied.
License
Mozilla Public License 2.0. Bundled fonts retain their upstream licenses.