PiloTY
yiwenlu66/PiloTY
Terminal persistente e stateful para agentes IA via MCP
Ver no GitHubMCP server que fornece aos agentes IA um terminal interativo persistente, mantendo estado entre chamadas de ferramentas. Permite executar comandos de longa duração, monitorar logs, manter REPLs/debuggers abertos e lidar com operações interativas como senhas, sem perder contexto.
Instalação
npx convez-ai yiwenlu66/PiloTY1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar builds, instalações e suites de testes de longa duração
- Monitorar logs em tempo real (tail -f, journalctl, kubectl logs)
- Manter REPL/debugger aberto enquanto agente testa ideias
- Gerenciar operações interativas e prompts de senha (sudo, SSH)
- DevOps remoto com sessões SSH persistentes
Veredito

Solução robusta para colmatar a lacuna de estado em operações terminais de agentes IA. Requer cuidado com segurança (expõe acesso irrestrito ao terminal), mas é essencial para fluxos DevOps e debugging complexos.
README
A tradução para o português deste README ainda está na fila.
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,vimcan work, but cursor-heavy programs often require screen snapshots instead of plain text output.
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, orterminatedterminal_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_lineto submit a newline-terminated command,send_textfor raw bytes, andsend_control/send_signalfor interrupts. - Use
wait_for_outputfor temporal PTY output waiting,wait_for_regexfor content-based waits, andwait_for_shell_promptaftersshor similar login flows. - Use
snapshot_screen/snapshot_scrollbackwhen 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_passwordfor 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_sis 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, default1000) or whendeadline_sexpires. wait_for_outputcan return partial output withoutcome=deadline_exceededif output started but the PTY never went quiet before the deadline.wait_for_regexfirst checks already-rendered scrollback, then waits on new PTY bytes.wait_for_shell_promptconsumes PTY output while it waits and returns the consumed bytes inoutput.- 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(default1000).
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.