1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Let Claude use your computer from the CLI
6
7> 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.
8
9<Note>
10 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.
11</Note>
12
13Computer 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.
14
15This page covers how computer use works in the CLI. For the Desktop app, see [computer use in Desktop](/en/desktop#let-claude-use-your-computer).
16
17## What you can do with computer use
18
19Computer use handles tasks that require a GUI: anything you'd normally have to leave the terminal and do by hand.
20
21* **Build and validate native apps**: ask Claude to build a macOS menu bar app. Claude writes the Swift, compiles it, launches it, and clicks through every control to verify it works before you ever open it.
22* **End-to-end UI testing**: point Claude at a local Electron app and say "test the onboarding flow." Claude opens the app, clicks through signup, and screenshots each step. No Playwright config, no test harness.
23* **Debug visual and layout issues**: tell Claude "the modal is clipping on small windows." Claude resizes the window, reproduces the bug, screenshots it, patches the CSS, and verifies the fix. Claude sees what you see.
24* **Drive GUI-only tools**: interact with design tools, hardware control panels, the iOS Simulator, or proprietary apps that have no CLI or API.
25
26## When computer use applies
27
28Claude 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:
29
30* If you have an [MCP server](/en/mcp) for the service, Claude uses that.
31* If the task is a shell command, Claude uses Bash.
32* If the task is browser work and you have [Claude in Chrome](/en/chrome) set up, Claude uses that.
33* If none of those apply, Claude uses computer use.
34
35Screen control is reserved for things nothing else can reach: native apps, simulators, and tools without an API.
36
37## Enable computer use
38
39Computer use is available as a built-in MCP server called `computer-use`. It's off by default until you enable it.
40
41<Steps>
42 <Step title="Open the MCP menu">
43 In an interactive Claude Code session, run:
44
45 ```text theme={null}
46 /mcp
47 ```
48
49 Find `computer-use` in the server list. It shows as disabled.
50 </Step>
51
52 <Step title="Enable the server">
53 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.
54 </Step>
55
56 <Step title="Grant macOS permissions">
57 The first time Claude tries to use your computer, you'll see a prompt to grant two macOS permissions:
58
59 * **Accessibility**: lets Claude click, type, and scroll
60 * **Screen Recording**: lets Claude see what's on your screen
61
62 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.
63 </Step>
64</Steps>
65
66After setup, ask Claude to do something that needs the GUI:
67
68```text theme={null}
69Build the app target, launch it, and click through each tab to make
70sure nothing crashes. Screenshot any error states you find.
71```
72
73## Approve apps per session
74
75Enabling 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:
76
77* Which apps Claude wants to control
78* Any extra permissions requested, such as clipboard access
79* How many other apps will be hidden while Claude works
80
81Choose **Allow for this session** or **Deny**. Approvals last for the current session. You can approve multiple apps at once when Claude requests them together.
82
83Apps with broad reach show an extra warning in the prompt so you know what approving them grants:
84
85| Warning | Applies to |
86| :------------------------- | :----------------------------------------------------------- |
87| Equivalent to shell access | Terminal, iTerm, VS Code, Warp, and other terminals and IDEs |
88| Can read or write any file | Finder |
89| Can change system settings | System Settings |
90
91These apps aren't blocked. The warning lets you decide whether the task warrants that level of access.
92
93Claude'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](/en/desktop#app-permissions) for the complete tier breakdown.
94
95## How Claude works on your screen
96
97Understanding the flow helps you anticipate what Claude will do and how to intervene.
98
99### One session at a time
100
101Computer 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.
102
103### Apps are hidden while Claude works
104
105When 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.
106
107When Claude finishes the turn, hidden apps are restored automatically.
108
109### Stop at any time
110
111When 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.
112
113A second notification appears when Claude is done.
114
115## Safety and the trust boundary
116
117<Warning>
118 Unlike the [sandboxed Bash tool](/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.
119</Warning>
120
121The built-in guardrails reduce risk without requiring configuration:
122
123* **Per-app approval**: Claude can only control apps you've approved in the current session.
124* **Sentinel warnings**: apps that grant shell, filesystem, or system settings access are flagged before you approve.
125* **Terminal excluded from screenshots**: Claude never sees your terminal window, so on-screen prompts in your session can't feed back into the model.
126* **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.
127* **Lock file**: only one session can control your machine at a time.
128
129## Example workflows
130
131These examples show common ways to combine computer use with coding tasks.
132
133### Validate a native build
134
135After making changes to a macOS or iOS app, have Claude compile and verify in one pass:
136
137```text theme={null}
138Build the MenuBarStats target, launch it, open the preferences window,
139and verify the interval slider updates the label. Screenshot the
140preferences window when you're done.
141```
142
143Claude runs `xcodebuild`, launches the app, interacts with the UI, and reports what it finds.
144
145### Reproduce a layout bug
146
147When a visual bug only appears at certain window sizes, let Claude find it:
148
149```text theme={null}
150The settings modal clips its footer on narrow windows. Resize the app
151window down until you can reproduce it, screenshot the clipped state,
152then check the CSS for the modal container.
153```
154
155Claude resizes the window, captures the broken state, and reads the relevant stylesheets.
156
157### Test a simulator flow
158
159Drive the iOS Simulator without writing XCTest:
160
161```text theme={null}
162Open the iOS Simulator, launch the app, tap through the onboarding
163screens, and tell me if any screen takes more than a second to load.
164```
165
166Claude controls the simulator the same way you would with a mouse.
167
168## Differences from the Desktop app
169
170The CLI and Desktop surfaces share the same computer use engine. A few Desktop-specific controls aren't yet in the CLI:
171
172| Feature | Desktop | CLI |
173| :------------------- | :--------------------------------------------- | :------------------------------ |
174| Enable | Toggle in **Settings > Desktop app > General** | Enable `computer-use` in `/mcp` |
175| Denied apps list | Configurable in Settings | Not yet available |
176| Auto-unhide toggle | Optional | Always on |
177| Dispatch integration | Dispatch-spawned sessions can use computer use | Not applicable |
178
179## Troubleshooting
180
181### "Computer use is in use by another Claude session"
182
183Another 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.
184
185### macOS permissions prompt keeps reappearing
186
187macOS 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.
188
189### `computer-use` doesn't appear in `/mcp`
190
191The server only appears on eligible setups. Check that:
192
193* You're on macOS. Computer use is not available on Linux or Windows.
194* You're running Claude Code v2.1.85 or later. Run `claude --version` to check.
195* You're on a Pro or Max plan. Run `/status` to confirm your subscription.
196* You're authenticated through claude.ai. Computer use is not available with third-party providers like Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. If you access Claude exclusively through a third-party provider, you need a separate claude.ai account to use this feature.
197* You're in an interactive session. Computer use is not available in non-interactive mode with the `-p` flag.
198
199## See also
200
201* [Computer use in Desktop](/en/desktop#let-claude-use-your-computer): the same capability with a graphical settings page
202* [Claude in Chrome](/en/chrome): browser automation for web-based tasks
203* [MCP](/en/mcp): connect Claude to structured tools and APIs
204* [Sandboxing](/en/sandboxing): how Claude's Bash tool isolates filesystem and network access
205* [Computer use safety guide](https://support.claude.com/en/articles/14128542): best practices for safe computer use
