pilotty-mcp

# pilotty-mcp An MCP server that gives AI agents full control over interactive terminal applications — things a normal shell command cannot handle. A plain shell tool is blind to interactive terminal programs. `pilotty-mcp` solves this by running commands in a managed PTY session and exposing tools to read the screen, send keystrokes, and wait for changes — the same way a human would interact with a terminal. Examples: - `drizzle-kit generate` prompts for confirmation before applying schema changes - `git rebase -i` opens a todo list editor that must be navigated and saved - `npm create` walks through a project scaffolding wizard - `lazygit`, `htop`, `vim`, and any other full-screen TUI Built on [`pilotty`](https://github.com/msmps/pilotty). ## What it handles - Confirmation prompts (`y/n`, `ok/cancel`) - Interactive selection menus (arrow keys, space to select) - Text input prompts (passwords, paths, names) - Full-screen TUIs (`vim`, `lazygit`, `htop`, interactive rebase editors, etc.) - Commands that exit immediately — the transcript and exit code are still captured and returned ## Requirements - [Bun](https://bun.sh) — the server runs on Bun - [`pilotty`](https://github.com/msmps/pilotty) installed and on `PATH` ```bash npm install -g pilotty ``` ## Installation ```bash git clone https://github.com/henrikklee/pilotty-mcp cd pilotty-mcp bun install ``` ## Add to Claude Code ```bash claude mcp add --transport stdio --scope user pilotty-mcp -- bun run /absolute/path/to/pilotty-mcp/index.ts ``` Or add manually to `~/.claude.json`: ```json { "mcpServers": { "pilotty-mcp": { "type": "stdio", "command": "bun", "args": ["run", "/absolute/path/to/pilotty-mcp/index.ts"] } } } ``` ## Add to OpenCode Add to `~/.config/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "pilotty-mcp": { "type": "local", "command": ["bun", "run", "/absolute/path/to/pilotty-mcp/index.ts"], "enabled": true } } } ``` ## Tools | Tool | Description | |---|---| | `start_interactive_command` | Start a PTY session for a command that needs live input | | `get_terminal_snapshot` | Read the current screen state | | `wait_for_terminal` | Block until text, a regex, or a screen change appears | | `send_terminal_keys` | Send keys or key sequences (`Enter`, `Ctrl+C`, `Escape : w q Enter`) | | `type_into_terminal` | Type literal text at the cursor | | `list_interactive_sessions` | List active sessions | | `stop_interactive_command` | Kill a session | ## How it works 1. Agent encounters a command that needs interactive input. 2. Agent calls `start_interactive_command` with that command. 3. `pilotty-mcp` runs it in a PTY session and returns an initial screen snapshot. 4. Agent reads the screen, sends keys or text, waits for the screen to update, repeats. 5. When the command exits, the final transcript and exit code are returned. ## Development ```bash bun run typecheck bun run fmt ```