Oswright

OSWright

Desktop automation for AI agents, without paying for a screenshot every step.

mcp-name: io.github.Ask-812/oswright

An MCP server that lets an LLM drive real desktop applications — the desktop equivalent of Playwright MCP. It keeps a model of the screen between actions and re-reads only the parts that changed, so the same work costs an order of magnitude fewer tokens.

Eight fields read off an invoice and typed into an expense form, verified by the application itself. Same task, same result, 7.4× less context than returning a screenshot after every action. Every number on screen is measured during the run — regenerate the whole thing with python benchmarks/record_demo.py.

Why this exists

Most GUI agents re-perceive the entire screen on every step: screenshot, OCR, hand the model an image, repeat. Measured on a live desktop, the median observation changes 0.012% of the screen's pixels. Re-reading everything does far more work than the change warrants, and charges ~2,800 image tokens whether anything happened or not.

OSWright asks the compositor what changed, rescans only that, and answers element lookups from the cheapest source that can. The claims below are measured on this machine and reproducible from benchmarks/ — including the ones that did not come out in its favour.

Key Features

• Cross-platform. Windows (Win32 API), Linux (pynput/X11), macOS (pynput/Quartz).
• Accessibility tree. Find elements deterministically by role and name via Windows UI Automation — 100% accurate, instant, no model needed.
• Fast OCR. Windows OCR (built-in, instant) with EasyOCR fallback for Linux/macOS. Results are cached automatically.
• Lightweight on Windows. No PyTorch download — Windows uses the built-in OCR engine, so a full install is a few MB rather than a few GB.
• Image matching. Locates elements by template image via OpenCV.
• Window management. List, focus, minimize, close, and screenshot specific windows.
• Screenshot diffing. Detect when the screen changes with wait_for_change.
• Clipboard access. Read and write system clipboard for data transfer.
• App launcher. Launch applications and wait for them to load.
• Auto-snapshot. Every action returns a screenshot so the agent always sees current state.
• 43 MCP tools. Screen, OCR, UIA, mouse, keyboard, windows, clipboard, and compound actions.
• Incremental perception. Rescans only the parts of the screen that changed, and can return what changed instead of a full screenshot — ~21× fewer tokens per step.
• Screen memory. Recognises screens it has read before and reuses them, verified by pixels — 89× cheaper than reading again.
• Speculative perception. Learns what actions do and confirms the expected result instead of re-reading — 19–23× cheaper, with a surprise report when the interface does something unexpected.
• Adaptive waiting. Waits for the screen to actually settle rather than sleeping a fixed 300 ms — 11.9 s saved over a 50-step task.
• Resolution cascade. Element lookups stop at the cheapest method that works; repeat lookups cost ~0.05 ms.
• DPI-correct. Coordinates are physical pixels everywhere, so clicks land correctly on scaled displays.
• Test suite. 259 automated tests; the desktop-driving ones skip themselves when no display is available.

Requirements

• Python 3.10 or newer
• VS Code, Cursor, Windsurf, Claude Desktop, or any other MCP client

Getting started

First, install the OSWright MCP server with your client.

Standard config works in most tools:

{

"mcpServers": { "oswright": { "command": "uvx", "args": ["oswright"] } } }

Note: If you don't have uvx, you can use pip install oswright and then set "command": "oswright" directly.

Claude Desktop

Follow the MCP install guide, use the standard config above.

Claude Code

claude mcp add oswright uvx oswright

VS Code

Add to your user or workspace settings.json under mcp.servers:

{

"mcp": { "servers": { "oswright": { "command": "uvx", "args": ["oswright"] } } } }

Or use the VS Code CLI:

code --add-mcp '{"name":"oswright","command":"uvx","args":["oswright"]}'

Cursor

Go to Cursor Settings -> MCP -> Add new MCP Server. Name it oswright, use command type with the command uvx oswright.

Windsurf

Follow Windsurf MCP documentation. Use the standard config above.

Cline

Add to your cline_mcp_settings.json:

{

"mcpServers": { "oswright": { "type": "stdio", "command": "uvx", "args": ["oswright"], "disabled": false } } }

Goose

Go to Advanced settings -> Extensions -> Add custom extension. Name it oswright, use type STDIO, and set the command to uvx oswright.

Using pip instead of uvx

If you prefer a standard pip install:

pip install oswright

Then use this config:

{

"mcpServers": { "oswright": { "command": "oswright" } } }

Or run directly:

python -m oswright

Agent skill

skills/oswright/SKILL.md tells an agent when to reach for OSWright and which tools are the cheap ones. It follows the open Agent Skills format. Copy the skills/oswright folder into your agent's skills directory — ~/.claude/skills/ for Claude Code, or the equivalent for your client.

The skill sets --observation-mode delta. Without it, every action returns a full screenshot, which is the cost OSWright exists to avoid.

Incremental perception

Most GUI agents re-perceive the entire screen on every step: full screenshot, full OCR, then hand the model a fresh image. Measured on a live desktop, the median observation changes 0.012% of pixels — so a full rescan does roughly 240× more work than the change warrants, and the screenshot it returns costs ~2,800 image tokens whether anything happened or not.

OSWright keeps a model of the screen between observations and rescans only the regions that actually moved.

observe()  ->  {"changed": true,

"added": [{"text": "Saved", "x": 812, "y": 447}], "removed": ["Unsaved changes"], "screen_fraction_scanned": 0.015}

Measured on this machine over a 14-step agent loop:

The busier the screen, the larger the gap: full OCR scales with how much text is on screen, whereas the incremental path scales with how much *changed*. The same comparison measures 6.5× on a quiet desktop and 14.3× with a dense web page open. Re-measure with benchmarks/ rather than trusting these.

Cost is a proxy, though, and a cheaper perception path that quietly degraded accuracy would be worse than none. So it is checked against task completion: scripted tasks driving the real tool surface across four applications, graded against each application's own state — UI Automation for Calculator and Explorer, the window title for Chrome and VS Code — never against OCR.

Accuracy is identical across every configuration while token cost falls 23×. Run it with python benchmarks/bench_tasks.py.

Why both pixels and accessibility

The design bets that neither perception path wins everywhere. Turning each half off measures that rather than asserting it:

Accessibility-only — the posture most Windows GUI agents take — is perfect on XAML and blind on a Win32 list view and on web content. Probed against VS Code it sees 18 elements, the entire IDE being a single node named Chrome Legacy Window, while OCR reads 94 including every filename.

Pixels-only fails Calculator's buttons, because the button a human reads as 7 is *named* Seven, and Windows OCR returns no digits from Calculator at all.

The cascade is the only configuration that passes everywhere.

The resolution cascade

find_element and click_element stop at the first method that can answer, so cost tracks how *novel* the request is rather than how large the screen is:

Looking up text the model already knows is ~5,000× cheaper than the v0.4.0 path (0.05 ms versus 244 ms). The response reports which rung answered, so you can see what a task is actually costing.

Rung 3 is worth understanding: UIA's TextRange.FindText searches the application's *own* text buffer and returns exact bounding rectangles. It is immune to font, DPI, antialiasing and OCR error. It sits below the pixel rungs only because scanning a window's controls for it costs a few hundred milliseconds of cross-process COM — it is the accurate rung, not the fast one.

Note on ordering. These rungs are ordered by *measurement*, not by theory.

The common advice is to make the accessibility tree primary, but on real

applications it is not always cheaper: walking Chrome's tree took 537 ms here,

slower than a full-screen OCR pass, and VS Code exposed only 18 elements to it.

Neither pixels nor accessibility wins everywhere, which is why this is a

cascade rather than a choice.

Asking the compositor instead of looking

On Windows, the desktop compositor already knows which pixels changed and exposes them through DXGI Desktop Duplication. Asking it costs 0.14 ms and transfers no pixels, against tens of milliseconds to capture a frame and discover it was identical — so an idle observation skips the capture entirely.

When something *has* changed, the compositor is left holding that frame, so its pixels are read directly from the GPU rather than grabbed a second time through a different API — 1.5–2.3× faster than mss in measurements here.

The compositor is used only as a fast *negative* for change detection. When it reports a change, the dirty regions still come from hashing the captured frame: the two are measured over slightly different intervals, so compositor rectangl