> ## 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. # MonoTerm > AI terminal inside your terminal — sidebar, tabs, PTY engine, virtual cursor tracking. ## What is MonoTerm? MonoTerm is Monolex's terminal-in-terminal. It wraps the same headless PTY engine that powers the Monolex desktop app, but renders directly to your existing terminal via crossterm — no Electron, no WebView, no GUI. *Published contract: `monoterm 0.4.17`, OpenCLIs build `2026-07-15-163247`. The executing binary, registry, and public CDN metadata agree on this release.* ``` ┌───────────────────────────────────────────────────────────────────┐ │ Your Terminal (iTerm, Wezterm, Terminal.app, etc.) │ │ │ │ ┌───────────────┬─┬─────────────────────────────────────────┐ │ │ │ Sidebar │││ PTY Main Area │ │ │ │ │││ │ │ │ │ PROJECT │││ macbook@NIIA ~ % claude │ │ │ │ claude │││ ╭────────────────────────────────────╮ │ │ │ │ ─────────── │││ │ Claude Code │ │ │ │ │ TABS │││ │ │ │ │ │ │ ● Agent-1 │││ │ > how can I help?█ │ │ │ │ │ Agent-2 │││ │ │ │ │ │ │ │││ ╰────────────────────────────────────╯ │ │ │ │ FILES │││ │ │ │ │ ▶ src/ │││ │ │ │ │ .env │││ │ │ │ │ │││ │ │ │ │ ACTIVITY │││ │ │ │ │ read main │││ │ │ │ │ bash cargo │││ │ │ │ ├───────────────┴─┴─────────────────────────────────────────┤ │ │ │ claude │ ● Agent-1 ^T:new ^N/P:tab ^B:sidebar ^Q:quit │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────┘ ``` ## Install ```bash theme={null} # Via OpenCLIs openclis install monoterm ``` ## Quick Start ```bash theme={null} # Launch with project selector (Where & With) monoterm # Launch plain shell (skip selector) monoterm --plain # Show all commands and keybindings monoterm --help # Run the real-PTY self-test suite (macOS/Linux) monoterm test ``` ## Platform Availability | Surface | macOS arm64 | Linux x86\_64 | Linux arm64 | Windows x86\_64 | | ------------------------------------------------- | ----------: | ------------: | ----------: | --------------: | | Interactive TUI (`monoterm`, `--plain`, `--ansi`) | Yes | Yes | Yes | Yes | | Live-instance control (`monoterm ctl ...`) | Yes | Yes | Yes | No | | PTY self-test (`monoterm test ...`) | Yes | Yes | Yes | No | The exact published targets are `darwin-aarch64`, `linux-x86_64`, `linux-aarch64`, and `windows-x86_64`. There is no Intel macOS or Windows Arm artifact in this release. `ctl` uses a Unix domain socket and `test` uses Unix PTY primitives, so both command families fail closed on Windows until named-pipe and ConPTY transports are implemented. ## Complete CLI Reference | Command | What it does | Effect or proof boundary | | ----------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `monoterm` | Opens the Where & With selector, then the terminal UI. | Interactive process. | | `monoterm --plain` | Skips selection and starts a plain shell. | Interactive process. | | `monoterm --ansi [path]` | Records raw PTY escape sequences. | Writes the selected path; without one, uses `monoterm-ansi.log` in the OS temporary directory. | | `monoterm ctl` / `help` / `-h` / `--help` | Shows every live-control command. No subcommand also selects help. | Read-only; available without a live instance. | | `monoterm ctl status` | Shows dimensions, tabs, and instance identity. | Read-only socket query against the newest live instance; macOS/Linux only. | | `monoterm ctl tabs` | Lists all tabs. | Read-only; macOS/Linux only. | | `monoterm ctl read [query]` | Reads the active screen, optionally from the last query or prompt match. | Read-only current-grid extraction; defaults to `%`; macOS/Linux only. | | `monoterm ctl run ` | Sends a command plus Enter to the active tab. | Executes in the PTY and bypasses UI key bindings; macOS/Linux only. | | `monoterm ctl write ` | Sends raw text without Enter. | PTY mutation that bypasses UI key bindings; macOS/Linux only. | | `monoterm ctl ctrl-c` | Sends `Ctrl+C`. | Interrupts the active foreground process; macOS/Linux only. | | `monoterm test [auto\|all]` | Runs all 28 checks across 16 sections. `auto` and `all` are aliases for the default. | Spawns a new instance and exercises keyboard, control-socket, PTY-stream, and palette paths; macOS/Linux only. | | `monoterm test spawn\|run` | Spawns a fresh PTY and dumps its initial screen. | Diagnostic aliases; macOS/Linux only. | | `monoterm test key ` | Sends one real event such as `@`, `tab`, `esc`, `enter`, `j`, `k`, an arrow, `ctrl+b`, or text. | Keyboard-level UI verification; macOS/Linux only. | | `monoterm test mouse` | Injects SGR right-click bytes and checks that MonoTerm renders the menu. | Separates the MonoTerm mouse parser from host-terminal forwarding; macOS/Linux only. | | `monoterm test help` / `-h` / `--help` | Shows test subcommands and aliases. | Read-only. | | `help` / `--help` / `-h` | Prints the embedded guide. | Read-only. | | `version` / `--version` / `-V` | Prints the payload version. | Read-only. | The control socket uses newline-delimited JSON at `~/Library/Application Support/Monolex/runtime/sockets/monoterm/control-{PID}.sock`. It discovers the newest live process and cleans stale sockets. `ctl` and `test` prove different layers: `ctl` drives an existing PTY directly, while `test` sends keyboard events through a newly spawned UI and also verifies selected control-socket and PTY-stream paths. ## Raw Socket Protocol: 11 Parsed Messages The six `monoterm ctl` commands are the stable shell wrapper. Integrations can also send raw newline-delimited JSON. The `0.4.17` parser recognizes exactly 11 message types: | Message | Current behavior | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | Returns dimensions, active tab, tab count, and socket path. | | `tab-list` | Returns tab labels and active markers. In this payload, every row's `sessionId` repeats the active session ID; use `session-list` for session identity. | | `tab-new` | Parsed, then fails closed with `command requires mutable state — use keybindings`. | | `tab-switch` | Parsed with `index`, then fails closed with the same mutable-state error. | | `tab-close` | Parsed with `index`, then fails closed with the same mutable-state error. | | `session-list` | Returns the headless manager's real PTY session inventory. | | `write` | Writes `data` to a selected `sessionId`. | | `extract-md` | Extracts the selected session grid from an optional query as Markdown. | | `simulate-key` | Executes PTY-byte mappings and the non-blocking sidebar/next-tab/previous-tab actions. Blocking prompt/new-tab actions are acknowledged but not executed. | | `command-list` | Returns nine advertised requests. It omits `simulate-key` and `subscribe-pty` while still listing the three fail-closed tab mutations, so it is not a capability proof. | | `subscribe-pty` | Switches the connection to a long-lived `subscribed` / `pty-data` event stream, optionally filtered by `sessionId`. | This distinction matters for automation: the parser accepting a message is not the same as the current TUI implementing its mutation. The 28-check harness proves `status`, `tab-list`, `write`, and `subscribe-pty`; it does not turn the three fail-closed tab messages into working commands. ## Keybindings Default keybindings, configurable via JSON: | Key | Action | | ------------------- | ------------------------------------------------------------------------ | | `Ctrl+T` | New tab (project selector) | | `Ctrl+W` | Close tab | | `Ctrl+N` / `Ctrl+P` | Next / Previous tab | | `Ctrl+]` / `Ctrl+[` | Next / Previous tab (Kitty protocol is needed for `[` in some terminals) | | `Ctrl+K` | Spotlight palette for files, tabs, and slash commands | | `Ctrl+B` | Toggle sidebar | | `Ctrl+R` | Rename tab | | `Ctrl+Q` | Quit | | `Alt+1~9` | Go to tab by number | | `@` | Open prompt box with file-tree sidebar | | `Alt+Backspace` | Delete word backward | | `Alt+Left/Right` | Move word backward/forward | Override via `~/Library/Application Support/Monolex/keybindings.json`: ```json theme={null} { "actions": { "ctrl+shift+t": "new_tab", "ctrl+shift+w": "close_tab" }, "pty": { "alt+backspace": "\\e\\x7f" } } ``` ## Architecture MonoTerm does not implement a terminal emulator. It wraps the Monolex headless engine — the same Alacritty VTE parser, AtomicState diff engine, and PTY daemon that power the desktop app. ``` monoterm (binary) ├── lib-keybinding → Key event → Action or PTY bytes ├── monolex-headless → Session management, GridUpdate engine │ ├── lib-atomic-renderer → AtomicState, XtermCell, DiffHint │ └── lib-pty-client → PTY daemon communication └── crossterm → Terminal rendering (no GUI) ``` ### What MonoTerm adds over raw headless: | Feature | Headless | MonoTerm | | -------------- | ---------------------- | ------------------------------ | | PTY session | Yes | Yes + multi-tab | | Grid rendering | GridUpdate JSON/binary | crossterm to host terminal | | Sidebar | No | File tree, tabs, activity | | IME support | inverse\_cursor field | Virtual cursor tracking + hold | | Resize | Grid worker only | Grid + PTY daemon (SIGWINCH) | | Keybindings | N/A | Configurable JSON | | Self-test | N/A | `monoterm test` (PTY harness) | ## Virtual Cursor & IME When apps like Claude Code hide the real cursor and draw their own using INVERSE video (`\x1b[7m`), MonoTerm detects the virtual cursor position from the AtomicState layer and places the host terminal's cursor there. This ensures the parent terminal's IME (Korean, Japanese, Chinese input) composition window appears at the correct position — where the user is actually editing, not where the hidden real cursor is. The detection uses the same algorithm as the Monolex desktop app: * Scan for INVERSE cells on the cursor row first (avoid false positives) * Fall back to bottom-up scan * Hold position during Ink erase-redraw cycles (6 frames) * Distance check to discard false positives (zsh % marker, status bars) ## PTY Harness MonoTerm includes a built-in test system that exercises the headless engine through a real test PTY without requiring a human-operated terminal: ```text theme={null} $ monoterm test --- 1. Startup --- PASS TABS sidebar PASS shell tab listed ... --- 16. Spotlight palette --- PASS palette opens PASS filter shows /tabs PASS palette dismissed ================== 28/28 passed ``` The 28 checks are grouped into 16 ordered sections: startup, shell, prompt box, tree focus, tree search, prompt focus, prompt input, prompt close, sidebar hide and restore, new-tab dialog, dialog cancellation, `ctl status`, `ctl tabs`, `ctl write`, PTY subscription, and the Spotlight palette. Screen assertions poll until the required state appears instead of treating one fixed-delay snapshot as proof. ## Source MonoTerm is released through OpenCLIs from the public Monolex repository under `tauri-apps/app-monoterm`. A source build, an installed OpenCLIs payload, and a passing PTY harness are separate proof layers. ## Relationships | Tool | Ownership | | ------------------------------------------------- | ------------------------------------------------------------------------------ | | [Monolex Headless](/ai-clis/monolex-headless) | Owns session lifecycle and rendered AtomicState beneath MonoTerm | | [Monolex PTY Daemon](/ai-clis/monolex-pty-daemon) | Owns terminal processes, VTE state, and scrollback | | [Maxmux](/ai-clis/maxmux) | Related terminal multiplexer with a separate package and settings surface | | [MonoTree](/ai-clis/monotree) | Shares file-tree foundations while remaining a standalone browser | | [MonoBrain](/ai-clis/monobrain) | Reference reactive companion for the raw `subscribe-pty` and injection surface |