MonoTerm

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

# Via OpenCLIs
openclis install monoterm

Quick Start

# 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 <command>`	Sends a command plus Enter to the active tab.	Executes in the PTY and bypasses UI key bindings; macOS/Linux only.
`monoterm ctl write <text>`	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 <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:

{
  "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:

$ 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	Owns session lifecycle and rendered AtomicState beneath MonoTerm
Monolex PTY Daemon	Owns terminal processes, VTE state, and scrollback
Maxmux	Related terminal multiplexer with a separate package and settings surface
MonoTree	Shares file-tree foundations while remaining a standalone browser
MonoBrain	Reference reactive companion for the raw `subscribe-pty` and injection 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

What is MonoTerm?

Install

Quick Start

Platform Availability

Complete CLI Reference

Raw Socket Protocol: 11 Parsed Messages

Keybindings

Architecture

What MonoTerm adds over raw headless:

Virtual Cursor & IME

PTY Harness

Source

Relationships

​What is MonoTerm?

​Install

​Quick Start

​Platform Availability

​Complete CLI Reference

​Raw Socket Protocol: 11 Parsed Messages

​Keybindings

​Architecture

​What MonoTerm adds over raw headless:

​Virtual Cursor & IME

​PTY Harness

​Source

​Relationships

What is MonoTerm?

Install

Quick Start

Platform Availability

Complete CLI Reference

Raw Socket Protocol: 11 Parsed Messages

Keybindings

Architecture

What MonoTerm adds over raw headless:

Virtual Cursor & IME

PTY Harness

Source

Relationships