> ## 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. # Monopty > Create, drive, observe, guard, and test local Monolex headless PTY sessions from scripts and AI agents. Monopty is the local automation CLI for Monolex headless PTY sessions. It combines raw terminal control with bounded screen, history, and system-output extractors, then builds guarded prompts, structured steps, scenarios, and end-to-end health checks on top. *Published contract: `monopty 0.2.6`, OpenCLIs build `2026-07-16-174051`, source commit `47145fce2d7cf4f17fc6523481f6b596dbdcf574`. The macOS archive has SHA-256 `ba5c3d64808da8cba2a6ef7d26df5bceeb939a1c2ab79409c0da5b03dcfb79f5`; the installed executable has SHA-256 `3a2f0abae6892be827320ba2cf96c1bb7b8157355f0fb5ae5dcc012c60d8a1b4`.* *Registry ownership: the canonical `docs_url` is this page, the public product homepage is `https://monolex.ai`, and Monopty pairs with Monolex Headless, Monolex PTY Daemon, MonoTerm, and Monosystem. Repository ownership remains `monolex/monolex`; no public source URL is advertised while that repository is private.* ## Quick Start ```bash theme={null} openclis install monolex-headless openclis install monolex-pty-daemon openclis install monopty monolex-headless --local-only & monopty health monopty new --json ``` Version 0.2.6 exposes 22 operational root commands plus Clap's generated `help` command. `claude` contains three aliases. It is an OpenCLIs-distributed CLI with `initiate.md` and `SKILL.md`; it does not expose an MCP schema command. ## Global Options | Option | Contract | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | `--json` | Emits machine-readable stdout where the selected command supports it. Guidance and diagnostics remain on stderr. | | `--socket ` | Selects one control socket instead of auto-discovery. | | `--include-app` | Includes desktop-app control sockets. The default searches local headless sockets only. | | `-h`, `--help` | Prints root or per-command help without running the command. | | `-V`, `--version` | Prints the executing binary version. | Use explicit session ids and sockets in unattended jobs. Auto-discovery is convenient for one healthy local instance, but a stale or second owner is a diagnosis problem and must not be guessed away. ## Discovery, Health, and Raw Control | Invocation | What it does | Options, defaults, and effect | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sockets` | Lists live local control sockets. | Read-only discovery. | | `sessions [--session ]` | Lists rendered sessions, selected socket, owner PID, connection mode, liveness verdict, and idle time. | Read-only; a `LIVE` session is drivable, not proof that an answer is complete. | | `health [--session ]` | Aggregates session count, instance count, and `healthily_drivable`; reports stale or multi-owner conditions. | Read-only control-plane diagnosis. | | `ledger [--tail ]` | Reads prior Monopty operation records. | Default tail: `20`. Historical audit evidence is not current liveness. | | `new [--cols ] [--rows ] [--cwd ] [--initial ] [--no-wait]` | Creates a PTY session through headless. | Defaults: `120×40`; waits for the initial command unless `--no-wait` is set. Mutates process/session state. | | `close ` | Sends Headless's local `tab-close` request and retires one session. | With current Headless 0.1.45 and PTY Daemon 0.2.8, first terminates and reaps the PTY-owned shell and foreground process group, then removes daemon, Headless, and heartbeat rows. A teardown rejection is returned as an error and remains visible for retry. The operation is idempotent when already gone; human output is `closed ` and `--json` returns `ok`, `session`, `closed`, and `socket`. | | `write [--force]` | Sends raw bytes to a session. | Decodes `\r`, `\n`, `\t`, `\x03`, and `\e`. `--force` bypasses stale or ambiguous health refusal. | | `wait [--idle-ms ] [--max-wait ]` | Waits until rendered output remains idle. | Defaults: `500 ms` idle, `30 s` maximum. Idle is timing evidence only; an interactive prompt may still await input. | ## Four Read Sources | Invocation | Evidence source | Controls and best use | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `answer ` | `extract-md`, anchored at the last query match | Completed command/model response after a known prompt. It reports source-selection diagnostics on stderr. | | `screen [--full] [--force]` | Current backend `AtomicState` terminal grid | Visible viewport by default; `terminal` is an alias. `--full` includes scrollback for compatibility/debugging. | | `history [--tail ] [--around ] [--context ] [--force]` | Full terminal source reduced to a bounded view | Defaults: tail `80`, context `8`. Use for output that has scrolled beyond the viewport. | | `system --cli --transcript [--session ]` | CLI-owned transcript or output file through `niia get-answer-system` | Use when the provider's authoritative answer is outside the terminal grid. The optional session id adds ledger symmetry. | The corresponding wait/assert commands keep these sources separate: | Invocation | Success contract | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `expect-screen [--max-wait ] [--full] [--show] [--force]` | Polls the viewport/full screen until text appears. Default timeout: `120 s`; `--show` includes content after success. | | `expect-history [--max-wait ] [--tail ] [--context ] [--show] [--force]` | Polls full history but returns compact match metadata unless `--show` is set. Defaults: `120 s`, tail `80`, context `8`. | | `expect-system --cli --transcript [--session ] [--max-wait ] [--show]` | Polls the parsed system answer. Default timeout: `120 s`. | Do not collapse `answer`, `screen`, `history`, and `system` into one generic “terminal result.” They answer different questions: completed response, visible interaction state, scrollback history, and provider-owned output. ## Prompt and Structured Workflow Commands | Invocation | What it does | Guard, defaults, and effect | | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ask [--query ] [--idle-ms ] [--max-wait ] [--force]` | Writes the prompt, submits it, and polls `extract-md`. | Defaults: query from a prompt prefix, `500 ms` idle, `120 s` maximum. `--force` bypasses health refusal. | | `follow-up [--expect-last ] [--query ] [--idle-ms ] [--max-wait ] [--force]` | Continues one session. | `--expect-last` makes the prior-answer guard explicit. `--force` permits continuation when that guard or health check cannot be confirmed. | | `step --send --expect [OPTIONS]` | Executes one structured write/expect unit. | Repeatable `--guard` and `--cleanup`; `--mode shell\|claude` defaults to `shell`; `--read answer\|history\|screen\|terminal\|system` defaults to `answer`; timeout defaults to `120 s`. | | `scenario [--session ] [--cwd ] [--mode shell\|claude] [--keep]` | Executes ordered structured steps from a file or stdin. | Without `--session`, creates a `120×40` shell in `/tmp`; sends `exit\r` after success unless `--keep` is set. Existing sessions are never auto-exited. | `step` also accepts `--screen-full`, `--history-tail ` (default `80`), `--history-context ` (default `8`), `--system-cli `, `--system-transcript `, `--show`, repeatable `--guard`/`--cleanup`, and `--force`. Scenario records carry the same core fields: `name`, `send`, `expect`, `guard`, `cleanup`, `mode`, `read`, `screen_full`, `history_tail`, `history_context`, `system_cli`, `system_transcript`, `max_wait`, and `force`. Execution stops at the first unmet guard, timeout, or failed read contract. An auto-created scenario still sends `exit\r` after success unless `--keep` is set; use `close` afterward when the exited shell must also disappear from daemon and session inventories. ### Claude aliases | Invocation | Contract | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `claude start [--cols ] [--rows ] [--cwd ] [--command ] [--accept]` | Creates a normal shell session, then writes the Claude launch command. Defaults: `120×40`, command `claude`. `--accept` sends Enter after settling for trust/update dialogs. | | `claude ask [ask options]` | Uses the same ask/extract primitives with Claude submit retries. | | `claude follow-up [follow-up options]` | Uses the same optional previous-answer guard and Claude submit retries. | Claude aliases are not a separate transport. Use an explicit `--query` whose expected answer text is not already visible in the prompt composer; prompt echo is not completion proof. ## Test and Development Commands | Invocation | Work performed | Important boundary | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `test [--loops ] [--cwd ] [--claude-version] [--claude-interactive] [--keep]` | Creates, drives, reads, and normally exits real local PTY sessions. | Defaults: one loop in `/tmp`. `--claude-interactive` sends a real model prompt and can consume quota; `--keep` leaves test shells alive. | | `dev-loop [--loops ] [--skip-fmt] [--skip-check] [--skip-test] [--skip-build] [--skip-scenario] [--claude-version] [--claude-interactive]` | Runs the source-tree gate: format, check, tests, build, structured scenario, and PTY smoke. | Default loops: `3`. It can format source and create build artifacts; it is not proof of the installed or CDN payload. | | `help [COMMAND]` | Prints generated root or subcommand help. | Read-only discovery. | ## Output Channels and Dynamic Guidance Successful commands may print one dim `[NEXT] ...` breadcrumb to stderr. Machine JSON remains isolated on stdout, while routing provenance and `NOT_ATTACHED`, `NO_SETTLE`, `MULTI_OWNER`, or `STALE_GRID` diagnostics remain on stderr. Some 0.2.6 `[NEXT]` breadcrumbs still render `ask` and `follow-up` with legacy `--session` / `--prompt` spellings. The executable parser requires positional ` ` arguments. Treat those breadcrumbs as workflow direction and use the invocations documented on this page. `answer` owner-targets the live session owner and uses the freshest renderer when no live owner exists; it does not silently choose a stale mirror. A successful `sockets`, `sessions`, or `health --json` call therefore has clean JSON stdout and a separate `[NEXT]` stderr line. ## Reliable Automation Pattern ```bash theme={null} monopty health --json monopty scenario ./review-flow.jsonl --json monopty ledger --json ``` ## Release Provenance Version 0.2.5 made the executable `close` verb public, but its initial macOS publication preceded the version commit and the packaged discovery guide did not list the new command. Version 0.2.6 supersedes it from clean commit `47145fce2d7cf4f17fc6523481f6b596dbdcf574`, with `source_dirty: false`. Its packaged `initiate.md`, installed guide, and public OpenCLIs `initiate_md` remain byte-identical at SHA-256 `de8f892939ba7b60c1d2ac4da5bfe7290ab64c39a89b99ba78f1e9ba0da46eeb`. Current repository commit `0da9e2bc67543abee6ddbed37f3d67af714dedf4` does not add a Monopty command. It strengthens the guide to reflect the newer server-side close contract: acknowledgement comes only after the owned process tree is gone, and a failed teardown stays visible for retry. The current source guide has SHA-256 `6495d665ae1d6843957dd39858a71556d50a3248daa33443a9b4dd7baae2e0b2`; its SKILL has SHA-256 `82fc51dcf7987d5017110f32fa43c994c7cf9241ef1678f7cbc623974a96c93e`. The installed release SKILL remains `fa2689f70696c4568337858872e20e8f4a482b836d40d0ee2e26236b87766262`. This is a guide/protocol-stack split, not a claim that a new Monopty binary was published. | Public platform | CDN archive SHA-256 | Current proof | | ----------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `darwin-aarch64` | `ba5c3d64808da8cba2a6ef7d26df5bceeb939a1c2ab79409c0da5b03dcfb79f5` | Published, Developer ID signed, Apple notarized, directly installed and executed | | `linux-x86_64` | `8abd46872b108950b3414c72389ebb4e832f065f4e76a0fafed0a43fa303e071` | Directly downloaded and executed in Ubuntu 24.04 WSL; `health --json` reached the live Headless owner and returned `ok: true` | | `linux-aarch64` | `699b4d4fd5b61f74bd6a7119b14da31a52c2ab4b0ecfdd1999ecaef542add63e` | Directly downloaded and hash-verified; the extracted payload is an AArch64 GNU/Linux ELF | | `windows-x86_64` | `a58d0549d49ffbc847d5ee552b27a523442cb0f88d4eacbd1549ad0e7a70c31d` | Directly downloaded and executed on Windows as 0.2.6; `health --json` correctly failed because no native Headless control socket was live | | `windows-aarch64` | `7cd04e4b3b23262148c725aa574146be76e8d5b96373802ae42bb8db30b112eb` | Directly downloaded and hash-verified; the extracted payload is a Windows AArch64 PE executable | The OpenCLIs-managed macOS executable has SHA-256 `3a2f0abae6892be827320ba2cf96c1bb7b8157355f0fb5ae5dcc012c60d8a1b4`. An isolated local runtime smoke paired it with Headless 0.1.43 and PTY Daemon 0.2.5, created a session, observed the exited shell as `shell=dead`, closed it with a structured `closed: true` result, confirmed an empty session list, and repeated `close` successfully to prove the idempotent retirement contract. The retired shell did not remain in Headless as a recoverable ghost. The extracted Linux x86\_64 executable has SHA-256 `604ab4c682a38d80afc17e20cbbb9e292f551c8688e2cdf2f6c2cd0f29033b66`; the Linux AArch64 executable has SHA-256 `116e45cbd659a8746e5711fdf305e3c5452b66d90ca64450337ed0f1d7f96115`. The x86\_64 runtime probe was read-only: it inspected the existing remote Headless estate without creating, writing, or closing a session. The extracted Windows x86\_64 executable has SHA-256 `25ce1f769166b5cc1ef3d7f89a977d223e0d9c10d50e6ec74cf82e1fc3728c77`; the Windows AArch64 executable has SHA-256 `580320ed5839493406faaf12dea4187ebe82d06241a6b914c4986d09136c6afc`. The native Windows health failure is expected runtime evidence, not a release failure: distribution and parser execution succeeded, while the control-plane probe truthfully reported that no native local Headless socket was available. The required platform set remains `darwin-aarch64`, `linux-x86_64`, `linux-aarch64`, `windows-x86_64`, and `windows-aarch64`. All five archives are published and directly hash-verified. Runtime proof still requires the installed binary, a healthy Headless owner, and a live PTY daemon; CDN availability alone proves only distribution. ## Relationships | Tool | Ownership | | ------------------------------------------------- | --------------------------------------------------------------------------------- | | [Monolex Headless](/ai-clis/monolex-headless) | Owns the local control protocol and rendered session lifecycle Monopty drives | | [Monolex PTY Daemon](/ai-clis/monolex-pty-daemon) | Owns child processes, VTE state, grid, and scrollback beneath headless | | [Monosystem](/ai-clis/monosystem) | Extends session control across machines and the gateway rather than local sockets | | [MonoLog](/ai-clis/monolog) | Searches persisted PTY activity; Monopty controls live sessions |