| name | terminal-session-debugging |
| description | Use when debugging interactive CLI, REPL, TUI, ssh, telnet, nc, watch-mode, dev server, long-running command, terminal prompt flow, or any command that may not exit. Provides a PTY-backed MCP workflow for spawning terminal sessions, sending text and keys, reading output, managing multiple sessions, and exporting full transcripts. |
Terminal Session Debugging
Use the terminal-session MCP server for terminal programs that need real PTY behavior or may not exit.
When to Use
Use this workflow for:
- Interactive CLIs, REPLs, shell prompts, installers, wizards, and prompt loops.
- TUI/curses programs where terminal size and key handling matter.
ssh, telnet, nc, and other bidirectional terminal/network sessions.- Watch-mode tools, dev servers, and commands that may run forever.
- Multi-session debugging such as server + client, listener + connector, REPL + shell.
- Any task where a normal Bash call may block, hide prompts, or lose interaction history.
Core Workflow
- Call
health_check to confirm the MCP server is available.
- Call
spawn_terminal with a clear label.
- Call
read_terminal to observe initial output.
- Send one input at a time with
send_text or send_key.
- Read after every input before deciding the next action.
- Use
terminal_status and list_terminals to inspect state.
- Use
resize_terminal when terminal dimensions matter.
- Use
close_terminal to interrupt, send EOF, terminate, or kill sessions.
- Call
export_transcript before reporting final results.
Recording Model
The MCP records command, output, stdin text, key events, resize events, close events, exit status, and errors under .terminal-debug/. It does not redact, mask, block, or safety-filter commands or content. Treat transcripts as complete debugging evidence.
Interaction Discipline
- Do not send a long script of answers until the prompt sequence is known.
- For prompt flows, treat each prompt as a state; capture, send one response, capture again.
- For multiple sessions, use labels such as
server, client, listener, repl, or ssh.
- Never claim a behavior happened unless it appears in
read_terminal, terminal_status, or the exported transcript.
Report Format
When reporting results, include:
- Session IDs and labels.
- Commands spawned.
- Inputs and keys sent.
- Observed output evidence.
- Interpretation of what the evidence proves.
- Transcript export paths.
- Cleanup status for active sessions.
