PiloTY

1<p align="center">
2  <img src="assets/logo.png" alt="PiloTY logo" width="220" />
3</p>
4 
5# PiloTY
6 
7PiloTY (PTY for your AI Copilot) is an MCP server that gives an agent a persistent, interactive terminal.
8 
9If 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.
10 
11PiloTY 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.
12 
13Warning: PiloTY exposes unrestricted terminal access. Treat it like giving the agent your keyboard.
14 
15## What it enables
16 
17- Long-running commands: builds, installs, migrations, test suites. Start once, check output later.
18- Log monitoring: `tail -f`, `journalctl -f`, `kubectl logs -f`, CI logs, service restarts.
19- "Vibe debugging": keep a REPL/debugger open while the agent reads code and tries ideas (`python`, `ipython`, `pdb`).
20- Privileged operations: handle interactive password prompts (`sudo`, SSH passwords, key passphrases).
21- SSH-based devops: keep a remote login session alive across tool calls; run remote commands in the same shell.
22- Terminal UIs: `less`, `man`, `top`, `vim` can work, but cursor-heavy programs often require screen snapshots instead of plain text output.
23 
24## Quickstart
25 
26PiloTY is meant to be launched by an MCP client over stdio.
27 
28Add it to Codex CLI as an MCP server:
29 
30```bash
31codex mcp add piloty -- uvx --from git+https://github.com/yiwenlu66/PiloTY.git piloty
32```
33 
34If you prefer SSH-based Git fetch:
35 
36```bash
37codex mcp add piloty -- uvx --from git+ssh://git@github.com/yiwenlu66/PiloTY.git piloty
38```
39 
40If you already have a local clone:
41 
42```bash
43codex mcp add piloty -- uv --directory /path/to/PiloTY run piloty
44```
45 
46Run the server command directly (without adding it to an MCP client):
47 
48```bash
49uvx --from git+https://github.com/yiwenlu66/PiloTY.git piloty
50```
51 
52## Mental model
53 
54One session is one real interactive terminal that stays alive across tool calls.
55 
56- State persists: cwd, environment variables, foreground process, remote SSH connection, REPL/debugger state.
57- PiloTY tracks both the raw output stream and a rendered screen/scrollback view.
58 
59PiloTY keeps two representations:
60 
61- `output`: incremental text stream (optionally ANSI-stripped)
62- Rendered screen/scrollback: what a human would see in a terminal
63 
64Sessions are addressed by a `session_id` string. Reusing the same id is what keeps state.
65 
66## Integration notes (for MCP integrators)
67 
68MCP 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.
69 
70Typical agent workflow:
71 
72- Create a session (explicit cwd) and reuse the same `session_id`.
73- Run commands, poll for output, and send raw input/control keys for interactive programs.
74- For cursor-heavy TUIs, rely on rendered screen snapshots/scrollback rather than plain text output.
75- Use `expect_prompt` after `ssh` or other login flows where the prompt appears later.
76- If prompt detection is wrong (looks idle at a prompt but status stays "running"), configure a custom shell-prompt regex.
77- Use `send_password` for secret entry; terminate the session when done.
78 
79For exact tool names, arguments, and return fields, use your MCP client's tool schema or read `piloty/mcp_server.py`.
80 
81## Limitations
82 
83- Status/prompt detection is best-effort and can be wrong (especially for custom prompts and cursor-heavy TUIs).
84- Plain text output can be misleading for full-screen programs; use screen snapshots when layout matters.
85- `send_password()` suppresses transcript logging and terminal echo for that send. It does not prevent other prompts/programs from echoing secrets later.
86- Quiescence-based output collection can be confused by programs that print periodic noise. Tune with `PILOTY_QUIESCENCE_MS` (default `1000`).
87 
88## Logs
89 
90Each server instance writes session logs under `~/.piloty/`:
91 
92- `~/.piloty/servers/<server-instance-id>/sessions/<session-id>/transcript.log`: raw PTY bytes (combined stdout/stderr)
93- `~/.piloty/servers/<server-instance-id>/sessions/<session-id>/commands.log`: inputs sent (best-effort)
94- `~/.piloty/servers/<server-instance-id>/sessions/<session-id>/interaction.log`: inputs plus captured output (best-effort)
95- `~/.piloty/servers/<server-instance-id>/sessions/<session-id>/session.json`: metadata snapshot
96- `~/.piloty/active/<server-instance-id>/<session-id>`: symlink to the current session directory (when symlinks are supported)
97 
98Server logs default to `/tmp/piloty.log`.
99 
100`tools/session_viewer.py` can inspect sessions:
101 
102```bash
103python tools/session_viewer.py list
104python tools/session_viewer.py info <server-instance-id>/<session-id>
105python tools/session_viewer.py tail -f <server-instance-id>/<session-id>
106```
107 
108## Development
109 
110Repository layout:
111 
112```
113piloty/
114  core.py        # PTY + terminal renderer + session logs
115  mcp_server.py  # MCP tools + state inference
116tests/
117tools/
118  pty_playground.py
119  session_viewer.py
120```
121 
122Run tests:
123 
124```bash
125python -m pytest -q
126```
127 
128License: Apache License 2.0, see `LICENSE`.
129