PTY / Terminal Backend

The PTY (pseudo-terminal) backend provides interactive shell support for Mona. It enables running interactive commands like vim, htop, and npm init that require a real terminal.

Installation

PTY support is included in the [all] install and the [local-office] bundle. If you need it separately:

cd ~/.monoclaw/monoclaw-runtime
uv pip install -e ".[pty]"

This installs:

• ptyprocess on macOS/Linux
• pywinpty on Windows

When to use PTY

PTY is useful when:

• Running interactive terminal programs (vim, less, htop)
• Using commands with colored output and progress bars
• Running npm init or other interactive installers
• Needing real-time terminal feedback

Configuration

PTY is enabled automatically when the terminal backend is set to local or docker:

terminal:
  backend: local
  pty:
    enabled: true
    rows: 24
    cols: 80

Interactive commands

With PTY enabled, Mona can run interactive commands:

Run npm init and create a new package

Mona will:

1. Start npm init in a PTY
2. Answer the interactive prompts
3. Complete the initialization

Terminal size

Adjust the virtual terminal size:

terminal:
  pty:
    rows: 40
    cols: 120

This affects how programs like vim and less render output.

Windows support

On Windows, pywinpty provides PTY functionality using the Windows Pseudo Console API:

terminal:
  pty:
    backend: winpty    # winpty | conpty (Windows 10+)

Limitations

• No GUI programs — PTY supports terminal apps, not GUI apps
• Single session — One PTY per command; no persistent shells between turns
• Input timing — Some interactive programs require careful input timing

Troubleshooting