Control any terminal emulator programmatically. Send keystrokes, read the screen, take screenshots, and run commands — all over WebSocket JSON-RPC. Built for AI coding agents.
curl -fsSL https://raw.githubusercontent.com/moejay/wrightty/main/install.sh | sh
cargo install wrightty
pip install wrightty[cli,mcp]
npm install @moejay/wrightty
Execute shell commands and capture output. Wait for prompts, handle timeouts, parse results.
Read terminal text including TUI apps, colors, and cursor position. Full cell-level access.
Type text, send Ctrl+C, navigate vim, interact with any TUI. Supports all modifiers and special keys.
Capture the terminal as SVG, PNG, or structured JSON. Perfect for visual testing and documentation.
Block until a pattern appears on screen. Supports regex, timeouts, and polling intervals.
Record as asciicast (asciinema-compatible), replayable scripts (Python/JSON/CLI), or video.
from wrightty import Terminal term = Terminal.connect() # auto-discovers running server output = term.run("cargo test") print(output) term.wait_for("$") term.send_keys("Ctrl+c") svg = term.screenshot("svg") # Record a session (asciinema-compatible) rec = term.start_session_recording() term.run("make build") result = term.stop_session_recording(rec) term.close()
import { Terminal } from "@moejay/wrightty"; const term = await Terminal.connect(); const output = await term.run("cargo test"); console.log(output); await term.waitFor("$"); await term.sendKeys("Ctrl+c"); const svg = await term.screenshot("svg"); // Record a session const rec = await term.startSessionRecording(); await term.run("make build"); const result = await term.stopSessionRecording(rec); term.close();
# Start a headless server $ wrightty term --headless # Run commands $ wrightty run "ls -la" $ wrightty run "cargo test" --timeout 120 # Read screen $ wrightty read # Send input $ wrightty send-keys Ctrl+c $ wrightty send-keys Escape : w q Enter # Screenshots $ wrightty screenshot --format svg -o terminal.svg # Wait for output $ wrightty wait-for "BUILD SUCCESS"
// Connect with any WebSocket client $ wscat -c ws://127.0.0.1:9420 // Read the screen → {"jsonrpc":"2.0","id":1,"method":"Screen.getText", "params":{"sessionId":"0"}} ← {"result":{"text":"$ ls\nCargo.toml src tests\n$"}} // Send keystrokes → {"jsonrpc":"2.0","id":2,"method":"Input.sendKeys", "params":{"sessionId":"0","keys":["Ctrl+c"]}} ← {"result":{}}
Virtual PTY with no window. Uses Alacritty's terminal engine. Perfect for CI, testing, and headless automation.
Fork with wrightty built in. Zero overhead — reads directly from Alacritty's terminal state.
Works with any terminal running inside tmux. The universal escape hatch.
Translates wrightty calls into wezterm cli commands. Full session support.
Uses Kitty's remote control protocol. Requires allow_remote_control yes.
Connects via Ghostty's Unix IPC socket. Also has a native fork available.
Uses Zellij's CLI actions from within a running session.
foot, GNOME Terminal, Rio, or anything else — just run it inside tmux and use the tmux bridge.
| Domain | Methods | Purpose |
|---|---|---|
| Wrightty | getInfo | Capability negotiation |
| Session | create destroy list getInfo | Lifecycle management |
| Input | sendKeys sendText sendMouse | Keystrokes & text |
| Screen | getText getContents screenshot waitForText ... | Read & capture |
| Terminal | resize getSize setColorPalette ... | Configuration |
| Recording | startSession startActions captureScreen startVideo ... | Session recording |
| Events | subscribe unsubscribe | Screen updates, bell, title |
# Start with a name and password $ wrightty term --headless --name my-server --password secret123 # Discover shows name and auth status $ wrightty discover ws://127.0.0.1:9420 wrightty-server v0.1.2 (my-server) [password]
# Python term = Terminal.connect(password="secret123") # Node.js const term = await Terminal.connect({ password: "secret123" }) # CLI wrightty --password secret123 run "ls -la" wrightty-py --password secret123 read wrightty-js --password secret123 read
{
"mcpServers": {
"wrightty": {
"command": "python3",
"args": ["-m", "wrightty.mcp_server"],
"env": { "WRIGHTTY_SOCKET": "ws://127.0.0.1:9420" }
}
}
}