pty-repeater

YOUR TERMINAL AGENT's BEST COUPLE !

Just as Terminal Agents use Playwright to control browsers, pty-repeater enables them to control CLI tools, REPLs, and debuggers. It minimizes LLM token consumption and allows seamless session sharing across multiple terminal instances.

CASK RELEASES

coming soon

HOMEBREW

brew install pty-repeater

NPM

npm install -g @zzwz2049/pty-repeater

MCP (Model Context Protocol)

1. Install via NPM

npm install -g @zzwz2049/pty-repeater

2. Configure MCP Server

{
  "mcpServers": {
    "terminalcp": {
      "command": "pty-repeater",
      "args": ["--mcp"]
    }
  }
}

Example Use Case: Terminal Agent REPL control other Terminal Agents

This screenshot demonstrates a PM Agent (ShellAgent-Master) orchestrating multiple Worker Agents (Claude and Codex) through pty-repeater. The left sidebar shows task execution flow, while the right panels display live terminal sessions with token usage tracking and real-time collaboration between agents.

Core Features

Terminal Automation

PM-Agent programmatically controls any CLI tool, AI agents, REPLs, and debuggers through PTY forwarding

Session Persistence

Unix socket IPC communication enables cross-client session sharing. Humans can attach/detach anytime while AI agents run continuously

Dual Output Modes

stdout for rendered terminal screens (TUI/interactive), stream for ANSI-stripped text (logs/builds)

Adaptive Intelligence

Independent write queues prevent race conditions, 200ms CR delay for TUI compatibility, auto-spawn server on demand

Four-Layer Architecture

Terminal Manager

PTY + ANSI rendering core layer

→Spawns processes via node-pty
→Renders ANSI with xterm.js
→Write queues prevent race conditions
→Standalone \r delayed 200ms for TUI

Terminal Server

Persistent daemon service

→Unix socket IPC communication
→Auto-spawn on first start action
→Centralized session management
→Sessions persist after client disconnect

TerminalClient

Universal communication abstraction

→Version compatibility checks
→Only auto-starts server on start action
→Request/response correlation
→Wrapped error handling

User Interface Layer

CLI + MCP dual interface

→CLI: tmux-style syntax ::Enter
→MCP: JSON commands (\r, \u001b)
→Both output plain text
→Minimize token usage

Interactive Sequence Diagrams

OpenAI Codex

Claude Code

100%