smart-terminal — Claude Code MCP server for interactive shells
Gives an agent a persistent PTY shell: send commands, type keys, read output between steps. Useful when interactive tools stall on piped stdin.
claude mcp add smart-terminal -- npx -y smart-terminal-mcpWhat smart-terminal does
This server keeps a shell alive with node-pty instead of closing it after each call. The agent types a command, reads the reply, and carries on in the same folder with the same environment and background processes. Separate tools handle the awkward parts: terminal_write and terminal_read for prompts and REPLs, terminal_wait to pause until a pattern shows up, terminal_watch to return on a match, silence, timeout or exit.
Big output gets handled too. Passing since to terminal_read returns only new bytes from the buffer. terminal_run_paged walks long read-only output a page at a time, terminal_diff produces a unified diff between two runs, and terminal_exec trims oversized output to its head and tail. terminal_retry repeats a flaky command with bounded backoff.
On Windows the shell is picked in order: pwsh.exe, powershell.exe, cmd.exe. Linux and macOS use $SHELL, then bash, then sh. Up to 10 named sessions can run at once, with readable IDs like calm-reef. terminal_run starts a binary straight from cmd + args with shell=false, so anything relying on aliases or pipes has to go through terminal_exec.
What it helps with
- drive an interactive installer that hangs on a pipe
- wait for a server's startup line without polling in a loop
- fetch only fresh output after a long build
- diff the output of two identical commands
- keep the working directory across agent steps
Example prompts for the agent
- Start
npm run devand wait for the line about the port - Send Ctrl+C to session
calm-reefand show the last lines - Run
git statustwice and diff the two results
How to install smart-terminal
Platform CLI
claude mcp add smart-terminal -- npx -y smart-terminal-mcpPlatform CLI
codex mcp add smart-terminal -- npx -y smart-terminal-mcpConfig file
{
"mcpServers": {
"smart-terminal": {
"command": "npx",
"args": [
"-y",
"smart-terminal-mcp"
]
}
}
}Config file
{
"servers": {
"smart-terminal": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"smart-terminal-mcp"
]
}
}
}Platform CLI
gemini mcp add smart-terminal npx -y smart-terminal-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about smart-terminal
How do I install smart-terminal in Claude Code?
Run claude mcp add smart-terminal -- npx -y smart-terminal-mcp.
What does smart-terminal do?
It opens one PTY-backed shell that stays open and hands the agent tools to run commands, type input, read output and wait for specific lines in it.
How is it different from a plain exec tool?
A plain exec call ends and drops the session state. The PTY session survives between steps and accepts keystrokes, so vim, npm prompts and TTY-aware installers keep working.
