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.

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 — the server runs on Bun
• pilotty installed and on PATH

npm install -g pilotty

Installation

git clone https://github.com/henrikklee/pilotty-mcp
cd pilotty-mcp
bun install

Add to Claude Code

claude mcp add --transport stdio --scope user pilotty-mcp -- bun run /absolute/path/to/pilotty-mcp/index.ts

Or add manually to ~/.claude.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:

{
  "$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

bun run typecheck
bun run fmt