Maxmux

Maxmux is the crossterm terminal UI built on the same Monolex headless engine and PTY daemon used by other Monolex clients. It adds project selection, tabs, a file-tree sidebar, an @ prompt box, configurable key bindings, and a local control socket without taking ownership of PTY emulation itself. Published contract: maxmux 0.2.3, OpenCLIs build 2026-06-30-100934. The executing binary, registry, and public CDN metadata agree on this release.

Quick Start

openclis install maxmux

maxmux --version
maxmux                 # choose a project and provider
maxmux --plain         # start a plain shell directly
maxmux ctl status      # inspect the newest running instance

Complete Command Reference

The root parser has four operational families (run, ctl, config, and test), help/version aliases, and two launch flags. No-argument execution is intentionally interactive.

Command	What it does	Important controls or effect
`maxmux`	Opens the project/provider selector and then the terminal UI.	Interactive terminal process.
`maxmux --plain`	Skips project selection and starts the default shell.	Interactive terminal process.
`maxmux --ansi [path]`	Records raw PTY escape sequences for rendering diagnosis.	Writes the selected path; default is `/tmp/maxmux-ansi.log`.
`ctl status`	Reports dimensions, tabs, and instance identity.	Read-only; auto-discovers the newest live socket.
`ctl tabs`	Lists all tabs in the selected instance.	Read-only.
`ctl read [query]`	Reads the active rendered screen, optionally from the last prompt match.	Read-only extraction from the current grid.
`ctl run <command>`	Sends a command plus Enter to the active PTY.	Executes in the terminal session; bypasses UI key bindings.
`ctl write <text>`	Sends raw text without Enter.	PTY mutation; bypasses UI key bindings.
`ctl ctrl-c`	Sends `Ctrl+C` to the active PTY.	Interrupts the foreground process.
`config`	Opens the settings TUI.	Currently manages shell aliases; settings surface will expand independently.
`test`	Runs the complete PTY-driven UI self-test.	Spawns a new isolated Maxmux instance and exercises eight checks.
`test spawn`	Starts Maxmux in a real PTY and dumps the initial screen.	Diagnostic process.
`test key <key>`	Sends a real keyboard event such as `@`, `tab`, `esc`, or `ctrl+b`.	Tests the crossterm event and key-binding layers, unlike `ctl`.
`test help`	Prints the self-test command contract.	Read-only.
`help`, `-h`, `--help`	Prints the bundled Maxmux guide.	Read-only.
`version`, `-V`, `--version`	Prints `maxmux 0.2.3`.	Read-only installed-payload proof.

Unknown root arguments are not rejected: after known command/flag parsing they fall through to interactive launch. For automation, use only the documented forms and never treat a guessed option as a harmless help probe.

`ctl` Wrapper Contract

maxmux ctl exposes six convenient commands plus its help branch. It scans the Maxmux socket directory, removes sockets whose PID is no longer live, and picks the highest live PID as the newest instance.

Wrapper	Request sent	Output and failure boundary
`ctl status`	`status`	One JSON object with dimensions, tab count/index, and socket path; exits non-zero when no instance exists.
`ctl tabs`	`tab-list`	Human-readable rows with index, name, session id, and active marker.
`ctl read [query]`	`tab-list`, then `extract-md`	Prints the active screen from the last query match; default `%`, use `$` for Bash.
`ctl run <command>`	`tab-list`, then `write`	Joins remaining arguments, appends carriage return, and executes in the active PTY.
`ctl write <text>`	`tab-list`, then `write`	Sends joined text without Enter and prints the raw response.
`ctl ctrl-c`	`tab-list`, then `write`	Sends byte `0x03` and prints `ok`.
`ctl help`	none	Prints the wrapper contract without requiring a live instance.

ctl run, write, and ctrl-c mutate the selected terminal. ctl is Unix only because version 0.2.3 has no Windows named-pipe implementation.

Complete Self-Test Surface

The test parser contains more diagnostics than its current fallback help text shows:

Command	What it verifies	Side effects or cost
`test`, `test auto`, `test all`	Full automated PTY suite.	Spawns isolated Maxmux/PTY processes.
`test spawn`, `test run`	Starts a 100×30 instance and dumps its rendered screen.	May wait up to 90 seconds for startup.
`test key [key]`	Sends one real key; default is `enter`.	Spawns an isolated interactive instance.
`test mouse`	Injects SGR right-click events until the context menu renders.	Long-running diagnostic with repeated mouse input.
`test ghost`	Runs the `>> … <<` Codex bridge and proves spinner/result injection.	Can invoke Codex, consume provider quota, and wait for a remote result.
`test dspace`	Proves double-space inline-ghost acceptance.	Temporarily writes a sentinel to the OnIt autocomplete DB, then removes it.
`test ghostopen`	Proves double-space opens and closes the ghost box.	Spawns an isolated instance; no model call is required.

The 0.2.3 test help fallback is mislabeled monoterm test and lists only auto, spawn, key, and ghost. That output is a known help defect, not the complete parser. The test harness is Unix-only; Windows returns an unsupported error before spawning it.

Raw Control Socket Protocol

Advanced companions can send newline-delimited JSON directly. The shared protocol recognizes 11 message types:

Type	Required data	Current 0.2.3 behavior
`status`	none	Returns TUI dimensions, tab count/index, and socket.
`tab-list`	none	Returns tab rows.
`tab-new`	none	Parsed, but currently returns `command requires mutable state`; use `Ctrl+T`.
`tab-switch`	`index`	Parsed, but currently returns the same mutable-state error; use a key binding.
`tab-close`	`index`	Parsed, but currently returns the same mutable-state error; use `Ctrl+W`.
`session-list`	none	Returns Headless session ids.
`write`	`sessionId`, `data`	Writes bytes to one PTY.
`extract-md`	`sessionId`, optional `query`	Returns rendered terminal content as Markdown or `null`.
`simulate-key`	`key`	Resolves the key-binding layer; non-blocking navigation/actions and PTY sequences are supported.
`command-list`	none	Returns the nine request/response commands advertised by the TUI.
`subscribe-pty`	optional `sessionId`	Switches the connection to a long-lived `pty-data` stream after a `subscribed` acknowledgement.

command-list omits the streaming-only subscribe-pty and the separately handled simulate-key. It also advertises the three tab mutations that still return the mutable-state error, so discovery output is not execution proof.

Interactive Controls

Context	Keys	Action
Terminal	`Ctrl+T`, `Ctrl+W`	Create or close a tab.
Terminal	`Ctrl+N` / `Ctrl+P`, `Alt+1`…`Alt+9`	Move between tabs.
Terminal	`Ctrl+K`	Open the Spotlight palette for files, tabs, and slash commands.
Terminal	`Ctrl+B`	Toggle the sidebar.
Terminal	`Ctrl+R`	Rename the tab through NIIA Work On It.
Terminal	`@`	Open the prompt box and file-tree sidebar.
Prompt	`Tab`, `Enter`, `Esc`	Move to the tree, send the prompt, or close the overlay.
File tree	`j/k`, arrows, `/`, `Enter`	Navigate, filter, insert a file path, or expand a folder.
Global	`Ctrl+Q`	Quit Maxmux.

Bindings are configurable at ~/Library/Application Support/Monolex/keybindings.json. The control protocol uses newline-delimited JSON over ~/Library/Application Support/Monolex/runtime/sockets/maxmux/control-{PID}.sock.

Published Platforms

Version 0.2.3 ships darwin-aarch64, linux-x86_64, linux-aarch64, and windows-x86_64 archives. Interactive Maxmux can be distributed on all four; ctl and test remain Unix-only in this release. A Windows archive therefore does not imply control-socket or PTY-harness parity.

Runtime Boundary

Maxmux UI and key bindings
          ↓
Monolex headless AtomicState and GridUpdate
          ↓
Monolex PTY daemon and Alacritty VTE
          ↓
shell or AI CLI process

ctl proves socket-level control of an already running instance. test proves keyboard-level behavior in a newly spawned PTY. Neither result alone proves the other surface.

Relationships

Tool	Ownership
Monolex Headless	Owns the headless session and atomic rendered state beneath Maxmux
Monolex PTY Daemon	Owns PTY processes, VTE state, and the daemon control socket
Monopty	Scriptable headless PTY workflows; Maxmux is the human-facing full-screen client
MonoTerm	Related terminal client with a distinct UI and command surface
Monobrain	Reference companion that observes PTY output and injects through the Maxmux control surface

Get Started

Articles

So Anthropic

User Guide

Philosophy

Applied Philosophy

Architecture

Gestalt Color

Transparency

Terminal Core

Features

VariableMD

Research

CodexMono

OpenCLIs

vpncli

MonoSurf

AI-CLIs

Quick Start

Complete Command Reference

`ctl` Wrapper Contract

Complete Self-Test Surface

Raw Control Socket Protocol

Interactive Controls

Published Platforms

Runtime Boundary

Relationships

​Quick Start

​Complete Command Reference

​ctl Wrapper Contract

​Complete Self-Test Surface

​Raw Control Socket Protocol

​Interactive Controls

​Published Platforms

​Runtime Boundary

​Relationships

Quick Start

Complete Command Reference

`ctl` Wrapper Contract

Complete Self-Test Surface

Raw Control Socket Protocol

Interactive Controls

Published Platforms

Runtime Boundary

Relationships