Skip to main content
Glama
PiloTY
by yiwenlu66

PiloTY

PiloTY (PTY for your AI Copilot) is an MCP server that gives an agent a persistent, interactive terminal.

If you have used Claude Code / Codex to run shell commands, you have probably hit the same wall: tool calls tend to be stateless. Each call starts "fresh", so environment variables disappear, interactive programs cannot be driven reliably, and long-running processes get cut off or orphaned while the agent is thinking.

PiloTY exists to make the agent's terminal behave more like a human's: start something in a real terminal, come back later, and keep going.

Warning: PiloTY exposes unrestricted terminal access. Treat it like giving the agent your keyboard.

What it enables

  • Long-running commands: builds, installs, migrations, test suites. Start once, check output later.

  • Log monitoring: tail -f, journalctl -f, kubectl logs -f, CI logs, service restarts.

  • "Vibe debugging": keep a REPL/debugger open while the agent reads code and tries ideas (python, ipython, pdb).

  • Privileged operations: handle interactive password prompts (sudo, SSH passwords, key passphrases).

  • SSH-based devops: keep a remote login session alive across tool calls; run remote commands in the same shell.

  • Terminal UIs: less, man, top, vim can work, but cursor-heavy programs often require screen snapshots instead of plain text output.

Related MCP server: can-see

Quickstart

PiloTY is meant to be launched by an MCP client over stdio.

Add it to Codex CLI as an MCP server:

codex mcp add piloty -- uvx --from git+https://github.com/yiwenlu66/PiloTY.git piloty

If you prefer SSH-based Git fetch:

codex mcp add piloty -- uvx --from git+ssh://git@github.com/yiwenlu66/PiloTY.git piloty

If you already have a local clone:

codex mcp add piloty -- uv --directory /path/to/PiloTY run piloty

Run the server command directly (without adding it to an MCP client):

uvx --from git+https://github.com/yiwenlu66/PiloTY.git piloty

Mental model

One session is one real interactive terminal that stays alive across tool calls.

  • State persists: cwd, environment variables, foreground process, remote SSH connection, REPL/debugger state.

  • PiloTY tracks both the raw output stream and a rendered screen/scrollback view.

PiloTY keeps two representations:

  • output: incremental text stream (optionally ANSI-stripped)

  • Rendered screen/scrollback: what a human would see in a terminal

Public MCP results separate call outcome from terminal interpretation:

  • outcome: success, deadline_exceeded, eof, error, invalid_session, or terminated

  • terminal_state: best-effort rendered-state classification after the call (running, ready, password, confirm, repl, editor, pager, unknown)

Sessions are addressed by a session_id string. Reusing the same id is what keeps state.

Integration notes (for MCP integrators)

MCP does not expose a standard "client cwd" field, so the first step is always to create a session with an explicit working directory, then reuse the same session_id for subsequent calls.

Typical agent workflow:

  • Create a session (explicit cwd) and reuse the same session_id.

  • Use send_line to submit a newline-terminated command, send_text for raw bytes, and send_control / send_signal for interrupts.

  • Use wait_for_output for temporal PTY output waiting, wait_for_regex for content-based waits, and wait_for_shell_prompt after ssh or similar login flows.

  • Use snapshot_screen / snapshot_scrollback when layout matters. Snapshot tools are passive and do not ingest fresh PTY bytes.

  • If prompt detection is wrong, configure a custom shell-prompt regex.

  • Use send_password for secret entry; terminate the session when done.

For exact tool names, arguments, and return fields, use your MCP client's tool schema or read piloty/mcp_server.py.

Limitations

  • deadline_s is a wall-clock budget. On send/wait tools, it is not "process completion time".

  • Drain-based tools (send_line, send_text, send_control, send_password, send_signal, wait_for_output) stop after the server quiescence policy (PILOTY_QUIESCENCE_MS, default 1000) or when deadline_s expires.

  • wait_for_output can return partial output with outcome=deadline_exceeded if output started but the PTY never went quiet before the deadline.

  • wait_for_regex first checks already-rendered scrollback, then waits on new PTY bytes.

  • wait_for_shell_prompt consumes PTY output while it waits and returns the consumed bytes in output.

  • Terminal-state detection is best-effort and can be wrong (especially for custom prompts and cursor-heavy TUIs).

  • Plain text output can be misleading for full-screen programs; use screen snapshots when layout matters.

  • send_password() suppresses transcript logging and terminal echo for that send. It does not prevent other prompts/programs from echoing secrets later.

  • Quiescence-based output collection can be confused by programs that print periodic noise. Tune with PILOTY_QUIESCENCE_MS (default 1000).

Logs

Each server instance writes session logs under ~/.piloty/:

  • ~/.piloty/servers/<server-instance-id>/sessions/<session-id>/transcript.log: raw PTY bytes (combined stdout/stderr)

  • ~/.piloty/servers/<server-instance-id>/sessions/<session-id>/commands.log: inputs sent (best-effort)

  • ~/.piloty/servers/<server-instance-id>/sessions/<session-id>/interaction.log: inputs plus captured output (best-effort)

  • ~/.piloty/servers/<server-instance-id>/sessions/<session-id>/session.json: metadata snapshot

  • ~/.piloty/active/<server-instance-id>/<session-id>: symlink to the current session directory (when symlinks are supported)

Server logs default to /tmp/piloty.log.

tools/session_viewer.py can inspect sessions:

python tools/session_viewer.py list
python tools/session_viewer.py info <server-instance-id>/<session-id>
python tools/session_viewer.py tail -f <server-instance-id>/<session-id>

Development

Repository layout:

piloty/
  core.py        # PTY + terminal renderer + session logs
  mcp_server.py  # MCP tools + state inference
tests/
tools/
  pty_playground.py
  session_viewer.py

Run tests:

python -m pytest -q

License: Apache License 2.0, see LICENSE.

Available Tools

17 tools
clear_scrollbackB

Clear rendered scrollback history while preserving current screen.

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

Inputs: session_id (required).

configure_sessionA

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.

Inputs: session_id (required), description, shell_prompt_regex.

create_sessionA

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).

Inputs: cwd (required), session_id (required), description.

get_metadataB

Get metadata for an existing PTY session.

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

Inputs: session_id (required).

list_sessionsD

Inputs: no named parameters.

send_controlA

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.

Inputs: key (required), session_id (required), deadline_s.

send_lineA

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)

Inputs: line (required), session_id (required), deadline_s.

send_passwordA

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.

Inputs: password (required), session_id (required), deadline_s.

send_signalB

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

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

Inputs: signal (required), session_id (required), deadline_s.

send_textA

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.

Inputs: text (required), session_id (required), deadline_s.

snapshot_screenA

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.

Inputs: session_id (required).

snapshot_scrollbackA

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.

Inputs: session_id (required), lines.

terminateB

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

Inputs: session_id (required).

transcriptC

Get the transcript file path for this session.

Inputs: session_id (required).

wait_for_outputA

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().

Inputs: session_id (required), deadline_s.

wait_for_regexA

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.

Inputs: pattern (required), session_id (required), deadline_s.

wait_for_shell_promptA

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.

Inputs: session_id (required), deadline_s.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: session lifecycle, input methods (line, text, control, password, signal), output retrieval (snapshots, transcript), and waiting mechanisms (output, regex, prompt). No overlap or ambiguity.

    Naming Consistency5/5

    All tools use a consistent verb_noun snake_case pattern (e.g., create_session, send_line, wait_for_shell_prompt). No mixing of conventions.

    Tool Count5/5

    17 tools are well-scoped for a PTY management server, covering all necessary interactions without bloat. Each tool serves a distinct, necessary function.

    Completeness5/5

    The tool set covers session lifecycle, multiple input modes, output retrieval, and waiting for various states. It includes password handling and signal sending, appearing complete for typical terminal interaction use cases.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      DockaShell is an MCP server that provides AI agents with isolated Docker containers for persistent shell access, file operations, and full audit trails, enabling autonomous development and self-evolving workflows.
      11 npm
      30
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      MCP server giving AI agents full SSH access with persistent sessions, structured command output, SFTP file transfer, and port forwarding.
      18
      62 PyPI
      12
      MIT