[DOCS] Computer use docs missing multi-monitor display-switching guidance

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/desktop

Section/Topic

Let Claude use your computer, especially the overview/setup guidance for users working on multi-monitor desktops

Current Documentation

The docs currently say:

Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to test a native app in the iOS simulator, interact with a desktop tool that has no CLI, or automate something that only works through a GUI.

Computer use is off by default. Enable it in Settings and grant the required macOS permissions before Claude can control your screen.

And the computer-use tool reference currently says:

The computer use tool supports these actions:

• screenshot - Capture the current display
• left_click - Click at coordinates [x, y]
• type - Type text string
• key - Press key or key combination (for example, "ctrl+s")
• mouse_move - Move cursor to coordinates
• scroll - Scroll in any direction with amount control
• left_click_drag - Click and drag between coordinates
• right_click, middle_click - Additional mouse buttons
• double_click, triple_click - Multiple clicks
• left_mouse_down, left_mouse_up - Fine-grained click control
• hold_key - Hold down a key for a specified duration (in seconds)
• wait - Pause between actions
• zoom - View a specific region of the screen at full resolution. Requires enable_zoom: true in tool definition. Takes a region parameter with coordinates [x1, y1, x2, y2] defining top-left and bottom-right corners of the area to inspect.

| display_number | No | Display number for X11 environments |

What's Wrong or Missing?

Changelog v2.1.85 says:

Fixed switch_display in the computer-use tool returning "not available in this session" on multi-monitor setups

The current docs do not explain multi-monitor behavior for Claude Code computer use.

That leaves three user-visible gaps:

A. Multi-monitor support is not described at all

The desktop page describes Claude controlling "your screen" in the singular, but does not tell users whether computer use can work across more than one display.

B. Display switching during a session is undocumented

The changelog confirms there is display-switching behavior in computer use, but neither the desktop page nor the computer-use tool reference explains how Claude moves between displays, when that is supported, or what users should expect on multi-monitor setups.

C. The relationship between display_number and display switching is unclear

The platform reference exposes display_number for X11 environments, but it does not explain whether that is the only multi-display mechanism or how it relates to the switch_display behavior fixed in v2.1.85.

Suggested Improvement

Add a short multi-monitor subsection to https://code.claude.com/docs/en/desktop under computer use that explains:

1. whether Claude Code computer use supports multiple displays,
2. whether Claude can switch to another monitor during a session,
3. any setup limitations or expectations for multi-monitor desktops.

Also update the computer-use tool reference to clarify the developer-facing behavior. If switch_display is a public action, document it alongside the other available actions. If it is an internal implementation detail, the reference should still explain how multi-display selection works in practice and how it relates to display_number.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Context
https://code.claude.com/docs/en/desktop	Primary Claude Code computer-use page; currently explains enabling screen control but not multi-monitor support or display switching
https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool	Cross-reference for the computer-use tool; lists actions and display_number, but does not document switch_display or other multi-monitor session behavior

Total scope: 2 pages affected

Source: Changelog v2.1.85

Exact changelog entry:

Fixed switch_display in the computer-use tool returning "not available in this session" on multi-monitor setups

[coygeek]

Quickly checked the current docs mirror again and this still appears unresolved. I still do not see multi-monitor/display-switching guidance in the Claude Code computer-use docs, and the platform computer-use reference still does not document switch_display behavior or how it relates to multi-display sessions.

[m13v]

i maintain a macOS automation layer that drives clicks and keyboard input across multiple displays daily, and the multi-monitor coordinate problem is way more subtle than docs usually capture. the core issue is that macOS uses a global coordinate system where the primary display origin is (0,0) and secondary displays have negative Y values or offset X depending on arrangement. screenshot pixel coordinates don't map 1:1 to global screen coordinates because of Retina scaling (2x on most Macs) plus the window origin offset. so if you screenshot a secondary monitor and try to click at pixel (500, 300) from that image, you're off by the display origin plus the scale factor. i'd suggest the docs at minimum clarify: which display is captured by default, whether switch_display resets the coordinate space or keeps global coords, and how Retina 2x scaling interacts with click targets on non-primary displays.

[coygeek]

Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.

[coygeek]

Verified against the latest docs; this still appears unresolved.

[coygeek]

Verified against the latest docs; this still appears unresolved.