---
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

1. Call `health_check` to confirm the MCP server is available.
2. Call `spawn_terminal` with a clear `label`.
3. Call `read_terminal` to observe initial output.
4. Send one input at a time with `send_text` or `send_key`.
5. Read after every input before deciding the next action.
6. Use `terminal_status` and `list_terminals` to inspect state.
7. Use `resize_terminal` when terminal dimensions matter.
8. Use `close_terminal` to interrupt, send EOF, terminate, or kill sessions.
9. 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.