Workwright

Playwright for terminals. An MCP server that gives AI coding assistants a real, visible PTY they — and you — can watch live.

---

Why

AI assistants run commands in hidden subprocesses. When you ask them to test a CLI tool — interactive prompts, progress bars, colored output, TUI apps — you can't see what happened. Logs get stripped, stderr merges with stdout, colors vanish.

Workwright opens a visible terminal window (xterm.js in your browser) that you and the AI can both see and interact with. The AI drives it through MCP tools; you watch it work.

This is the terminal analogue of Playwright: Playwright opens a visible browser and gives you page.goto, locator, and assertions. Workwright opens a visible terminal and gives you workwright_launch, workwright_execute, and workwright_wait_for_text.

Quick start

# Install
npm install -g workwright

Add to your MCP client config — Cursor (~/.cursor/mcp.json), Claude Code, Windsurf, or any MCP-speaking client:

{
  "mcpServers": {
    "workwright": {
      "command": "npx",
      "args": ["workwright"]
    }
  }
}

Now ask your assistant: "Use workwright to run the test suite and watch it live." A browser window opens with the terminal. The AI runs commands. You watch.

Headless mode (CI, no viewer)

{
  "mcpServers": {
    "workwright": {
      "command": "npx",
      "args": ["workwright", "--no-viewer"]
    }
  }
}

From a local clone

{
  "mcpServers": {
    "workwright": {
      "command": "node",
      "args": ["/absolute/path/to/workwright/lib/index.js"]
    }
  }
}

Tools

Fourteen MCP tools, grouped by purpose:

Sessions

Tool	Description
workwright_launch	Start a new PTY session. Opens the viewer on first call.
workwright_list	List active sessions with shell, PID, CWD, dimensions.
workwright_select	Switch the current session by index.
workwright_close	Close one session.
workwright_close_all	Close everything and shut down.
workwright_resize	Resize the current terminal (cols × rows).

Running commands

Tool	Description
workwright_execute	Run a command and wait for completion. Returns captured output.
workwright_send_input	Send raw text (no wait). For interactive prompts, REPLs, TUIs.
workwright_send_keys	Send special keys: Ctrl+C, Enter, Tab, arrows, F1-F12, etc.

Observing

Tool	Description
workwright_read_output	Read the terminal buffer (last N lines or full scrollback).
workwright_wait_for_text	Wait for literal text or a regex. Fails fast on timeout.
workwright_snapshot	Clean text snapshot with ANSI stripped.
workwright_screenshot	Capture terminal (PNG when viewer is running, else text).
workwright_get_config	Inspect current server configuration.

CLI options

--port <port>          Start HTTP server (default: stdio)
--shell <shell>        Default shell (bash, powershell, cmd)
--cols <cols>          Terminal columns (default: 120)
--rows <rows>          Terminal rows (default: 30)
--no-viewer            Disable xterm.js browser viewer (headless)
--viewer-port <port>   Viewer WebSocket port (default: auto)

Architecture

  MCP client ──stdio──▶ workwright process ──PTY──▶ shell (pwsh/bash/cmd)
  (AI assistant)              │                          │
                              ▼                          │
                         WebSocket server ◀─── output ───┘
                              │
                              ▼
                         Browser (xterm.js viewer)
                         └── you watch it live

Same shape as Playwright:

Playwright (browser)	Workwright (terminal)
Launches browser, user sees pages	Launches PTY, user sees terminals
page.goto, locator, assertions	workwright_execute, workwright_read_output, workwright_wait_for_text
Tracing and screenshots	Terminal buffer, snapshots, PNG screenshots
Config file + env	CLI flags (config file planned — see roadmap)

Workwright is not a fork of Playwright. It reuses the architectural pattern — visible, driveable, AI-automatable — for terminals instead of browsers. @playwright/test is used only as the integration test runner.

Security

Workwright runs arbitrary shell commands on the host. Only use it with MCP clients and configurations you trust. See SECURITY.md.

The viewer surface is locally-scoped by design:

• Binds to 127.0.0.1 only — no remote network reach.
• WebSocket Origin allowlist — rejects cross-site hijacking attempts from malicious webpages.
• No auth token: trust boundary is "any user on this machine".

If you don't need the viewer, run with --no-viewer.

Development

git clone https://github.com/balgaly/workwright.git
cd workwright
npm install
npm run build
npm test     # 74 integration tests via @playwright/test over stdio

See CONTRIBUTING.md for build, lint, and PR expectations.

Roadmap

Tracked in docs/PUBLIC-ROADMAP.md. Highlights:

• Config file (workwright.config.ts / .mjs) + env var overrides (WORKWRIGHT_*).
• True canvas-based screenshots via the viewer (currently text-snapshot fallback).
• Record mode: capture a session as an asciinema-compatible cast.

License

MIT — see LICENSE. Copyright © 2026 Workwright contributors.

---

Workwright is not affiliated with or endorsed by Microsoft or the Playwright project. "Playwright" is a trademark of Microsoft. Workwright is a distinct project that borrows Playwright's design philosophy for terminal automation.