Home › Sources › Let Claude use your computer from the CLI

Let Claude use your computer from the CLI

Tags

official-docs claude-code-cli

Content

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Let Claude use your computer from the CLI

Enable computer use in the Claude Code CLI so Claude can open apps, click, type, and see your screen on macOS. Test native apps, debug visual issues, and automate GUI-only tools without leaving your terminal.

{/ plan-availability: feature=computer-use plans=pro,max /}

Computer use is a research preview on macOS that requires a Pro or Max plan. It is not available on Team or Enterprise plans. It requires Claude Code v2.1.85 or later and an interactive session, so it is not available in non-interactive mode with the -p flag.

Computer use lets Claude open apps, control your screen, and work on your machine the way you would. From the CLI, Claude can compile a Swift app, launch it, click through every button, and screenshot the result, all in the same conversation where it wrote the code.

This page covers how computer use works in the CLI. For the Desktop app on macOS or Windows, see computer use in Desktop.

What you can do with computer use

Computer use handles tasks that require a GUI: anything you'd normally have to leave the terminal and do by hand.

When computer use applies

Claude has several ways to interact with an app or service. Computer use is the broadest and slowest, so Claude tries the most precise tool first:

Screen control is reserved for things nothing else can reach: native apps, simulators, and tools without an API.

Enable computer use

Computer use is available as a built-in MCP server called computer-use. It's off by default until you enable it.

In an interactive Claude Code session, run:

```text theme={null}
/mcp
```

Find `computer-use` in the server list. It shows as disabled.

Select computer-use and choose Enable. The setting persists per project, so you only do this once for each project where you want computer use.

The first time Claude tries to use your computer, you'll see a prompt to grant two macOS permissions:

* **Accessibility**: lets Claude click, type, and scroll
* **Screen Recording**: lets Claude see what's on your screen

The prompt includes links to open the relevant System Settings pane. Grant both, then select **Try again** in the prompt. macOS may require you to restart Claude Code after granting Screen Recording.

After setup, ask Claude to do something that needs the GUI:

```text theme={null} Build the app target, launch it, and click through each tab to make sure nothing crashes. Screenshot any error states you find.


## Approve apps per session

Enabling the `computer-use` server doesn't grant Claude access to every app on your machine. The first time Claude needs a specific app in a session, a prompt appears in your terminal showing:

* Which apps Claude wants to control
* Any extra permissions requested, such as clipboard access
* How many other apps will be hidden while Claude works

Choose **Allow for this session** or **Deny**. Approvals last for the current session. You can approve multiple apps at once when Claude requests them together.

Apps with broad reach show an extra warning in the prompt so you know what approving them grants:

| Warning                    | Applies to                                                   |
| :------------------------- | :----------------------------------------------------------- |
| Equivalent to shell access | Terminal, iTerm, VS Code, Warp, and other terminals and IDEs |
| Can read or write any file | Finder                                                       |
| Can change system settings | System Settings                                              |

These apps aren't blocked. The warning lets you decide whether the task warrants that level of access.

Claude's level of control also varies by app category: browsers and trading platforms are view-only, terminals and IDEs are click-only, and everything else gets full control. See [app permissions in Desktop](https://code.claude.com/en/desktop#app-permissions) for the complete tier breakdown.

## How Claude works on your screen

Understanding the flow helps you anticipate what Claude will do and how to intervene.

### One session at a time

Computer use holds a machine-wide lock while active. If another Claude Code session is already using your computer, new attempts fail with a message telling you which session holds the lock. Finish or exit that session first.

### Apps are hidden while Claude works

When Claude starts controlling your screen, other visible apps are hidden so Claude interacts with only the approved apps. Your terminal window stays visible and is excluded from screenshots, so you can watch the session and Claude never sees its own output.

When Claude finishes the turn, hidden apps are restored automatically.

### Screenshots are downscaled automatically

Claude Code downscales every screenshot before sending it to the model. You don't need to lower your display resolution or resize windows on Retina or other high-resolution displays. A 16-inch MacBook Pro at native Retina resolution captures at 3456×2234 and downscales to roughly 1372×887, preserving aspect ratio.

There is no setting to change the target size. If on-screen text or controls are too small for Claude to read after downscaling, increase their size in the app rather than changing your display resolution.

### Stop at any time

When Claude acquires the lock, a macOS notification appears: "Claude is using your computer · press Esc to stop." Press `Esc` anywhere to abort the current action immediately, or press `Ctrl+C` in the terminal. Either way, Claude releases the lock, unhides your apps, and returns control to you.

A second notification appears when Claude is done.

## Safety and the trust boundary

<Warning>
  Unlike the [sandboxed Bash tool](https://code.claude.com/en/sandboxing), computer use runs on your actual desktop with access to the apps you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the trust boundary is different. See the [computer use safety guide](https://support.claude.com/en/articles/14128542) for best practices.
</Warning>

The built-in guardrails reduce risk without requiring configuration:

* **Per-app approval**: Claude can only control apps you've approved in the current session.
* **Sentinel warnings**: apps that grant shell, filesystem, or system settings access are flagged before you approve.
* **Terminal excluded from screenshots**: Claude never sees your terminal window, so on-screen prompts in your session can't feed back into the model.
* **Global escape**: the `Esc` key aborts computer use from anywhere, and the key press is consumed so prompt injection can't use it to dismiss dialogs.
* **Lock file**: only one session can control your machine at a time.

## Example workflows

These examples show common ways to combine computer use with coding tasks.

### Validate a native build

After making changes to a macOS or iOS app, have Claude compile and verify in one pass:

```text theme={null}
Build the MenuBarStats target, launch it, open the preferences window,
and verify the interval slider updates the label. Screenshot the
preferences window when you're done.

Claude runs xcodebuild, launches the app, interacts with the UI, and reports what it finds.

Reproduce a layout bug

When a visual bug only appears at certain window sizes, let Claude find it:

```text theme={null} The settings modal clips its footer on narrow windows. Resize the app window down until you can reproduce it, screenshot the clipped state, then check the CSS for the modal container.


Claude resizes the window, captures the broken state, and reads the relevant stylesheets.

### Test a simulator flow

Drive the iOS Simulator without writing XCTest:

```text theme={null}
Open the iOS Simulator, launch the app, tap through the onboarding
screens, and tell me if any screen takes more than a second to load.

Claude controls the simulator the same way you would with a mouse.

Differences from the Desktop app

The CLI and Desktop surfaces share the same computer use engine, with a few differences:

Feature Desktop CLI
Platforms macOS and Windows macOS only
Enable Toggle in Settings > General (under Desktop app) Enable computer-use in /mcp
Denied apps list Configurable in Settings Not yet available
Auto-unhide toggle Optional Always on
Dispatch integration Dispatch-spawned sessions can use computer use Not applicable

Troubleshooting

"Computer use is in use by another Claude session"

Another Claude Code session holds the lock. Finish the task in that session or exit it. If the other session crashed, the lock is released automatically when Claude detects the process is no longer running.

macOS permissions prompt keeps reappearing

macOS sometimes requires a restart of the requesting process after you grant Screen Recording. Quit Claude Code completely and start a new session. If the prompt persists, open System Settings > Privacy & Security > Screen Recording and confirm your terminal app is listed and enabled.

computer-use doesn't appear in /mcp

The server only appears on eligible setups. Check that:

See also