How do I use ptywright?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ptywright Launch a terminal session, run 'ls -la', and snapshot the output." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ptywright

by kingsword09

Overview Schema Related Servers Score Discussions

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: interactive-process-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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

2wRelease cycle

12Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kingsword09/ptywright'

If you have feedback or need assistance with the MCP directory API, please join our Discord server