Create a PTY session with an explicit working directory.

MCP does not provide a standard field for the client's current working directory. The caller must provide cwd explicitly.

Args: session_id: Stable identifier for this PTY session. cwd: Working directory for the session's shell. description: Free-form description of what this session is doing (for humans).

Send one newline-terminated line to a stateful PTY session.

Requires an existing session created via create_session(session_id, cwd).

After sending line + "\n", this drains newly produced PTY bytes until the PTY is silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until deadline_s expires.

deadline_s must be at most 300 seconds.

Common SSH pattern:

• create_session(session_id, cwd)

• send_line(session_id, "ssh host", deadline_s=2)

• wait_for_shell_prompt(session_id, deadline_s=30)

Send raw text to a stateful PTY session without adding a newline.

Requires an existing session created via create_session(session_id, cwd).

After sending text, this drains newly produced PTY bytes until the PTY is silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until deadline_s expires.

deadline_s must be at most 300 seconds.

Send a password plus newline.

Requires an existing session created via create_session(session_id, cwd).

Security model:

• Forces terminal echo off for this send operation (echo=False).

• Disables transcript logging for this send operation (log=False).

• Returns the PTY bytes consumed during this call with best-effort password redaction, prefixed by [password sent].

After sending password + "\n", this drains newly produced PTY bytes until the PTY is silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until deadline_s expires.

deadline_s must be at most 300 seconds.

Send a control character to the terminal.

Requires an existing session created via create_session(session_id, cwd).

Keys:

• c sends Ctrl+C, commonly used to interrupt.

• d sends Ctrl+D (EOF in many programs).

• z sends Ctrl+Z (job control suspend).

• l sends Ctrl+L (clear screen in many shells).

• [ or escape sends ESC.

After sending the control character, this drains newly produced PTY bytes until the PTY is silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until deadline_s expires.

deadline_s must be at most 300 seconds.

Wait for newly arriving PTY output without sending input.

Requires an existing session created via create_session(session_id, cwd).

This waits for new PTY bytes to arrive. After the first new output is observed, it continues draining until the PTY is silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until deadline_s expires.

deadline_s must be at most 300 seconds. If the deadline expires after some output has already been captured, partial output is returned with outcome="deadline_exceeded".

If you need to wait specifically for a shell prompt, use wait_for_shell_prompt().

Get the current VT100-rendered terminal screen snapshot.

Requires an existing session created via create_session(session_id, cwd).

This is a passive snapshot. It does not ingest new PTY bytes.

Get rendered terminal scrollback.

Requires an existing session created via create_session(session_id, cwd).

This is a passive snapshot. It does not ingest new PTY bytes.

Clear rendered scrollback history while preserving current screen.

Requires an existing session created via create_session(session_id, cwd).

Wait for a regex match in rendered text and/or newly arriving PTY bytes.

Requires an existing session created via create_session(session_id, cwd).

This first checks already rendered scrollback, then waits on new PTY output.

deadline_s must be at most 300 seconds.

Wait until a shell prompt is detected.

Requires an existing session created via create_session(session_id, cwd).

This repeatedly ingests new PTY output and re-runs prompt detection until a shell prompt is visible or until deadline_s expires. Any output consumed during that wait is returned in output.

If the remote shell uses a customized prompt that the default heuristics misclassify, set shell_prompt_regex via configure_session(...).

deadline_s must be at most 300 seconds.

Get metadata for an existing PTY session.

Requires an existing session created via create_session(session_id, cwd).

Update session metadata and shell prompt detection.

description is free-form metadata for humans and does not affect execution.

shell_prompt_regex is used by heuristic readiness detection to decide whether the terminal is idle at a shell prompt. It is matched against the last non-empty line of the rendered screen.

This can be called before a session exists; values are stored by session_id and applied when the session is created.

Send an OS signal to the foreground process in a session.

Requires an existing session created via create_session(session_id, cwd).

Get the transcript file path for this session.

Terminate a PTY session. Future calls using the same session_id are rejected.