> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Maxmux

> Run a full-screen AI terminal multiplexer over the Monolex headless and PTY stack, then control or test it through stable CLI surfaces.

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

```bash theme={null}
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

```text theme={null}
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](/ai-clis/monolex-headless)     | Owns the headless session and atomic rendered state beneath Maxmux                          |
| [Monolex PTY Daemon](/ai-clis/monolex-pty-daemon) | Owns PTY processes, VTE state, and the daemon control socket                                |
| [Monopty](/ai-clis/monopty)                       | Scriptable headless PTY workflows; Maxmux is the human-facing full-screen client            |
| [MonoTerm](/ai-clis/monoterm)                     | Related terminal client with a distinct UI and command surface                              |
| [Monobrain](/ai-clis/monobrain)                   | Reference companion that observes PTY output and injects through the Maxmux control surface |