How do I use ptywright?

This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

ptywright

by kingsword09

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

ptywright

中文文档

ptywright is a terminal/TUI automation driver. It launches CLI/TUI programs in a PTY, feeds ANSI/VT output into @xterm/headless, rebuilds the terminal screen, and exposes that state through MCP tools, script runners, replayable cassettes, and browser-terminal regression workflows.

The core idea is simple: prefer deterministic terminal snapshots over screenshots when testing terminal behavior.

What It Solves

Drive a live terminal from an MCP client or agent.
Test CLI/TUI flows with JSON/TypeScript scripts, goldens, and HTML reports.
Record raw PTY byte streams once and replay them without rerunning the command.
Test browser-hosted terminal renderers with terminal/DOM snapshots.
Keep generated artifacts portable with manifests, hashes, and reusable argv commands.

Non-goals remain intentional: ptywright does not try to reverse-engineer a full component tree from terminal cells, and pixel-level screenshot diff is not the main regression path.

Related MCP server: pty-mcp

Install

# One-off usage
bunx ptywright@latest --help
npx -y ptywright@latest --help

# Or install globally
bun add -g ptywright
npm install -g ptywright

Inside this repository, use the local CLI:

bun run src/cli.ts help

Pick A Workflow

Need	Use	Start here
Let an agent inspect and control a live CLI/TUI	MCP server	MCP tools
Write deterministic CLI/TUI regression tests	Script runner	Script runner
Capture terminal bytes once and replay them later	Raw PTY cassette	Raw PTY cassettes
Test a browser page that renders a terminal	Browser agent regression	Browser agent regression
Feed raw PTY replay into a downstream browser terminal renderer	Browser harness	Browser terminal harness
Debug CI failures, moved artifacts, or snapshot drift	Artifact commands	Artifacts and CI

Quick Start

MCP Server

ptywright mcp
ptywright mcp --caps core
ptywright mcp --caps core,script,recording
ptywright mcp-http --port 3000

MCP client config:

{
  "mcpServers": {
    "ptywright": {
      "command": "bunx",
      "args": ["ptywright@latest", "mcp", "--caps", "core,script,recording"]
    }
  }
}

Typical MCP flow: launch_session, wait_for_text, send_text or press_key, wait_for_stable_screen, snapshot_text or snapshot_view, then close_session.

Script Runner

Create a JSON script:

{
  "$schema": "./schemas/ptywright-script.schema.json",
  "name": "tui_smoke",
  "launch": {
    "command": "bun",
    "args": ["run", "tests/fixtures/tui_demo.ts"],
    "cols": 80,
    "rows": 24
  },
  "steps": [
    { "type": "waitForText", "text": "PTYWRIGHT TUI DEMO" },
    { "type": "snapshot", "kind": "text", "saveAs": "ready" },
    { "type": "expect", "from": "ready", "contains": ["status: ok"] }
  ]
}

Run it:

ptywright run scripts/tui_smoke.json
ptywright run-all --dir scripts
ptywright script inspect .tmp/run-all

Run output is written under .tmp/runs/<name>/ for single scripts and .tmp/run-all/ for suites by default.

Raw PTY Cassette

ptywright pty record --out tests/cassettes/session.pty.json -- codex
ptywright pty replay tests/cassettes/session.pty.json --speed 0
ptywright pty validate tests/cassettes/session.pty.json
ptywright pty inspect tests/cassettes/session.pty.json

For projects that already own a node-pty or bun-pty style process, use the programmatic wrapper:

import { wrapPtyLike } from "ptywright/pty-cassette";

const recorded = wrapPtyLike(pty, {
  path: "tests/cassettes/session.pty.json",
  terminal: { cols: 120, rows: 40, term: "xterm-256color" },
  command: { file: "codex", args: [] },
});

recorded.write("hello\r");

Browser Agent Regression

Use this when a browser page renders a terminal and exposes [data-terminal-root].

ptywright agent run examples/agent_deterministic.json --update-snapshots
ptywright agent run examples/agent_deterministic.json
ptywright agent replay .tmp/agent/agent_deterministic/agent_deterministic.cassette.json
ptywright agent check

The preferred integration is launch.mode="command": start a wrapper command, read the first printed URL, open it with Playwright, and snapshot terminal/DOM state across configured viewports.

Command Map

ptywright mcp                         # MCP over stdio
ptywright mcp-http --port 3000        # MCP over Streamable HTTP
ptywright run <file.json|file.ts>     # Run one script
ptywright run-all --dir scripts       # Run a script suite
ptywright script inspect <dir>        # Inspect script artifacts
ptywright pty record --out <file> -- <command> [args...]
ptywright pty replay <file>
ptywright agent run <flow.json>
ptywright agent replay <run-or-cassette>
ptywright agent promote <run-or-cassette>
ptywright agent replay-all [dir]
ptywright agent check [dir]
ptywright agent inspect <artifact-or-dir>
ptywright agent exec <artifact-or-dir> --command rerun

Run ptywright help for the full CLI surface.

Documentation

JSON schemas live in schemas/, and examples live in examples/ and scripts/.

Project Layout

src/cli/           CLI argument parsing and command dispatch
src/mcp/           MCP server and tool registrations
src/session/       TerminalSession lifecycle, waits, snapshots, frames
src/pty/           PTY adapter abstraction and Bun backends
src/terminal/      xterm/headless snapshot, ANSI, style, mouse helpers
src/script/        JSON/TS script runner, suites, reports, manifests
src/agent/         Browser terminal agent flows, replay, promote, check
src/pty-cassette/  Raw PTY record/replay and wrapper APIs
src/trace/         Cast and HTML report generation
schemas/           Published JSON schemas
tests/             Deterministic fixtures, goldens, cassettes, snapshots

Development

bun install

# Local CLI and MCP
bun run src/cli.ts help
bun run src/cli.ts mcp

# Main gates
bun run test
bun run agent:check
bun run check

# Formatting and linting
bun run format:check
bun run lint

# Useful focused runs
bun run src/cli.ts run examples/report_demo_pass.json
bun run src/cli.ts run-all --dir scripts
bun run src/cli.ts agent run examples/agent_deterministic.json --update-snapshots

CI installs Chromium, runs bun run check, and uploads .tmp/agent-check.

Environment

TUI_TEST_PTY_BACKEND=auto|bun-terminal|bun-pty
- Default auto: macOS/Linux prefer bun-terminal; Windows uses bun-pty.
PTYWRIGHT_CAPS=all|core|debug|script|recording
- Equivalent to ptywright mcp --caps ....

License

Apache-2.0

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Reason
io.github.reason-machines
Start and manage Reason cloud coding agents, projects and sessions from any MCP client.
Coding Agents Agent Orchestration Autonomous Agents
1
https://mcp.reasonmachines.com/mcp
Hither
dev.hither
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
File Systems Shell Access Browser Automation
1
https://hither.dev/mcp
ezremote
lol.masti.tunnel
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
File Systems Shell Access Browser Automation
1
https://tunnel.masti.lol/mcp
Node Command
io.github.huseyincig
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
File Systems Shell Access Browser Automation
1
https://mcp.nodecommand.app/mcp

Related MCP Servers

shell-session-mcp
Shell Access Command Line
CarefulDeveloper
A
license
Not graded
quality
D
maintenance
Provides persistent interactive shell sessions via pseudo-terminals for MCP agents, enabling bidirectional communication, incremental reads, and stateful command execution across steps.
Updated 4 months ago (2026-07-15 18:16 UTC)
9 npm
MIT
pty-mcp
Testing & QA Tools Developer Tools Command Line
Chrlstopher-c
F
license
Not graded
quality
C
maintenance
Enables end-to-end testing of CLI applications, REPLs, and TUIs by driving interactive pseudo-terminal sessions and reading clean rendered output through any MCP client.
Updated 2 months ago (2026-08-31 01:21 UTC)
-
termius-mcp
Command Line Shell Access
yapp
A
license
Not graded
quality
C
maintenance
Enables users to drive visible terminals in a locally running Termius desktop app by creating, sending to, reading from, resizing, and closing local terminals or existing SSH sessions through MCP tools.
Updated 2 months ago (2026-09-14 11:05 UTC)
ISC
termcp
Command Line Shell Access Developer Tools
open-mcp-ai
A
license
Not graded
quality
B
maintenance
Enables AI agents to interact with real terminal sessions across local and remote hosts, driving multi-turn interactive programs like TUIs, REPLs, and SSH prompts through MCP.
Updated a day ago (2026-11-11 14:18 UTC)
68
MIT

ptywright

What It Solves

Install

Pick A Workflow

Quick Start

MCP Server

Script Runner

Raw PTY Cassette

Browser Agent Regression

Command Map

Documentation

Project Layout

Development

Environment

License

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

shell-session-mcp

pty-mcp

termius-mcp

termcp