On for every account and every session type. The official build's own Linux Computer Use is a staged rollout that needs a RemoteDesktop portal and skips wlroots; our bundled bridges take precedence. Claude Desktop's built-in Computer Use MCP server exposes 27 tools for desktop automation (screenshot, click, type, scroll, drag, clipboard, and more). The learn tools (learn_application, learn_screen_region) generate interactive overlay tutorials that walk through any application's UI step by step.
Example prompt: "Can you use computer use MCP to explain me the PhpStorm application?"
How it works on Linux: upstream Computer Use is macOS-only - gated behind process.platform==="darwin", macOS TCC permissions, and a native Swift executor. The patch (fix_computer_use_linux.nim) removes the platform gates, routes both upstream executor factories to an injected Linux executor, leaves the OS-permission step to upstream, which reports it granted on Linux itself, and auto-detects your session type to route to a bundled first-party bridge: x11-bridge on X11 / XWayland, wlroots-bridge on Sway / Hyprland / Niri, gnome-portal-bridge on GNOME Wayland, and kwin-portal-bridge on KDE Wayland. The bridges ship inside the package, so X11, XWayland, Sway / Hyprland / Niri, GNOME Wayland on PipeWire >= 1.0.5 (Ubuntu 24.04+, Fedora 40+, Debian 13+) and KDE Plasma 6.6+ need nothing installed. Older GNOME and KDE sessions, NixOS GNOME / KDE and exotic compositors take a fallback; Computer Use dependencies has the matrix, how each bridge works and the fallbacks. The app also reports Computer Use to claude.ai as rolled out on Linux (enable_local_agent_mode.nim forces the computerUseRollout feature), so Team and Enterprise accounts without a web rollout get the Settings -> System -> Computer use section with its Enable computer use switch instead of "Computer use isn't available on the Team and Enterprise plans yet". Turn that switch on once; Code sessions on this computer and Cowork tasks then carry the computer-use tools (claude.ai lists Computer Use for those two session kinds; a plain chat reaches a computer only through claude.ai's own device linking). Organization compliance settings are honoured as on macOS and Windows: when your org restricts Computer Use, the server is not registered and, if the restriction lands mid-session, every further tool call is refused with the same message upstream shows; claude.ai checks that compliance lock before the rollout, so it is not lifted by the override. An administrator's computerUseEnabled: false in the managed settings (/etc/claude-desktop/managed-settings.json) turns Computer Use off on Linux as it does on macOS and Windows; unset, Computer Use stays on.
Notes:
-
Typing emoji. On sway, Hyprland and niri, Claude types through the bridge's virtual keyboard, which Chromium and Electron apps on native Wayland read with 16 bits per character: an emoji or another character beyond U+FFFF would arrive as a different character. Claude therefore pastes such characters through the clipboard (Ctrl+V; your clipboard is put back afterwards) and types the rest of the text normally. In a terminal, or when the app in front cannot be named, the text is typed as before. Other desktops type every character as before.
-
Long texts on X11. The time allowed for typing grows with the text (5 s plus 15 ms per character, more for characters outside the keyboard layout, never less than 15 s). When the bundled
x11-bridgeis stopped part-way (that time ran out, or the keyboard layout changed while it typed), only the characters it did not type yet are typed again, at most three times and only while it makes progress, so nothing is typed twice. An olderx11-bridgeor a customX11_BRIDGE_BINwithout that report fails as before.claude-patches.loghas a[claude-cu] x11-bridge type: stopped after N of M charactersline. -
Which monitor. Screenshots and clicks target the primary display; use
switch_displayto target another. With two or more monitors a screenshot names the monitor it shows and the other ones ("This screenshot was taken on monitor ..."), with the namesswitch_displaytakes, as Anthropic's own code does: monitors with the same name (both "Unknown Display" in a VM, two identical monitors) are told apart as "Unknown Display (2)", and a name too long or odd to pass on becomes "display N".switch_displaytakes such a name in any case, a monitor's own label when no other monitor has it, or its number. On X11 the "Claude is using your computer" glow and the teach overlay follow the monitor Computer Use works on, in every session type, Code sessions and local Cowork included: each screenshot on another monitor and eachswitch_displaymoves them there, and the session keeps that monitor for its next turn (before one is chosen, the monitor the Claude window is on; afterswitch_displaywithauto, the primary until the next screenshot). On a background display they stay off the user's monitors. When Anthropic enables its drawn pointer for an account, the glow on X11 with a compositing manager shows a thin rim and Claude's own arrow, which glides to each click target before the click (in every session type; not for a click that is refused, not while another Computer Use call runs alongside it, as upstream), is followed by the real pointer and shows a ring on each press; the real pointer stays visible. The screenshots Claude receives do not contain the arrow, its press ring or the "Claude is using your computer" badge (they are hidden for the instant of each capture, on X11 and on the Wayland overlay below); the rim or the glow stays up and may be visible at the screen edges (on GNOME Wayland it is hidden too, see The glow). Settings -> Extra -> Cowork (Linux) -> Computer Use -> Options has a Drawn cursor in the glow row for that Anthropic flag (1916550538): it follows Anthropic unless you force it on or off, and it uses the same override as Settings -> Extra -> Anthropic. Upstream shows neither on a Wayland session, also when Claude runs on XWayland; The glow below says what is drawn there. On KDE Wayland the bridge draws the teach steps, and on GNOME Wayland there is no teach overlay that could be placed on a specific monitor. In cloud Cowork, Dispatch and on KDE Wayland, once apps are approved the next screenshot goes to the monitor holding most of their visible windows, as on macOS; it is picked again whenever the approved apps change, unless Claude chose a monitor withswitch_display. This needs window positions: X11 (and XWayland with Electron on XWayland) and KDE Wayland report them; on GNOME Wayland and on sway, Hyprland and river the bridges report none, so the screenshot stays on the default monitor.claude-patches.loghas one[claude-cu] display auto-target:line per decision. On GNOME Wayland the default is the monitor shared in the "Remote Desktop" consent dialog instead: with several monitors, share all of them there, otherwise only the shared one is used by default. To change the selection later (GNOME and KDE Wayland), runclaude-desktop --reset-screen-sharing; the next Computer Use task shows the dialog again. When Claude reports a monitor as not shared, it asks you to run the same command. Clicking "Stop sharing" in the desktop's screen-sharing indicator (GNOME and KDE Wayland) stops Computer Use: Claude asks you before continuing, and the block is lifted when the task ends (the app checks the session's state every 10 seconds, so within about 10 seconds of the turn end, and immediately when the page or Claude releases Computer Use) or after about 2 minutes without Computer Use actions. The bridge session itself also ends at those points, so the desktop's screen-sharing indicator disappears; the next action shares again without a dialog once the selection is remembered. -
The glow. "Claude is using your computer" shows while Claude holds the Computer Use lock:
- X11 with a compositing manager: Anthropic's own glow window, on the monitor Computer Use works on.
- sway, Hyprland and niri (Wayland), also with Claude on XWayland: drawn by the bundled
wlroots-bridge(wlroots-bridge overlay) in a click-through layer-shell overlay, once it reports it can (doctorcapabilities.overlay); an older or customWLROOTS_BRIDGE_BINwithout it shows no glow. Same look as Anthropic's glow, on the output of the monitor Computer Use works on; it followsswitch_displayand the monitor a screenshot was taken on, also when Claude chose the monitor before the task started. When Anthropic enables its drawn pointer (or the Drawn cursor in the glow row forces it on) the overlay shows the thin rim and Claude's arrow, which glides to each target exactly as on X11 (Anthropic's own glide planner), jumps while a button is held and shows a ring on each press. The real pointer stays visible; the screenshots Claude receives leave the arrow and its ring out (the bridge hides them for each capture when it supports that,ready.captureScopeswithcursor), while the rim or glow stays up at the screen edges. When the overlay build draws it (ready.badge), it also flashes the "Claude is using your computer" badge as Anthropic's glow does: in the centre of the screen, then sliding to the top-right corner over 6 seconds (not with reduced motion), once each time Claude takes Computer Use; a screenshot taken in those 6 seconds is captured with the whole overlay hidden, rim included, so the badge is never in what Claude receives. If the overlay stops twice in one task (or cannot run on the compositor), the glow stays off until the task ends;claude-patches.loghas one[claude-cu] wl-glow:line. Input, screenshots and the lock are never delayed by it. - KDE Plasma 6.6+ (Wayland): drawn by the bundled
kwin-portal-bridge(kwin-portal-bridge overlay) in the same click-through layer-shell overlay, with the same look, monitor following and drawn cursor as on sway, once itsdoctorreports bothcapabilities.overlayandcapabilities.session_overlay_opt_out(the bridge build that carries the overlay); the screen-sharing session then starts without the bridge's own glow. The bridge keeps the overlay out of every screenshot itself (KWin's "exclude from capture"), so the arrow is never in what Claude receives and captures are not delayed for it. Which of the two glows a task gets is decided when it takes Computer Use, before the screen-sharing session starts;claude-patches.loghas one[claude-cu] kwin-portal-bridge capabilities:line. An older or customKWIN_PORTAL_BRIDGE_BINwithout those keys draws its own glow while it shares the screen, without the drawn cursor. Teach mode keeps the bridge's own teach overlay; the glow stays up during teach mode, as upstream does (the overlay takes no clicks or keys, so the teach buttons work through it). - GNOME Wayland: drawn by the bundled
gnome-portal-bridge(gnome-portal-bridge overlay) once itsdoctorreportscapabilities.overlay(the bridge build that carries the overlay; an older or customGNOME_PORTAL_BRIDGE_BINwithout it shows no glow). GNOME Shell has no layer-shell, so the overlay is a set of click-through XWayland windows; it needs XWayland (GNOME starts it on demand, the first glow of a session may take a moment longer). Same look, monitor following, drawn cursor and badge as on sway; the glow is static (it does not pulse, since each pulse step would make GNOME repaint the whole screen). It is hidden in the Activities overview, sits below GNOME Shell's own dialogs and notification banners, and on a fractionally scaled monitor looks blurry unless Mutter's experimentalxwayland-native-scalingis on. Nothing on GNOME can leave an XWayland window out of a screen capture, so the whole overlay (glow, rim, arrow, ring and badge) is hidden for each screenshot and shown again right after it: the screenshots Claude receives contain none of it, and the glow blinks briefly at each screenshot. A screenshot waits up to 150 ms for GNOME to take the overlay off screen (it normally takes 50 to 65 ms). When the screen-sharing session has to be started first (the first screenshot of a task, or after it was reset), it is started before the overlay is hidden, so the glow stays up during GNOME's consent dialog and the capture follows the hide at once. - river: no glow (a river desktop is not served by
wlroots-bridge, which drives river only as a background display). - KDE Plasma before 6.6, other Wayland compositors, a background display, X11 without a compositing manager: no glow.
- Settings -> Extra -> Cowork (Linux) -> Computer Use -> Options -> Show the glow while Claude uses the computer (on by default, key
computerUseGlowinclaude-desktop-extra.json/.jsonc) turns off the glow, the rim and the drawn cursor on X11 and on the Wayland rows above, KDE Plasma and GNOME included, from the next Computer Use task; Computer Use itself works the same. It does not turn off the own glow of akwin-portal-bridgewithoutcapabilities.session_overlay_opt_out(that bridge has no option for it).
-
Scaling and layouts. X11 sessions with a scale factor (
Xft.dpi,GDK_SCALE,--force-device-scale-factor) are supported: clicks and screenshots use the same DIP-to-pixel mapping. On sway, Hyprland and river, monitors at negative offsets (left of or above the origin) and rotated or flipped monitors work. On KDE Wayland, the first Computer Use action of a session waits up to about two minutes for the consent dialog and reports it if you decline. -
App discovery (listing and opening apps, the teach overlay) reads
.desktopfiles from$XDG_DATA_HOME/applicationsand every$XDG_DATA_DIRS/applications(which covers NixOS profiles, snap and/usr/local), plus the Flatpak export dirs, registering each with multiple name variants for flexible matching; a match on the app's name or desktop id wins over one on its executable name. On wlroots, GNOME and X11 sessionsopen_applicationruns the launcher's fullExecline as the Desktop Entry spec defines it (field codes, quoting,Path=,TryExec), so Flatpak apps, Chromium web apps andenv-wrapped launchers start correctly. When a launcher has no usableExec, isTerminal=true, or its binary is missing, it falls back to whichever ofgio launch,gtk-launch,kioclient6/kioclient5 execandexo-openis installed (plusxdg-terminal-exec,x-terminal-emulator -eor$TERMINAL -efor terminal apps); none of them is required. -
Which
PATH. Apps are found on thePATHClaude Desktop was started with, so launchers whoseExecnames a program in~/.local/bin,~/.nix-profile/binor a home-manager profile open, on your desktop and on the background display. The tools Computer Use runs itself (setsid, the launcher tools above, the clipboard tools,ydotool, ...) come from system folders and from root-managed read-only folders on thatPATH: on NixOS the system profile and/etc/profiles/per-user/<you>(users.users.<you>.packagesand the home-manager NixOS module); a standalone home-manager or~/.nix-profileis managed by your user and is not used for tools. A tool found only in a folder your user can write to counts as missing, andclaude-patches.lognames the folder it ignored: install the tool system-wide (your package manager; on NixOSenvironment.systemPackagesorusers.users.<you>.packages), or as root in/usr/local/bin. URLs and files open through the systemxdg-open. -
Teach mode (the learn tools' overlay tours) works on X11 (with a compositing manager, see below) and on KDE Plasma Wayland, where it follows the account's teach-mode setting; it is not available on wlroots or GNOME sessions and is refused on the background display.
-
One session at a time. Every session type takes Anthropic's Computer Use lock: a Code session or a local Cowork task takes it at its first Computer Use action of a turn and releases it when the turn ends, also on Stop and errors. The access tools (
request_access,list_granted_applications,list_apps),wait,switch_display, a batch of onlywait/switch_displayand the app-scoped accessibility tools (app_list_windows,app_ax_find,app_click,app_type) do not take it. A call that arrives after its turn ended (for example from a background subagent of Claude Code) is answered " aborted (user interrupt)." and takes nothing. While Claude holds the lock:- the Claude window un-maximizes, docks at the top right, stays above other windows for the turn and takes focus back at the end (tiling window managers may ignore the move). When the window manager applies the un-maximize only after the dock (seen on GNOME Wayland) and the window comes back large, the dock size is asked for once more; if it still does not hold,
claude-patches.loghas a[claude-cu] dock:line saying Claude's window may cover part of the screen. On X11 it stays clickable, so Stop in the docked panel works; Claude's own clicks on it are refused ("the Claude overlay intercepted the hit test"); - the "Claude is using your computer" glow shows (see The glow above), and the turn's first screenshot, and the check of its first click target, wait until the window has docked;
- Escape and Stop sharing stop the turn as described under Stopping Computer Use;
- on GNOME Wayland the screen-sharing session starts and ends with each turn (the indicator shows while Claude works; with the selection remembered no dialog appears);
- with Ask before Computer Use controls an app on, the note that screenshots are not filtered comes once per turn.
Another session that tries to use the computer meanwhile is told "Another Claude session is currently using the computer" and its action does not run. A cloud Cowork or Dispatch task releases the lock when the app sees its turn end; where it does not (a task whose page is not open in the app), Anthropic's idle sweep releases it after 12 minutes without Computer Use, so a Code session is refused until then.
- the Claude window un-maximizes, docks at the top right, stays above other windows for the turn and takes focus back at the end (tiling window managers may ignore the move). When the window manager applies the un-maximize only after the dock (seen on GNOME Wayland) and the window comes back large, the dock size is asked for once more; if it still does not hold,
-
Teach overlay stays interactive but blocks clicks to apps behind it during a tour (Electron's
setIgnoreMouseEventsis broken on X11).
Settings -> Extra -> Cowork (Linux) -> Ask before Computer Use controls an app (on by default). Claude names the apps it wants in request_access, and you approve them in the approval card in the chat, as on macOS. Approved apps get full control: clicks, typing and key presses, also for terminals, editors and browsers (macOS limits those to "read" or "click"). The card still offers the clipboard and system key combo checkboxes, and warns for terminals and file managers.
The switch governs Code sessions (the Code tab and local Cowork) on X11, wlroots, GNOME and the background display. Sessions that upstream runs itself already ask, whatever the switch says: cloud Cowork, Dispatch and teach mode pass their own approved apps to Computer Use, and their screenshots are masked by that list where the session can mask (see the table). Approved apps get full control in all of them on these sessions, also with the switch off. On KDE Plasma Wayland upstream handles everything.
With approval on, Computer Use refuses:
- every tool until at least one app is approved (a session without an approval card gets upstream's "not wired with a permission handler" answer, so nothing can be approved there);
- clicks, scrolls and drags on a window of an app you did not approve, and typing and key presses while such an app is in front, as far as the session can tell (see the table). A drag by hand (
left_mouse_down,mouse_move,left_mouse_up) is checked at every move and at the release; a refused release still lets go of the button; - input when the session could not tell which app is in front (the window list failed), rather than guessing; with nothing focused at all input is allowed, as upstream does;
- clipboard access and system key combos (lock screen, switch app, quit, Super on its own, XF86 keys, in any spelling the bridges accept such as
Super_Lorpage_up) unless you ticked them in the card; open_applicationand the accessibility tools for an app you did not approve.
Apps are matched by their app id (the .desktop id and its aliases), never by a window title or display name. Where the session has a hit test, a click on one of Claude's own windows is refused as well.
What screenshots show and how input is checked depends on the session:
| Session | Screenshots | Input check |
|---|---|---|
| X11, X11 background display (x11-bridge) | Only the approved apps; other windows are covered by solid rectangles | The app under the pointer (its title bar and borders count as the app) and the app in front |
| Hyprland (wlroots-bridge) | Only the approved apps, each window captured on its own: notifications, launchers and other layer-shell surfaces neither hide an approved window nor appear in the image; an approved window another window sits over is shown whole, with a note | The app under the pointer (approximate: from the compositor's window rectangles, popups and layer-shell surfaces are not seen) and the app in front |
| Sway, background display on headless sway (wlroots-bridge) | Only the approved apps; popup menus, layer-shell panels and overlays, and XWayland menus can still show over or next to an approved window; a window covered by one of them is cut away where it is covered | The app under the pointer (approximate: from the compositor's window rectangles, popups and layer-shell surfaces are not seen) and the app in front |
| Niri, river (wlroots-bridge) | The whole screen, including apps you did not approve | The app in front, also in a cloud session without window positions (with no window in front the approval level still applies: a read-only approval blocks input) |
| GNOME Wayland (gnome-portal-bridge) | The whole screen, including apps you did not approve | The app in front where GNOME gives apps the window list; on stock GNOME 41 and later it does not, and only "at least one app approved" applies |
| XWayland-only, fallback route (ydotool / spectacle) | The whole screen | Only "at least one app approved" |
| KDE Plasma Wayland (KWin mode) | Upstream's own handling: only the approved apps | Upstream's own checks; Claude always asks here, whatever the switch says |
Cloud sessions without window info. Cloud Cowork, Dispatch and chats linked to this computer run Anthropic's own access checks against the backend. Where the backend cannot tell which window is in front or under a point (GNOME Wayland, and niri and river without window positions), these sessions use the whole-screen rules of Anthropic's own Wayland code: once the access check passes (GNOME Wayland: at least one app approved, unless GNOME gives the window list, then the app in front; niri and river: the app in front, and with no window in front the approval level still applies), clicks and keystrokes go to whatever is on screen, except Claude's own windows, and list_granted_applications also lists "Entire screen"; a read-only approval still blocks input; nothing is allowed before an app is approved; typing is refused while Claude's own window has keyboard focus; input is refused while one of Claude's dialogs is open. The approval card already says the whole screen is shared. Where the backend can report windows (X11, sway, Hyprland, KDE Plasma Wayland) the per-app check stays: a click on an app that is not approved, or on the desktop, is refused. On niri and river the app in front is known, so input is still refused while an unapproved app is in front. Until the bridge has answered its first status check, Claude assumes the per-app check applies, so a click on an app that is not approved is refused from the start; the same holds while the bridge cannot reach the compositor or sway / Hyprland do not answer in time (clicks are refused and a screenshot that should show only the approved apps is refused rather than taken unfiltered). claude-patches.log gets a [claude-cu] no window info: <backend> (<reason>) line once per task when a backend answers without window info.
On sessions without a hit test (the app in front only), a click lands on whatever is under the pointer; it is refused only while an unapproved app is in front. With one of Claude's own windows in front such a click is not refused (Claude's window stands for the shared screen, as upstream treats it), but it never reaches Claude's window: Anthropic's own input guard, which the Linux backends arm around every input they send on GNOME Wayland, niri, river and the fallback Wayland paths, discards a click aimed at one. The guard covers the content of Claude's windows, not the window frame: a click on the title bar buttons (minimize, maximize, close) still acts on the window. Where that guard does not exist (an X11 session without the bundled x11-bridge) the click is refused. Typing is refused while Claude's own window has keyboard focus, in Code sessions too. Input is refused while one of Claude's dialogs (a message box or a file or folder picker) is open, in Code sessions too and again right before each input is sent; the guard does not cover those dialogs. On those desktops the guard also drops your own clicks into Claude's windows (and your keys, when Claude types or holds keys) while Claude sends input and for half a second after each action; each action there takes about 50 ms longer.
When no approved window can be shown (on another workspace, minimized, closed, or covered on sway or X11), Claude gets a text naming the reason per approved app instead of an all-grey image (Hyprland, sway and X11). An image that does show some approved apps can carry a short note about the apps that are covered or missing. When the windows change while a screenshot is taken (an app just opened or closed), the screenshot is taken once more; if that fails as well Claude is told to take it again. On Hyprland the per-window capture needs the bundled wlroots-bridge of this release; claude-desktop --diagnose shows each bridge's screenshot filter.
On Wayland sessions a web app installed as its own desktop entry (a Chromium-family --app=<url> window, also through a launcher script) is an app of its own: approving it covers only its window, and approving the browser does not include it. On X11 and XWayland its window has the browser's class and counts as the browser. A terminal app started from a desktop entry shows up under its terminal; when Claude asks for the app and only the terminal's window exists, the text tells it which app to request access to.
Masking needs a bundled bridge that supports it; an older or custom bridge (*_BRIDGE_BIN) without it gives the whole screen, and the status line says so. On X11 the masked screenshot looks through Claude's own "Claude is using your computer" glow and teach overlay (both cover the screen above every app), so the approved apps show with the glow's rim over them as on screen. An X11_BRIDGE_BIN older than the bundled x11-bridge cannot look through them; with it the glow stays off (it cannot say whether a compositing manager runs, see below), and masked screenshots taken while the teach overlay is up are refused with the reason that the approved apps are covered (claude-patches.log: does not take --ignore-window). On X11 without a compositing manager (i3, openbox, or xfwm4 with its compositor off) there is no glow: Electron cannot draw a transparent window there and would black out the screen. The app asks the bundled x11-bridge whether a compositing manager runs, at startup, at the start of every Computer Use task and with screenshots; while it does not know, the glow stays off. A compositor switched off is noticed at the start of the next task (a glow already on screen is closed within a moment), one switched on gives the glow back from the task after the next. The Claude window still shows that Computer Use is running; claude-patches.log has one [claude-cu] "Claude is using your computer" glow off: <reason> line per change. The teach overlay is the same kind of window and is not switched off: on X11 without a compositing manager it covers the work area in black during teach mode (on a VM, where it uses a dark backdrop, too), so teach mode on X11 needs a compositing manager. When the bridge cannot say whether it can mask (its doctor failed) or a masked capture fails, the screenshot is refused; it is never taken unmasked in its place.
Where screenshots show the whole screen, Claude is told so in the tool descriptions and with the first such screenshot of each task. Settings -> Extra -> Cowork (Linux) shows a line under This desktop saying which case applies to your session, from what the last screenshot actually did ("Screenshots show only approved apps", with what the mask does not cover on Sway and Hyprland, or "On this session (...) screenshots show the whole screen, including apps you did not approve").
What Claude is told about access. The system-prompt note for local sessions, the capability the Settings -> Computer use page and the enable dialog describe (per-app access), the enable-prompt card and the "Entire screen" choice follow what your session's backend really does (the choice follows whether the backend can tell which window is under a point; the Ask before Computer Use controls an app switch only matters for local sessions):
| Session | Per-app access |
|---|---|
| KDE Plasma Wayland (KWin mode) | Yes (upstream's own handling) |
| X11, X11 background display | Yes |
| Hyprland | Yes, by per-window capture |
| Sway, background display on headless sway | Yes, by masking; popups and layer-shell surfaces can still show |
| GNOME Wayland, Niri, river, fallback route (ydotool / spectacle) | No: the whole screen is visible; on GNOME the session also cannot tell which window is in front or under a point |
| Any session with Ask before Computer Use controls an app off | No (KDE Plasma Wayland excepted) |
Turn it off with the switch, or with "computerUseAskBeforeControl": false in claude-desktop-extra.jsonc in the profile's userData directory (~/.config/Claude/; a value there locks the switch). Off, every app can be controlled without asking in Code sessions: request_access answers at once, nothing is checked and screenshots show the whole screen, as in earlier versions. Cloud Cowork, Dispatch and teach mode keep upstream's own approval and masking. The change applies from Claude's next Computer Use call; tool descriptions follow in the next session.
All four bridges implement one command-line contract, which claude-desktop --diagnose and --reset-screen-sharing rely on, so they work with whatever bridges are bundled. The contract includes the optional abort-watch subcommand (x11-bridge, wlroots-bridge, kwin-portal-bridge) behind Escape stops Computer Use; each bridge's README has its own details.
See CLAUDE_BUILT_IN_MCP.md for the full tool reference, and Computer Use dependencies for the package matrix, the KDE/GNOME portal behavior notes, COWORK_SCREENSHOT_CMD, and ydotool v1.0+ setup.
When a screenshot fails. On sway, Hyprland, niri, river and GNOME Wayland the bundled bridge is the only screenshot path. On GNOME a screen-cast frame that does not arrive in time is waited for once more; when a capture still fails, Claude is told the screenshot failed and that taking it again once is reasonable; when it fails a second time in a row in the same turn, Claude is told to stop retrying and to tell you, naming claude-patches.log and COWORK_SCREENSHOT_CMD. A portal session that could not start is reported with its own advice (the session-start command to run). Electron's own screen capture is not used there: on Wayland it goes through the desktop's screen-share picker (GNOME's "share your screen" dialog, the output chooser of xdg-desktop-portal-wlr or -hyprland), which would block the tool call until someone answers it. On X11 it stays the silent last resort when x11-bridge fails, and on Wayland sessions without a bundled bridge it is the only capture path. A capture still running when the turn ends is stopped with it on every row (its bridge process is ended, no further tier runs, and the call answers that the turn ended); on a Wayland session without a bundled bridge a screen-share picker that is already open stays until it is answered, and its image is discarded. A screenshot that shows only the approved apps (sway, Hyprland and X11 with the bundled bridges, see the table above) is never taken unfiltered instead: when its capture fails, Claude is told that nothing was captured and that taking it again is reasonable, without the second-failure rule. COWORK_SCREENSHOT_CMD overrides every row.
Debugging: Computer Use patches emit [claude-cu] diagnostics: lines showing the detected session, available/missing tools, and screenshot cascade. Find them in ~/.config/Claude/logs/claude-patches.log (also printed to stderr on terminal launches) and share that file when reporting Computer Use issues. See also Debugging.
- Stop in the app stops the running task.
- Stop sharing on the GNOME or KDE screen-share indicator stops the running Computer Use turn at once (the app watches the bridge's folder in your
$XDG_RUNTIME_DIR; when the desktop session's umask left that folder group-writable, as on Ubuntu, the app sets it to 0700 first, and it never watches a folder another account could write to) (always on, in Code sessions as in local and cloud Cowork); so does the desktop ending the share itself, for example a portal restart. Like Escape and Stop, it stops the session's turn the hard way: in a Code session the Claude Code process is restarted with the next message. On X11, while Anthropic's Escape grab is registered, an Escape Claude itself presses is let through to the app (the grab is dropped for the injection and registered again right after) and never taken for yours. - Escape stops Computer Use on X11, Hyprland, sway and KDE Plasma Wayland when you switch on Escape stops Computer Use under Settings -> Extra -> Community Features or on the Extra -> Cowork (Linux) page under Computer Use -> Options (off by default; off keeps Anthropic's own handling, which on X11 takes Escape from your apps while Claude is working). What Escape does to your apps differs per desktop, and GNOME and niri have no stop key: see Escape stops Computer Use.
Cowork and Dispatch tasks that run in the cloud reach this computer's Computer Use only when the desktop has registered with a TPM-backed device key. Without read and write access to /dev/tpmrm0 (the TPM 2.0 resource manager) the desktop registers keyless, and those sessions get no computer tools ("No matching tools found"). Code tab sessions use Computer Use locally and are not affected. A computer without a TPM 2.0 cannot offer Computer Use to cloud Cowork or Dispatch; Code sessions still work there.
On Wayland, with one of the bundled bridges (KWin, GNOME or wlroots) in use, the computer tools are offered to cloud sessions as well: the announce, the call check (no "needs an Xorg session" refusal) and the approval card's app icons all follow the same answer. Sessions that fall back to ydotool or spectacle are not offered. On GNOME and on niri and river without window positions these sessions use the whole-screen rules described under Approving apps. If you turn the background display off while Claude Desktop runs and no bundled bridge remains usable, Computer Use calls from cloud Cowork and Dispatch are refused on that Wayland session until the app restarts (the tool list may still show the tools until Anthropic's code next refreshes it).
Check. Any of:
- Settings -> Extra -> Cowork (Linux) (the Cloud Cowork section shows the device key (TPM) and whether cloud Cowork and Dispatch can use this computer; the Computer Use section shows this desktop and holds our Computer Use switches (the last one, Show the glow while Claude uses the computer, says what draws the glow on this session), followed by the Drawn cursor in the glow row, which controls Anthropic's flag
1916550538and is not one of our switches; it shows what Anthropic currently serves, offers on, off or follow Anthropic (clear), says when this session shows no drawn cursor (no glow here, the own glow of a KDE bridge without the overlay, or the glow switched off), and a change is re-read on the next flag load but takes effect reliably after a restart). claude-desktop --diagnose: thedevice key (TPM),TPM access ruleandlast remote-device connectlines in the Cloud Cowork device key section.~/.config/Claude/logs/main.log:connect frame sent: device_id keyed(works) orkeyless(no computer tools).- The chat header: every claude.ai chat and Cowork session (
/chat/...and/cowork/...) shows a device icon. On a desktop without a device key it is a laptop with an X, and its popover ("No device key") says cloud tasks can't use Computer Use (screen and input) on this computer while files and commands still work, with a link that opens Settings -> Extra -> Cowork (Linux). Keyed but not linked to this chat: laptop with an amber dot. Device key state not known yet: a plain laptop. Linked chats and chats that run in the local VM show the upstream icon with an added "Linux details" row that opens the same page. Each popover carries one line on where the chat runs (cloud; for a linked chat, files and commands run in the linked computer's local Cowork VM, with its state; or the local VM on this computer).
Fix.
| Install | Action |
|---|---|
.deb, .rpm, pacman |
Settings -> Extra -> Cowork (Linux) -> Enable TPM access (shows the exact command; asks you to confirm, then for an administrator password) |
| AppImage, or no logind session | Run the command the panel shows |
| NixOS | programs.claude-desktop-extra.tpmAccess.enable = true; with imports = [ claude-desktop-extra.nixosModules.default ];, then rebuild |
| Any | Alternative: sudo usermod -aG tss $USER, then log out and back in |
Then restart Claude, open the Cowork tab so claude.ai registers this computer's TPM key (staying on Chat leaves the desktop at keyless (row_pk_no_row) even after ~/.config/Claude/device-keys/*.tpm2 is created), and start a new Cowork task; a running task keeps the tools it started with.
Security. The rule gives read/write access to /dev/tpmrm0 (the resource manager, never /dev/tpm0) to every account that logs in at this computer's screen (the active local seat), not only yours. Any program such an account runs can then use the TPM, including clearing it (which destroys TPM-sealed keys such as LUKS/systemd-cryptenroll or BitLocker keys), triggering its dictionary-attack lockout, or setting its owner or lockout password. If the TPM's lockout or owner authorization is empty, set one first: tpm2_changeauth -c lockout and tpm2_changeauth -c owner. Enable shows this in a confirmation dialog before the administrator prompt. Turn it off with Disable TPM access in the same panel (or the command it shows); access already granted lasts until you log out. The panel always shows both commands (each with its "What this does" details); the one that has nothing to do right now is greyed with the reason, and the row warns when access exists only until logout (no rule installed, not in the device's group). Uninstalling the package leaves the link in /etc/udev/rules.d/ (it stops working once the package is gone), and reinstalling makes TPM access active again; to remove it for good, use Disable TPM access before uninstalling, or delete /etc/udev/rules.d/70-claude-desktop-extra-tpm.rules.
Settings -> Extra -> Cowork (Linux) -> Computer Use: read app controls (accessibility) (off by default) gives Claude the app-scoped tools app_list_windows, app_ax_find, app_click and app_type, plus app_focus and app_scroll when the bridge offers them. app_ax_find lists a window's controls (role, name, states, position) from the desktop accessibility bus (AT-SPI), and the other tools act on a control by its [N] index, so Claude finds controls by name instead of by screenshot coordinates. With the switch off the tools do not exist and nothing touches the accessibility bus.
While a Computer Use session uses it, Claude turns the desktop accessibility service on, and turns it back off when the session ends (a crash is healed at the next start). A running screen reader is never touched. The text of password fields and terminals is never read. It needs at-spi2-core (installed with every common desktop). Switching the desktop accessibility setting on or off yourself during a Computer Use session is overridden: Claude Desktop switches it on when the tools are used and back to the previous value afterwards.
| Session | Coverage |
|---|---|
| X11 / XWayland, KDE Plasma Wayland | Controls with names, states and screen positions |
| GNOME Wayland, Sway / Hyprland / Niri | Names and actions; positions where the compositor reports them (Sway and Hyprland IPC), otherwise "position unknown" and Claude uses a screenshot to click. On GNOME, XWayland apps report positions as unknown |
GTK, Qt, Firefox and LibreOffice apps expose their controls. Electron and Chromium apps expose almost nothing unless started with --force-renderer-accessibility; Claude uses screenshots there. Every missing piece (no at-spi2-core, no matching window) gives a plain "unavailable" answer and normal Computer Use carries on.
Stable element numbers. The [N] of a control stays the same across listings of its window for the rest of the task, so Claude can keep using a number after listing again. Before an action the bridge checks that the control is still the one that was listed (role, name and accessible id). A control the app re-created is found again only when that is unambiguous: the same accessible id and name, or a role and name that only one control has. Otherwise the tool says the element is gone, nothing is sent, and Claude lists the window again. A different process behind the window is never matched.
What was sent. Every action result says which of three things happened: refused before sending (nothing reached the app, safe to retry), sent and confirmed, or sent but not confirmed (Claude checks with a new listing or a screenshot before repeating it).
Waiting. app_ax_find with wait_for re-checks the window until a control appears or goes (appears, gone), or changes state (enabled, checked, unchecked, expanded, collapsed, focused, value_contains), for up to 15 seconds (5 by default; a last check may add about a second), then lists the window and says whether the condition was met or timed out. The wait ends early on Stop, when another Claude session takes over the computer, when screen sharing is stopped, when the session's accessibility use ends, or when the app's grant no longer allows the call.
Large windows. app_ax_find can list only what is inside one container (within), limit the depth (depth), list containers with their child counts (outline), or include labels and other plain text (include_text).
More actions. app_click with ensure brings a control into a state (checked, unchecked, expanded, collapsed, selected) and checks the result; when the control already is in that state nothing is sent and the result says so. app_focus gives a control keyboard focus. app_scroll scrolls a control into view. app_type with a number sets a slider's or spin button's value (outside its range, nothing is sent).
Limits.
- Rows and cells in lists and trees are not expanded or selected through a fallback click: the tool refuses and Claude uses the pointer.
- A Qt combo box whose popup is a native window on Wayland needs pointer input; the tool refuses and Claude clicks it.
- Where a control has no accessibility way to do something, the result says so and Claude uses the pointer.
- The new parameters and the two extra tools are offered only when the bridge lists the matching features (
ax-features). An older or third-party bridge (KWIN_PORTAL_BRIDGE_BINand the like) keeps the four tools and the earlier behavior, including numbers that are replaced by each listing.
By default Computer Use acts on your own desktop: Claude's mouse and keyboard are yours, so you cannot work while it runs. The Computer Use on a background display switch (Settings -> Extra -> Cowork (Linux), marked Experimental) moves it to a second display.
- Display 1 is your desktop - where you chat with Claude and keep working.
- Display 2 is a separate display that you start yourself: an invisible X server (Xvfb), an X server in a window (Xephyr), or a headless or nested wlroots compositor (sway, labwc). Claude opens apps there, clicks, types and takes screenshots there. It never moves your mouse or takes your focus.
Use it to let Claude work in the background while you keep your desktop, to keep Claude away from what is open on your desktop, or to run a task on a machine with no free screen. Switch the feature off (or leave it off) and Computer Use behaves as before, with no restart. Display 2 works the same on every host session (X11, XWayland, Sway / Hyprland / Niri, GNOME, KDE). You start and stop it; the app never does.
Display 2 is required, never optional. While the switch is on and display 2 is not running, every Computer Use action is refused with a message saying so; Computer Use never falls back to your desktop. Your own display (the one Claude Desktop runs on) is never selectable.
Pick one. The setup panel (Settings -> Extra -> Cowork (Linux) -> the row's setup page) shows these recipes with a free display number filled in, and installs hints for what is missing on your machine.
Xvfb plus a window manager (invisible; the window manager lets Claude switch between windows):
Xvfb :99 -screen 0 1600x900x24 -nolisten tcp &
DISPLAY=:99 openbox & # or xfwm4Xephyr (display 2 as a window on your desktop, handy to watch what Claude does):
Xephyr :98 -screen 1600x900 -no-host-grab &
DISPLAY=:98 openbox &Headless sway (invisible Wayland; the new wayland-N socket shows up in the panel's list):
env -u WAYLAND_DISPLAY -u DISPLAY WLR_BACKENDS=headless WLR_RENDERER=pixman WLR_LIBINPUT_NO_DEVICES=1 sway &A nested sway (started inside your own session without WLR_BACKENDS=headless) or labwc works the same way. On NixOS, programs.claude-desktop-extra.backgroundDisplay runs a headless sway as a user service, with a browser, a keyring and optional wayvnc: see NixOS background display. If sway starts XWayland for its apps, give Claude the DISPLAY it picked through env (see below).
| Distro family | Xvfb | Xephyr | window manager | sway | x11vnc / wayvnc |
|---|---|---|---|---|---|
| Arch | xorg-server-xvfb |
xorg-server-xephyr |
openbox, xfwm4 |
sway |
x11vnc, wayvnc |
| Debian / Ubuntu | xvfb |
xserver-xephyr |
openbox, xfwm4 |
sway (1.7+) |
x11vnc, wayvnc |
| Fedora | xorg-x11-server-Xvfb |
xorg-x11-server-Xephyr |
openbox, xfwm4 |
sway |
x11vnc, wayvnc |
| RHEL 9 and clones | xorg-x11-server-Xvfb (AppStream, no extra repo) |
- | openbox (EPEL) |
not in the base repos: use Xvfb | x11vnc (EPEL) |
| NixOS | nix shell nixpkgs#xvfb nixpkgs#openbox |
nixpkgs#xorg-server (older channels: xorg.xorgserver) |
nixpkgs#openbox |
nixpkgs#sway |
nixpkgs#x11vnc, nixpkgs#wayvnc |
On immutable distros (Bazzite, Silverblue, SteamOS) install the tools in a distrobox container and start display 2 there. The X socket in /tmp/.X11-unix and the Wayland socket in $XDG_RUNTIME_DIR are visible to the host when the container shares them (distrobox does by default), so the panel finds them. Apps Claude starts run on the host, which is also where Claude Desktop runs.
Open Settings -> Extra -> Cowork (Linux) -> Computer Use on a background display. The setup page lists the displays it finds (your own is labelled "your desktop" and cannot be chosen), each with size, outputs, whether it is supported and a live preview, shows the restrictions that apply on this machine right now, and has a Test button that takes a screenshot and moves the pointer on the chosen display. Choose a display, switch it on; it applies from Claude's next Computer Use action.
The same setting is the computerUseBackgroundDisplay key in claude-desktop-extra.jsonc in the profile's userData directory (~/.config/Claude/; per profile, so a named profile has its own). A key set in the .jsonc wins over the page and makes the page read-only:
env carries what display 2 needs beyond its display name, for example the XWayland DISPLAY of a headless sway, an XAUTHORITY, or a private DBUS_SESSION_BUS_ADDRESS (see the limits below). Values are strings; PATH, CLAUDE_ELECTRON and LD_* are rejected. The page never writes env (it keeps what you wrote); choosing a different display on the page drops it, because it belongs to one display.
Attach a VNC viewer to display 2 (the panel has both recipes):
x11vnc -display :99 -localhost -nopw -forever & # X display, then connect to localhost:5900
WAYLAND_DISPLAY=wayland-1 wayvnc 127.0.0.1 5901 & # Wayland display, then connect to localhost:5901With Xephyr the window itself is the view.
- Single-instance apps open on your desktop. An app that is already running on display 1 and hands every new launch to its running instance (Firefox, Chromium, many GTK apps on the shared session D-Bus) opens its window there, not on display 2. Claude is told the app did not open on the Computer Use display and why. Close the app on your desktop first, give it a separate profile (for Firefox,
-no-remote -P <profile>), or start display 2 with its own D-Bus throughenv(DBUS_SESSION_BUS_ADDRESS; that costs the keyring, portals and notifications on display 2). - The shared session bus also means portal file choosers and desktop notifications from apps on display 2 appear on your desktop.
- No teach overlay. Teach tours would draw on your desktop, so they are refused in this mode.
- No "Claude is using your computer" glow on your desktop, since Claude is not using it.
- KDE Plasma 6.6+ picks its Computer Use mode when the app starts, so switching the feature on or off needs a restart there (the panel offers it).
- Clipboard needs
xcliporxselfor an X display andwl-clipboard(wl-copy,wl-paste) for a Wayland display, installed on your machine (system-wide, see WhichPATHabove). Without them Claude's clipboard read and write are refused with a message naming the tool; your own clipboard is never touched. - The setup page can preview and test every display it can reach except Claude's own, including another session of yours (for example a second login on
:1). - Without a
DISPLAYvariable (a pure Wayland session where Claude has no XWayland display exported), Claude cannot tell which X display number belongs to your desktop's XWayland. Do not choose that number as display 2. - Changes to the setting are noticed at Claude's next Computer Use action. An editor that rewrites
claude-desktop-extra.jsoncin place with the same size within the same second may go unnoticed until the next change on older kernels; the Settings page does not have this problem. open_applicationaccepts desktop entries and commands, not URLs, in this mode.- Window activation is limited on an X display without a window manager; run one (openbox, xfwm4) on display 2.
Headless GNOME Shell or KWin (the portal bridges need a desktop session bus and a consent dialog on a screen nobody sees), weston (no virtual-pointer or screencopy protocol), cage (a single-app kiosk) and Hyprland or niri headless (no supported headless start). The panel marks such a display as not supported and says why.
{ "computerUseBackgroundDisplay": { "enabled": true, "kind": "wlroots", // "x11" (x11-bridge, Xvfb/Xephyr) or "wlroots" (wlroots-bridge) "display": "wayland-1", // ":99" for x11; a socket name or absolute socket path for wlroots "env": { "DISPLAY": ":2" } // optional, hand-edited only: variables for every app and bridge Claude starts there } }