Deskwright MCP server

Deskwright

Computer use for AI agents on GNOME Wayland.

Let your coding agent use your Linux desktop. Or give it one of its own, so it stops stealing your mouse.

Install  •  What it can do  •  A desktop of its own  •  When something's off  •  Security

<!-- demo.gif goes here: split screen, you typing on the left, the agent driving apps on a virtual monitor on the right, uninterrupted. -->

Claude Code can edit your files and run your commands. It can't open GIMP, click a button in a settings dialog, or read what a native app is showing you. On macOS and Windows it can, through computer use. On Linux that's still on Anthropic's list.

This fills the gap on GNOME. It's an MCP server plus a small shell extension, and it hands an agent the actual desktop: launching apps, reading widgets, clicking, typing, dragging, window management, OCR and screen recording. Any MCP client can drive it. Claude Code, Codex, Cursor, your own script.

The part people tend to like most: DESKWRIGHT_SESSION=headless runs all of it on a virtual monitor that isn't on any of your screens. Your agent gets a real GNOME desktop to work on, and it never takes your focus.

Why this exists

Wayland deliberately stops an application from seeing or touching any other window. That's a good rule, and it's why xdotool, wmctrl and grim either do nothing on GNOME or fail in ways that look like your own mistake. Every Linux computer-use project I found either shipped a Docker container running X11, or quietly assumed X11 and broke.

So I went looking for what GNOME actually permits, and it turns out to be quite a lot, just not where anyone looks. Mutter answers D-Bus. AT-SPI, the accessibility layer built for screen readers, exposes every real widget in every running app with its name, its role and the action it performs. And a shell extension runs inside gnome-shell itself, where the rest lives.

That middle one matters more than it sounds. Pressing a widget's own accessibility action isn't a nicer way to click. It's a different thing: it can't miss, it survives the window moving, and it needs no pointer at all. An agent working this way stops guessing at coordinates, and stops taking a screenshot after every action to find out what happened.

Install

You need GNOME Shell on Wayland. Check with echo $XDGCURRENTDESKTOP $XDGSESSIONTYPE, which should mention GNOME and wayland.

The lazy way: hand it to your agent

Open Claude Code, or Codex, or whatever you use, and say:

Set up https://github.com/tristanmuzzu/deskwright on this machine,

follow the AGENTS.md.

AGENTS.md is a runbook written for agents. Every command, how to check each one worked, the right package names for Debian, Fedora and Arch, and the handful of things that go wrong with their fixes. Your agent will ask you for a sudo password once and tell you to log out once. That's your whole involvement.

By hand: two commands and a logout

pipx install --system-site-packages deskwright
deskwright-setup

deskwright-setup narrates every step. It turns on the accessibility flag, installs the bundled shell extension, and tells you about any missing system package with the right install line for your distro, so you're never guessing at package names. It never runs sudo itself.

Shortened. The full README is on GitHub.