ap-terminal

Real PTY Terminals

When to use

Use ap-terminal when a task needs a genuine interactive terminal — a TUI that repaints in place, a CLI that prompts step by step, or anything expecting a real tty (raw mode, cursor control, paste detection). Batch, non-interactive work belongs in command_execute (see ap-run-command), not here.

MCP tool: terminal_start

Spawn a PTY running argv (e.g. ['bash'], or an interactive CLI directly). Set cwd, a name/label for the session list, and cols/rows if the TUI is picky about terminal size.

{
  "tool": "terminal_start",
  "args": {
    "argv": ["claude"],
    "cwd": "/Volumes/SSDExternalMacStudio/Code/products/agentik/agentik-studio/apps/simone",
    "name": "simone-claude-tui",
    "cols": 120,
    "rows": 40
  }
}

MCP tool: terminal_output

Read the current screen/buffer. clean: true strips ANSI escape codes for readable text; lastBytes caps how much of the tail you pull back. The buffer is a ring of roughly 64KiB — older output is gone once it rolls off.

{ "tool": "terminal_output", "args": { "sessionId": "term_4b91", "clean": true, "lastBytes": 4000 } }

MCP tool: terminal_input

Send keystrokes. text is sent verbatim (no implicit newline). Set enter: true to additionally send an isolated carriage return AFTER the text — required for paste-detecting TUIs that ignore a newline embedded in pasted content.

{ "tool": "terminal_input", "args": { "sessionId": "term_4b91", "text": "/status", "enter": true } }

MCP tool: terminal_kill

Tear down the PTY when done or wedged.

{ "tool": "terminal_kill", "args": { "sessionId": "term_4b91" } }

MCP tool: terminal_sessions_list

List live terminal sessions. Without limit at most 50 rows come back; when there are more, the reply carries total, truncated: true and a nextCursor (pass it as cursor, with a limit, for the next page), or narrow with onlyAlive / status.

{ "tool": "terminal_sessions_list", "args": {} }