termmirror

An MCP server that gives AI agents real interactive terminal sessions — and a live web view where a human can watch those sessions and type into them.

Most agent tooling can only run commands that exit on their own. Anything that prompts, redraws, or waits for a keystroke is out of reach: installers, ssh with a password challenge, pdb, vim, a package manager's configuration screen — and another agent's CLI. termmirror keeps real PTY sessions open so an agent can work them the way a person does, one keystroke at a time, while a human can look over its shoulder and step in when needed.

One agent driving a Claude Code session through termmirror — it accepted the trust prompt, asked a question, and read the answer off the screen. The browser view is live, and typing in it goes straight to the same terminal.

A full-screen TUI under the same tools: the agent opened vim, moved to the end of the file, entered insert mode, and typed a line.

Features

• Real PTY sessions. Backed by node-pty with a headless terminal emulator holding screen state. No tmux or other external dependency.

• Built for TUIs. Alternate-screen detection, key encoding for control and navigation keys, and scrollback that unwraps soft-wrapped lines.

• Reliable waiting. wait returns once a program has responded and settled, so the screen you read reflects your input rather than the state before it.

• Live web view. Any session can be watched in the browser as it runs. Typing in the page goes straight to the PTY, so a human can take over and hand back.

• Agent-to-agent. Designed so one agent can drive another agent's CLI through a multi-turn conversation.

• Recordable. Any session can be recorded in the background and exported as a GIF, an mp4, or an asciicast, which makes demoing a terminal workflow a two-tool-call job.

Related MCP server: ddx-term-mcp

Requirements

• Node.js 20 or newer

• macOS or Linux

Installation

npm install termmirror

Or from source:

git clone https://github.com/Ar9av/termmirror.git
cd termmirror
npm install && npm run build

termmirror repairs node-pty's helper permissions at runtime, so --ignore-scripts costs nothing on macOS and Windows, where node-pty ships a prebuilt binding.

On Linux there is no prebuilt binding — node-pty compiles one from its own install script. With ignore-scripts=true (npm v12's default, and a common hardening setting) that is skipped silently, and the first session fails with Failed to load native module: pty.node. Build it once with npm rebuild node-pty --foreground-scripts, which needs make, g++ and python3.

Register the server with Claude Code:

claude mcp add --scope user termmirror -- node /absolute/path/to/termmirror/dist/src/index.js

--scope user matters: without it the server is registered for the current project only, and the tools are missing from every other one. The .mcp.json in this repo is the same kind of project-scoped registration — it serves the repo's own development, needs npm run build to have run, and Claude Code asks to approve it the first time.

Any MCP client works; the server speaks stdio.

Usage

Three tools, used in this order:

send_input  →  wait  →  read_screen

read_screen returns the screen as it looks now — a screenshot, not a log of everything printed. wait is what makes that screenshot worth reading: it blocks until the program has responded and gone quiet, so you see the state after your keystroke.

Tools

Waiting

idle is the default and the right choice in most cases. Interactive programs redraw continuously while they work and fall silent when it is your turn, so silence is a reliable completion signal — including for spinners and TUIs that expose no prompt to match against. Increase timeout for slow operations.

A no_output result means nothing came back since your input: the program is either busy and silent, or the input never registered.

Use pattern when the expected text is known. It matches against the whole screen, including your own echoed input, so wait for something the program prints rather than a marker you just typed.

Watching a session

The first session starts a local web server on port 7878. Open the URL returned by create_session to see the session live. Typing in the page writes directly to the PTY, which lets a human enter a password or answer a prompt the agent should not handle, then hand control back — no handoff protocol, just the same terminal from the other side.

Recording a session

start_recording captures everything the session prints from that point on, passively, while the agent keeps driving it as usual. stop_recording finishes the capture and renders it:

start_recording  →  (drive the session)  →  stop_recording

Recordings are written as asciicast v2 (.cast) under ~/.termmirror/recordings/ unless a path is given. A .cast is a complete recording on its own — asciinema play file.cast replays it — and stop_recording renders it to a shareable file:

brew install agg ffmpeg   # or: cargo install --git https://github.com/asciinema/agg

Pauses longer than idle_time_limit seconds (default 2) are shortened in the render — a session spends most of its wall clock waiting on an agent turn or a build, and none of that is worth watching at real speed. Pass idle_time_limit: null to keep the original timing, and speed to scale the whole thing.

Neither binary ships with termmirror. Without them stop_recording still returns the .cast along with a note on how to install what was missing, so a recording is never lost to a missing renderer. Recordings are also finalized automatically when the process exits or the session is killed.

Example

node examples/drive-claude.mjs "what is 2+2? reply with just the number"

One agent starts claude, accepts its trust prompt, asks a question, and reads the answer off the screen — the same tools the MCP interface exposes, written out longhand.

Development

npm run build    # compile TypeScript to dist/
npm test         # build, then run the test suite

The suite covers the wait semantics the rest of the server depends on, key encoding, scrollback, the web view's live stream and take-over typing, and an end-to-end run over the real MCP protocol.

A note on the name

The package is termmirror, with two m's. alias/termirror/ is a stub package that depends on it so the one-m spelling resolves to the right place.

License

MIT