# Mobile & Desktop > Every page below, concatenated. Each section gives the page title, its upstream source and its path in this repository. --- ## Access Claude for iOS on your Lock Screen, Control Center, and Action button | Claude Help Center Source: https://support.claude.com/en/articles/10302511-accessing-claude-app-on-ios-lock-screen-control-center-and-action-button Path: 16-Mobile-Desktop/accessing-claude-app-on-ios-lock-screen-control-center-and-action-button.md # Access Claude for iOS on your Lock Screen, Control Center, and Action button July 9, 2026 The features described in this guide are available on iOS 18 and above. Quickly access Claude for iOS functionality from your Lock Screen, Control Center, or Action button on iOS. This article will explain how to add the Claude app into these areas. ## Add Claude for iOS to your Lock Screen 1. Tap and hold your Lock Screen to open Customize Wallpaper 2. Tap "Customize." 3. Choose "Lock Screen." 4. Click on an empty area on either of the two bottom circular slots. 5. Scroll to add “Open Claude..” 6. Click “Done” on the top right corner. You’ll now be able to tap and hold to open Claude for iOS from your **[Lock Screen](https://support.apple.com/guide/iphone/create-a-custom-lock-screen-iph4d0e6c351/ios)**. ## Add Claude for iOS to the Control Center 1. Swipe down from the upper right side of your screen to open the Control Center. 2. Tap & Hold to add a control 3. Tap “Add a Control.” 4. Scroll to add “Open Claude.” You’ll now be able to access Claude for iOS from your **[Control Center](https://support.apple.com/guide/iphone/use-and-customize-control-center-iph59095ec58/ios)**. ## Use the Action button to open Claude for iOS 1. Open the Settings app. 2. Go into the “Action Button” settings. 3. Swipe until you see "Controls." 4. Click "Choose a Control..." 5. Scroll to “Open Claude.” 6. Click back into Settings. You’ll now be able to Hold to Open the **[Action button](https://support.apple.com/guide/iphone/use-and-customize-the-action-button-iphe89d61d66/18.0/ios/18.0)** to access Claude for iOS. --- ## Building Desktop Extensions with MCPB | Claude Help Center Source: https://support.claude.com/en/articles/12922929-building-desktop-extensions-with-mcpb Path: 16-Mobile-Desktop/building-desktop-extensions-with-mcpb.md # Building Desktop Extensions with MCPB April 15, 2026 The MCPB and Desktop Extensions build guide has moved to the Claude developer docs. [View the MCPB build guide →](https://claude.com/docs/connectors/building/mcpb) --- ## Deploy Claude Desktop for macOS | Claude Help Center Source: https://support.claude.com/en/articles/12611117-deploy-claude-desktop-for-macos Path: 16-Mobile-Desktop/deploy-claude-desktop-for-macos.md # Deploy Claude Desktop for macOS March 16, 2026 Administrators on Team or Enterprise plans can deploy Claude Desktop automatically to manage installations and updates centrally. Claude Desktop installs to \`/Applications\` and updates automatically when new versions are released, unless disabled via enterprise policies. ## Available installation formats - **\`.pkg\`** - Standard macOS installer package (recommended for enterprise) - **\`.dmg\`** - Drag-and-drop installation ## Cowork requirements Cowork will be installed automatically when you download and install Claude Desktop for macOS. ## Download **[Universal (x64 or arm64) Claude PKG](https://claude.ai/api/desktop/darwin/universal/pkg/latest/redirect)** The Universal build is compatible with both Intel and Apple Silicon machines and supports all Mac hardware. ## Deploy via MDM Upload the PKG to your MDM solution (Jamf, Kandji, Microsoft Intune) and deploy to target machines. ## Configuration To configure Claude Desktop settings such as auto-updates, extensions, and MCP servers, see the **[Enterprise Configuration](https://support.claude.com/en/articles/12622667-enterprise-configuration)** article. ## Troubleshooting ### Users cannot update Claude Desktop Claude Desktop can be installed to either the user's Applications folder or the system Applications folder, which affects update permissions. - \`~/Applications\` (user folder): Users can update without administrator privileges - \`/Applications\` (system folder): Users need administrator access and write permissions to \`/Applications\`, \`Claude.app\`, and all contained files For shared machines, disable auto-updates via enterprise policies and manage updates centrally through your MDM solution. --- ## Deploy Claude Desktop for Windows | Claude Help Center Source: https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows Path: 16-Mobile-Desktop/deploy-claude-desktop-for-windows.md # Deploy Claude Desktop for Windows Administrators on Team or Enterprise plans can deploy Claude Desktop automatically across their organization to manage installations and updates centrally. We offer MSIX packages for Windows deployments via Microsoft Intune, SCCM, Group Policy, or PowerShell. ## Installation requirements - For individual installations with full feature support including Claude Cowork, administrator privileges are required. Users will see a Windows UAC prompt during installation. Users without admin access can still install Claude, but Cowork on desktop will not be available. Access the user-friendly installer from **[our download page](https://claude.com/download)**. - For silent deployment without user interaction, use the MSIX package directly with your enterprise management tool. ## Cowork desktop requirements Claude Desktop for Windows requires the **[Virtual Machine Platform](https://support.microsoft.com/en-us/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1)** to use Cowork. You can automate installation of this feature via most endpoint management solutions, but you may also run the following command to install it manually: Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All -NoRestart The feature takes effect after the machine restarts. The `-NoRestart` flag suppresses the automatic restart for silent deployment, so schedule one through your management tool. ## Download - **[Claude MSIX (x64)](https://claude.ai/api/desktop/win32/x64/msix/latest/redirect)** - **[Claude MSIX (arm64)](https://claude.ai/api/desktop/win32/arm64/msix/latest/redirect)** ## Installation commands The Claude MSIX is packaged as a per-user application. `Add-AppxPackage` registers it for the current user only, while `Add-AppxProvisionedPackage` stages it machine-wide so it's available to every user on the device, including standard users without admin rights. ### Install for single user Add-AppxPackage -Path "Claude.msix" For more details, see Microsoft's **[Add-AppxPackage](https://learn.microsoft.com/en-us/powershell/module/appx/add-appxpackage?view=windowsserver2022-ps)** documentation. ### Install for all users (provisions machine-wide) Add-AppxProvisionedPackage -Online -PackagePath "Claude.msix" -SkipLicense -Regions "all" For more details, see Microsoft's **[Add-AppxProvisionedPackage](https://learn.microsoft.com/en-us/powershell/module/dism/add-appxprovisionedpackage?view=windowsserver2022-ps)** documentation. ## Deploy via MDM **Important:** Because the MSIX is packaged per-user, uploading it to Intune as a line-of-business (LOB) app installs it in user context rather than machine-wide. The install fails for standard users without admin rights. For machine-wide deployment, run `Add-AppxProvisionedPackage` against the package instead—either pre-stage it on target devices before users sign in, or deliver the command through a Win32 app or PowerShell script wrapper. Intune LOB can't run this command on your behalf. Claude Desktop can be deployed through various enterprise software distribution services. Choose the method that aligns with your organization's existing infrastructure: - **[Microsoft Intune](https://docs.microsoft.com/en-us/windows/msix/desktop/managing-your-msix-deployment-intune)** - **[Microsoft Endpoint Configuration Manager (SCCM)](https://learn.microsoft.com/en-us/windows/msix/desktop/managing-your-msix-deployment-mem-adminconsole)** - **[Group Policy Software Installation](https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/use-group-policy-to-install-software)** - **[Deployment Image Servicing and Management (DISM.exe)](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/preinstall-apps-using-dism?view=windows-10)** - **[PowerShell Scripts](https://learn.microsoft.com/en-us/windows/msix/desktop/powershell-msix-cmdlets)** ### Manage auto-updates alongside your MDM By default, Claude Desktop checks for updates approximately every four hours and applies them automatically—independent of the version your MDM has assigned. To keep the in-app updater and your MDM from conflicting, choose one of these approaches before you deploy: **Option 1: Your MDM manages versions.** Set the `disableAutoUpdates` policy to `1` and push new MSIX builds through your MDM on your own schedule. See **[Enterprise configuration for Claude Desktop](../13-Enterprise-Admin/enterprise-configuration-for-claude-desktop.md)** for the policy location. **Option 2: Claude Desktop manages versions.** Leave `disableAutoUpdates` unset. Deploy the MSIX once via a Win32-wrapped `Add-AppxProvisionedPackage` install, then use a custom detection script that checks `Get-AppxPackage -Name Claude` for a version greater than or equal to the one you provisioned. This keeps your MDM reporting **Installed** after the app self-updates. ## Configuration To configure Claude Desktop settings such as auto-updates, extensions, and MCP servers, see **[Enterprise configuration](https://support.claude.com/en/articles/12622667-enterprise-configuration)**. ------------------------------------------------------------------------ ## Troubleshooting ### MSIX package not working with AppLocker? By default, packaged apps may be restricted by AppLocker policies. Ensure your AppLocker rules allow MSIX packages, or add Claude Desktop to your allowed applications list. Consult your organization's security policies before making changes. ### "The parameter is incorrect" after MDM deployment This usually means the in-app updater and your MDM have both registered the package, leaving duplicate entries under the `Claude` package family. Pick a single update owner using the guidance in **[Manage auto-updates alongside your MDM](#h_1297fb34f3)** above. ### Install fails: "Administrator access is required to install Claude with full features," or error 0x80073D28 Claude Desktop for Windows includes a background service that runs Cowork's virtual machine, and Windows registers that service only when Claude is installed with administrator privileges. - **Claude Setup (ClaudeSetup.exe):** if the administrator prompt is declined or the elevated install fails, Claude Setup shows "Administrator access is required to install Claude with full features" and exits. Users who can't get administrator approval are offered the choice to install Claude without Cowork instead. - **MSIX deployed per user (for example, an Intune line-of-business app assigned to users, or Add-AppxPackage run without administrator rights):** Windows refuses the install with error 0x80073D28. The MSIX package never installs without its Cowork service: either it registers completely, or the install fails. To fix it, run Claude Setup with administrator approval on that device, or provision Claude machine-wide in system context with `Add-AppxProvisionedPackage`, as described in **[Deploy via MDM](#h_124a24d394)**. ### “Installation failed: AddPackage failed with HRESULT 0x80073CF6” This error means a previous Claude install or update on the device didn’t finish cleanly and left the package partially registered, so Windows can’t register the new one. **Warning:** On a device in this state, the installer’s automatic repair removes the previous package’s local app data, including app settings, the saved sign-in, and any files saved only inside Cowork. Chat history and files in the user’s own folders aren’t affected. To resolve it: 1. Restart the device. A pending removal often completes on restart. 2. Run the current installer elevated. 3. If the install fails again with the same error, **[contact Support](../15-Claude-AI-Features/how-to-get-support.md)** and include the `ClaudeSetup.log` file from the user’s Temp folder. IT needs to recover the device in system context, and Support will provide the steps. ### Cowork reports missing HCS services or virtualization errors If Cowork fails to start with an error like "Missing HCS services: HNS, vmcompute, vfpext," the Virtual Machine Platform service stack isn't registered on the machine, even if Claude installed successfully. **To diagnose and fix:** Check whether the feature is enabled and its services exist: Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform Get-Service vmcompute, hns If the feature shows as disabled or the services are missing, re-enable it: Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All Restart the machine using **Restart**, not shut down and power on. With Windows Fast Startup enabled, a shutdown cycle can leave the virtualization services uninitialized. If VMware or VirtualBox is also installed on the machine, confirm the Windows hypervisor is set to launch at boot. Run `bcdedit` from an elevated prompt and check that `hypervisorlaunchtype` reads `Auto`. If it doesn't, run `bcdedit /set hypervisorlaunchtype auto` and restart. **Note:** Virtual machines and VDI environments without nested virtualization aren't supported, so Cowork can't run on these hosts. To see exactly which check is failing, go to **Help \> Troubleshooting \> Show Logs** in Claude Desktop and review `supported-features-info.json`. --- ## Test iOS apps in the simulator - Claude Code Docs Source: https://code.claude.com/docs/en/desktop-ios-simulator Path: 16-Mobile-Desktop/desktop-ios-simulator.md ## On this page - [Requirements](#requirements) - [Choose which Xcode the simulator pane uses](#choose-which-xcode-the-simulator-pane-uses) - [Run your app in the simulator](#run-your-app-in-the-simulator) - [Control the simulator yourself](#control-the-simulator-yourself) - [How sessions manage devices](#how-sessions-manage-devices) - [Grant Claude access to a device](#grant-claude-access-to-a-device) - [Allow a device the first time](#allow-a-device-the-first-time) - [Actions that follow your permission mode](#actions-that-follow-your-permission-mode) - [Turn off simulator access](#turn-off-simulator-access) - [Limitations](#limitations) - [Troubleshooting](#troubleshooting) - [The simulator pane doesn’t open when Claude runs the app](#the-simulator-pane-doesn%E2%80%99t-open-when-claude-runs-the-app) - [The simulator pane says no simulators were found](#the-simulator-pane-says-no-simulators-were-found) - [See also](#see-also) Claude Code on desktop # Test iOS apps in the simulator Copy pageCopy page Claude Code Desktop opens your app in the iOS Simulator pane when Claude builds, runs, or checks it, with a separate simulator for each session. Copy pageCopy page The iOS Simulator pane is in public beta in Claude Code Desktop on macOS. It’s available on Pro, Max, Team, and Enterprise plans, except in Enterprise organizations that have a HIPAA configuration enabled. The iOS Simulator pane shows your app running in Apple’s iOS Simulator next to your conversation in Claude Code Desktop. When Claude builds, installs, launches, or checks your app in a simulator, the pane opens automatically and streams the device screen live. Use it to watch Claude run and test your app, or to tap through the app yourself while Claude keeps working. The simulator pane drives the simulator directly, so it doesn’t need [computer use](desktop.md#let-claude-use-your-computer) and never takes over your screen or hides your other windows. From the CLI, Claude reaches the iOS Simulator through [computer use](../02-Claude-Code-CLI/computer-use.md#test-a-simulator-flow) instead, which controls the simulator on your screen the same way you would with a mouse. [​](#requirements) Requirements The simulator pane uses Apple’s simulator tooling, which the desktop app doesn’t include. Before starting a session, make sure you have: - Claude Desktop v1.24012.0 or later - A Mac, since Apple’s iOS Simulator runs only on macOS - [Xcode](https://developer.apple.com/xcode/) with the iOS platform installed, which provides the simulator devices. If Xcode lists no simulators yet, see [The simulator pane says no simulators were found](#the-simulator-pane-says-no-simulators-were-found) - Xcode 26.x or Xcode 27 is recommended, and the pane works with either. If you have more than one Xcode installed, see [Choose which Xcode the simulator pane uses](#choose-which-xcode-the-simulator-pane-uses) On this page, “device” refers to a simulated iPhone or iPad, one of the same simulator devices you manage in Xcode under **Window → Devices and Simulators**, not physical hardware. The simulator pane is available in local sessions only. In [cloud](desktop.md#run-long-running-tasks-in-the-cloud) and [SSH](desktop.md#ssh-sessions) sessions, Claude runs on a machine that can’t reach the simulators on your Mac. [​](#choose-which-xcode-the-simulator-pane-uses) Choose which Xcode the simulator pane uses If you have more than one Xcode installed, such as Xcode 26.x alongside Xcode 27, the pane uses whichever one `xcode-select` points at. To use a different install, select it by its path. For example, if the Xcode you want is installed as `/Applications/Xcode-26.4.app`, run this in Terminal: ```python sudo xcode-select -s /Applications/Xcode-26.4.app ``` Then quit and reopen Claude Desktop so the pane uses the newly selected Xcode. To check which install is selected, run `xcode-select -p`. It prints the selected install’s Developer folder, such as `/Applications/Xcode-26.4.app/Contents/Developer`. [​](#run-your-app-in-the-simulator) Run your app in the simulator You don’t need a command or setting to open the simulator pane. Claude opens it when it runs your app in a simulator. 1 Open your iOS project In Claude Code Desktop, open the **Code** tab and start a session with your app’s project as the [project folder](desktop.md#start-a-session). Any project that builds an app for the iOS Simulator works. 2 Ask Claude to run or test the app Phrase the task around running or verifying the app. For example: ```python Build the app and run it in the simulator to check the onboarding flow. ``` 3 Watch the app in the simulator pane When the app launches in a simulator, the iOS Simulator pane opens next to the conversation. The first time Claude uses a device, the desktop app asks you to allow it; see [Grant Claude access to a device](#grant-claude-access-to-a-device). Claude installs the app, taps through it, and reads the screen to verify its own changes while you watch. The simulator pane opens whenever Claude launches the app in a simulator, at any point in the session. When your request is about seeing the app, for example “does the new screen look right?”, Claude starts a simulator before it begins the work. After Claude fixes a bug or changes a screen, ask it to verify the change: relaunching the app reopens the pane if it isn’t open. The simulator pane shows whichever device the app actually launched in. To test on a specific device, name it in your request, for example “run it on the iPhone SE simulator”, and Claude targets that device when it builds and launches. A device Claude boots also appears in Apple’s Simulator app, or in Device Hub on Xcode 27. Claude can install the app on a device you already have booted. You can also open the simulator pane yourself. Once the session has a simulator attached or Claude Code detects iOS app work, an **iOS Simulator** button appears in the session’s title bar. If the pane isn’t showing a device yet, click **Attach simulator**, or pick a specific device from the device menu next to it; picking a shut-down device boots it. If Xcode or its simulators are missing, the pane shows the setup steps instead and checks them off as you complete them. [​](#control-the-simulator-yourself) Control the simulator yourself The simulator pane is interactive, not only a viewer. While Claude works, or between tasks, you can: - Tap and swipe by clicking and dragging on the device screen - Press hardware buttons with the same shortcuts as Apple’s Simulator app: **Cmd+Shift+H** for Home, **Cmd+L** to lock, **Cmd+Up Arrow** and **Cmd+Down Arrow** for volume - Rotate the device a quarter turn clockwise with the rotate button or **Cmd+Right Arrow** - Switch which device the pane shows from the device menu, which lists each simulator’s OS version and whether it’s booted - Save a screenshot with **Cmd+S** or a screen recording with **Cmd+R**, using the pane’s capture buttons or the shortcuts; the files are saved to your Desktop - Stop streaming a device without shutting it down by clicking **Detach simulator**, which returns the pane to its **Attach simulator** state If the pane shows a **Display** menu, use it to tune the video stream from the simulator. Lower **Frame rate** or **Resolution** if the pane strains your Mac. Both settings change how the pane displays the device, not how the app runs. You and Claude drive the same device, so your taps change the app state Claude sees. To have Claude check a specific screen, tap through to it, then ask. While Claude is driving the device, the pane shows a **Claude is using this device** badge above the screen; hold off tapping until the badge clears, so the result reflects the app rather than your input. [​](#how-sessions-manage-devices) How sessions manage devices Each device belongs to the session that launched it, so [parallel sessions](desktop.md#work-in-parallel-with-sessions) don’t share a device: what you see in one session’s pane reflects that session’s work, not another’s. Switching sessions in the sidebar switches the simulator view along with the conversation, and switching back resumes the same device where it left off. If Claude works with more than one device, each opens its own pane, up to 4 per session. Claude Code Desktop shuts down the simulators it booted once they’re no longer in use: when you quit the app, when you archive the session, or 10 minutes after you detach a device from its pane. Devices you boot outside Claude Code Desktop, such as in Apple’s Simulator app or in Device Hub, are never shut down automatically. To shut down the attached device right away, use the shutdown button in the pane. [​](#grant-claude-access-to-a-device) Grant Claude access to a device Claude asks for your consent before it controls a device, while building the app or opening a URL on it follows your session’s permission mode. You or your organization can also turn Claude’s access off entirely. [​](#allow-a-device-the-first-time) Allow a device the first time The first time Claude uses a simulator, the desktop app asks you to allow it. The consent covers controlling that device and taking screenshots of it, and you give it once per device rather than once per session. Claude’s screenshots of the device are sent to Anthropic and kept under your normal conversation retention settings, so don’t sign in to real accounts on a device Claude uses. After you allow a device, Claude’s actions on it, such as tapping, typing, launching the app, and taking screenshots, run without further prompts. They carry the same trust as you clicking in the pane, and they only touch the simulated device, so the pane doesn’t need the macOS Accessibility and Screen Recording permissions that computer use requires. If you decline, the device still boots and the pane still works for your own taps; only Claude’s access stays off. To change your mind later, click **Let Claude use it** in the pane. [​](#actions-that-follow-your-permission-mode) Actions that follow your permission mode Two actions follow your session’s [permission mode](../02-Claude-Code-CLI/permissions.md#permission-modes) instead of the one-time consent: - Opening a URL on the device, for example to test a deep link or load a page in the device’s Safari, because a URL can carry data off the device. - Building the app, because `xcodebuild` runs your project’s build scripts on your Mac. Checking on a build already in progress doesn’t prompt. [​](#turn-off-simulator-access) Turn off simulator access You can turn Claude’s simulator access off in the desktop app’s settings. Organizations have two ways to turn it off for everyone: - The `disableMobileSimulatorTools` [managed setting](desktop.md#managed-settings) blocks Claude’s simulator tools. The simulator pane stays usable for your own taps, and the setting can’t be overridden from within the app. - The `requireCoworkFullVmSandbox` policy key, which runs Claude’s tools inside an isolated virtual machine instead of on your Mac, disables the simulator pane and Claude’s simulator tools entirely, so the pane can’t attach a device while it’s set. Claude tells you when either applies. [​](#limitations) Limitations Claude drives simulated devices only and can’t control a physical iPhone or iPad. To test on one, run the app on it from Xcode yourself, then describe what you see or attach a screenshot to the conversation for Claude to work from. [​](#troubleshooting) Troubleshooting [​](#the-simulator-pane-doesn’t-open-when-claude-runs-the-app) The simulator pane doesn’t open when Claude runs the app Claude may not have recognized that you wanted to run or test the app, or the simulator tooling may be missing. Check the following: - State the goal explicitly, for example “run the app in the iOS Simulator and tap through the signup flow”. - Confirm Xcode and the iOS simulators are installed and that you’re using a [recommended Xcode version](#requirements). - If your organization manages Claude Code, the [simulator tools may be disabled by policy](#turn-off-simulator-access). - If you’re in an Enterprise organization that has a HIPAA configuration enabled, the simulator pane isn’t available to you. - The simulator pane requires Claude Desktop v1.24012.0 or later. Open **Claude \> Check for Updates…**, then restart the app. [​](#the-simulator-pane-says-no-simulators-were-found) The simulator pane says no simulators were found Xcode is installed but has no iOS simulators to list. The simulator pane shows the setup steps to follow and checks them off as each one completes. To install the missing piece manually, download the iOS simulator runtime from Xcode’s settings, or run `xcodebuild -downloadPlatform iOS`. [​](#see-also) See also - [Computer use in Desktop](desktop.md#let-claude-use-your-computer): screen control for apps without a dedicated pane - [Computer use from the CLI](../02-Claude-Code-CLI/computer-use.md): how the CLI reaches the iOS Simulator - [Run a session in its own worktree](desktop.md#run-a-session-in-its-own-worktree): how sessions isolate changes - [Get started with Claude Code Desktop](desktop-quickstart.md) --- ## Claude Desktop on Linux (beta) - Claude Code Docs Source: https://code.claude.com/docs/en/desktop-linux Path: 16-Mobile-Desktop/desktop-linux.md ## On this page - [Requirements](#requirements) - [Cowork requirements](#cowork-requirements) - [Install](#install) - [Install from a downloaded file](#install-from-a-downloaded-file) - [Update](#update) - [Uninstall](#uninstall) - [Troubleshoot](#troubleshoot) - [Unable to locate package claude-desktop](#unable-to-locate-package-claude-desktop) - [Unmet dependencies](#unmet-dependencies) - [Running as root without --no-sandbox is not supported](#running-as-root-without-no-sandbox-is-not-supported) - [Your sign-in won’t be saved on this device](#your-sign-in-won%E2%80%99t-be-saved-on-this-device) - [Cowork isn’t available](#cowork-isn%E2%80%99t-available) - [What’s not in the Linux beta yet](#what%E2%80%99s-not-in-the-linux-beta-yet) Claude Code on desktop # Claude Desktop on Linux (beta) Copy pageCopy page Install and update the Claude desktop app on Ubuntu and Debian Copy pageCopy page Linux support for the Claude desktop app is in beta. The desktop app on Linux gives you the same Chat, Cowork, and Claude Code experience as on macOS and Windows: parallel sessions, visual diff review, an integrated terminal and editor, and live app preview. See [Use Claude Code Desktop](desktop.md) for the feature reference. [​](#requirements) Requirements - A Debian-based distribution: Ubuntu 22.04 or later, or Debian 12 or later - x86_64 or arm64 Other Debian-based distributions that meet these requirements may work but aren’t officially tested. On distributions that aren’t Debian-based, such as Fedora or Arch, run the [CLI](../01-Getting-Started/setup.md#system-requirements) instead. If you work on Windows with WSL 2, install the Windows desktop app and run sessions inside your distribution; see [Claude Code Desktop in WSL](desktop-wsl.md). [​](#cowork-requirements) Cowork requirements Cowork is the part of the desktop app for [Dispatch and longer agentic work](https://claude.com/docs/cowork/overview). On Linux, Cowork runs those tasks in a virtual machine that the desktop app hosts with QEMU and KVM. To use Cowork, your machine needs: - **Hardware virtualization**: turned on in your firmware settings. Without it, Cowork reports “Cowork requires hardware virtualization (KVM)”. - **QEMU and UEFI firmware**: `qemu-system-x86`, `ovmf`, and `virtiofsd` on x86_64, or `qemu-system-arm`, `qemu-efi-aarch64`, and `virtiofsd` on arm64. `apt install claude-desktop` installs them by default as recommended packages. If you installed with `--no-install-recommends`, or your system is a minimal image that skips recommended packages, Cowork reports “Cowork requires QEMU” and shows the `apt install` command to run. Ubuntu 22.04 has no `virtiofsd` package; the app uses a bundled copy there. - **Access to `/dev/kvm`**: add your user to the `kvm` group with `sudo usermod -aG kvm $USER`, then log out and back in. Some desktop environments grant the logged-in user access to `/dev/kvm` without the group, but Cowork also needs `/dev/vhost-vsock`, which only `kvm` group members can open. Join the group even if `/dev/kvm` already works for you. The app checks these requirements once at launch: restart it after installing packages, and log out and back in after joining the group. If `/dev/vhost-vsock` is missing and your running kernel has no module directory under `/lib/modules`, Cowork reports that the kernel doesn’t include the virtualization support Cowork needs and that it can’t be added manually. This combination is common on ChromeOS and in container-based Linux environments. [​](#install) Install Install from Anthropic’s apt repository so that updates arrive through your system’s regular package updates. Open a terminal and run the commands in each step. 1 Add Anthropic's apt repository This step downloads the signing key with `curl` and verifies it with `gpg`, which fresh Debian and Ubuntu installations may not include. If either command reports `command not found`, install both first: ```python sudo apt install curl gnupg ``` Download Anthropic’s signing key: ```python sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc https://downloads.claude.ai/claude-desktop/key.asc ``` The command prints nothing when it succeeds and a `curl:` error when it doesn’t. A missing or wrong key makes `apt update` fail later with `NO_PUBKEY BAA929FF1A7ECACE`, so confirm the key downloaded and belongs to Anthropic before continuing: ```python gpg --show-keys /usr/share/keyrings/claude-desktop-archive-keyring.asc ``` The fingerprint gpg prints should be `31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE`. If gpg reports that the file can’t be opened or contains no valid OpenPGP data, the download failed or returned the wrong content: confirm your network can reach `downloads.claude.ai`, then rerun the download command.Register the repository: ```python echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] https://downloads.claude.ai/claude-desktop/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list ``` 2 Install the package ```python sudo apt update && sudo apt install claude-desktop ``` 3 Launch and sign in Launch **Claude** from your application launcher, or run `claude-desktop` from a terminal, and sign in with your Anthropic account.The Linux app signs in the same way as on macOS and Windows: with a claude.ai subscription, or through your organization’s SSO. For API-key authentication, use the [CLI](../01-Getting-Started/quickstart.md). To use Desktop with Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or an LLM gateway instead, see [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview). For proxy servers and custom certificate authorities in those deployments, see [network configuration](../13-Enterprise-Admin/network-config.md). [​](#install-from-a-downloaded-file) Install from a downloaded file If you can’t install through the apt repository, download the `.deb` package directly from the repository’s package pool. This command looks up the newest package for your architecture in the repository index, then downloads it to the current directory: ```python curl -fLO "https://downloads.claude.ai/claude-desktop/apt/stable/$(curl -s "https://downloads.claude.ai/claude-desktop/apt/stable/dists/stable/main/binary-$(dpkg --print-architecture)/Packages" | grep '^Filename: pool/main/c/claude-desktop/claude-desktop_' | sort -V | tail -n 1 | cut -d' ' -f2)" ``` If the command fails with `Remote file name has no length`, the lookup returned no package path. This can mean the repository index couldn’t be fetched, for example when your network blocks `downloads.claude.ai`, or that no package exists for your architecture. Confirm that your network can reach `downloads.claude.ai` and that `dpkg --print-architecture` prints `amd64` or `arm64`; the repository doesn’t publish packages for other architectures. To install without registering Anthropic’s apt repository, first create `/etc/default/claude-desktop` with the line `CLAUDE_DESKTOP_ADD_REPO="false"`. Without the repository, apt doesn’t deliver new versions; to update, re-run the download command and reinstall, or [register the repository](#install) later. Then open the downloaded file with your software installer, such as GNOME Software, or install it with apt from the directory that contains the downloaded file: ```python sudo apt install ./claude-desktop_*.deb ``` If apt reports `E: Unsupported file ./claude-desktop_*.deb given on commandline`, the pattern didn’t match a `.deb` file in the current directory. Confirm the download completed, then run the command again from the directory that contains the file. The `.deb` contains Anthropic’s signing key and installs it at `/usr/share/keyrings/claude-desktop-archive-keyring.asc`, so you don’t need to download the key yourself. Unless you turned registration off with `CLAUDE_DESKTOP_ADD_REPO`, the package also registers the apt repository at `/etc/apt/sources.list.d/claude-desktop.list`, so future updates arrive with your system’s [regular package updates](#update). [​](#update) Update The desktop app doesn’t update itself on Linux. Updates arrive with your system’s regular package updates: ```python sudo apt update && sudo apt upgrade ``` Your distribution’s graphical software updater will also pick up new versions. [​](#uninstall) Uninstall ```python sudo apt remove claude-desktop ``` Uninstalling the package also removes the repository entry and signing key it registered. If you added the repository entry yourself with the [Add Anthropic’s apt repository](#install) step, remove it too: ```python sudo rm /etc/apt/sources.list.d/claude-desktop.list ``` [​](#troubleshoot) Troubleshoot [​](#unable-to-locate-package-claude-desktop) Unable to locate package claude-desktop If `sudo apt install claude-desktop` fails with `E: Unable to locate package claude-desktop`, apt didn’t find the repository you added. Check the following: - Run `sudo apt update` after adding the repository. `apt install` on its own doesn’t see a repository you added after the last time you ran `apt update`. - Confirm the repository entry was written. `cat /etc/apt/sources.list.d/claude-desktop.list` should show the `deb` line from the [Add Anthropic’s apt repository](#install) step. If the file is empty or missing, run that step again. - Confirm your architecture is supported. `dpkg --print-architecture` should print `amd64` or `arm64`. The repository doesn’t publish packages for other architectures. - Run `sudo apt update` again and check its output for errors related to `downloads.claude.ai`. A network or key error there means the repository was added but couldn’t be reached or verified. If the repository is in place and reachable and the package is still not found, [install from a downloaded file](#install-from-a-downloaded-file) instead. [​](#unmet-dependencies) Unmet dependencies If `apt` stops with `The following packages have unmet dependencies` or `Unsatisfied dependencies`, read which dependency it names: - `libc6 (>= 2.34)`: your distribution is older than the package supports. Ubuntu 20.04 ships `libc6` 2.31. Upgrade to Ubuntu 22.04 or later, or Debian 12 or later. - All missing dependencies show `not installable` with an `:amd64` or `:arm64` suffix: you downloaded the `.deb` for a different architecture than your machine’s. Run `dpkg --print-architecture` and download the matching `.deb`, or [install from the apt repository](#install), which selects the package for your architecture. [​](#running-as-root-without-no-sandbox-is-not-supported) Running as root without `--no-sandbox` is not supported If `claude-desktop` exits with this message, you launched it as root. Log in as a regular user and launch it from there. [​](#your-sign-in-won’t-be-saved-on-this-device) Your sign-in won’t be saved on this device Claude Desktop saves your sign-in in your desktop’s keyring, such as GNOME Keyring or KDE Wallet. If it can’t reach an unlocked keyring, your sign-in isn’t saved and you sign in again each time you launch the app. Pick the case that matches your system: - **No keyring installed, on a desktop other than KDE Plasma**: if you installed with `--no-install-recommends`, or on a minimal image that skips recommended packages, apt didn’t install a keyring. Install GNOME Keyring with `sudo apt install gnome-keyring`. - **KDE Plasma with GNOME Keyring also installed**: KDE Wallet comes with the Plasma desktop. The two keyrings conflict, and Claude Desktop can show this notice even though KDE Wallet works. Remove the extra one with `sudo apt remove gnome-keyring`, then restart your computer. - **Keyring installed but locked**: unlock it. After the fix, restart the app and sign in. Then quit and launch it again to confirm the app opens with you still signed in. [​](#cowork-isn’t-available) Cowork isn’t available If Cowork shows one of these messages, fix the requirement it names, then restart the app: - **Cowork requires QEMU**: install the [QEMU and UEFI firmware packages](#cowork-requirements) the message lists. - **Cowork requires hardware virtualization (KVM)**: turn on [hardware virtualization](#cowork-requirements) in your firmware settings. - **Claude doesn’t have permission to use virtualization (/dev/kvm)**: add your user to the [`kvm` group](#cowork-requirements), then log out and back in. - **Cowork requires the `vhost_vsock` kernel module**: run `sudo modprobe vhost_vsock`, then restart the app. That loads the module for the current boot only. To load it on every boot, run `echo vhost_vsock | sudo tee /etc/modules-load.d/vhost_vsock.conf`. [​](#what’s-not-in-the-linux-beta-yet) What’s not in the Linux beta yet - **Computer Use**: [app and screen control](desktop.md#let-claude-use-your-computer) isn’t available on Linux. - **Dictation**: voice input isn’t available in the Linux desktop app. Use [voice dictation](../02-Claude-Code-CLI/voice-dictation.md) in the CLI instead. - **Quick Entry global hotkey**: works on X11. On native Wayland it requires your desktop environment’s GlobalShortcuts portal. - **Fedora and RHEL**: only Debian-based distributions are supported today. Support for additional distributions is coming in the future. For anything not yet available in the desktop app, the [CLI](../01-Getting-Started/quickstart.md) runs the same Claude Code engine and supports a wider range of Linux distributions; see the [system requirements](../01-Getting-Started/setup.md#system-requirements). --- ## Get started with the desktop app - Claude Code Docs Source: https://code.claude.com/docs/en/desktop-quickstart Path: 16-Mobile-Desktop/desktop-quickstart.md ## On this page - [Install](#install) - [Start your first session](#start-your-first-session) - [Now what?](#now-what) - [What’s next](#what%E2%80%99s-next) Claude Code on desktop # Get started with the desktop app Copy pageCopy page Install the Claude desktop app, open the Code tab, and start your first Claude Code session on a project folder on your computer. Copy pageCopy page The desktop app gives you Claude Code with a graphical interface. You can ask Claude to work on the code in a folder on your computer and review its changes without using a terminal. Claude Code is in the **Code** tab at the top of the app’s sidebar. This page walks through installing the app and starting your first session there. Claude Code requires a [Pro, Max, Team, or Enterprise subscription](../17-Billing-Plans/pricing.md). ## Download for macOS Universal build for Intel and Apple Silicon ## Download for Windows For x64 processors ## Get Claude for Linux (beta) apt or .deb for Ubuntu and Debian For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](desktop-linux.md). These cases are covered on other pages: - **Already set up**: see [Use Claude Code Desktop](desktop.md) for everything the Code tab can do - **Want `claude` in your terminal**: [install the CLI](../01-Getting-Started/quickstart.md) separately - **Using chat or Cowork**: see the [Claude Help Center](https://support.claude.com/) - **Need more on installing or deploying the desktop app**: see the [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop) [​](#install) Install 1 Install and sign in On macOS and Windows, download the installer from the links above and run it. On Linux, follow the install steps in [Claude Desktop on Linux](desktop-linux.md). Launch Claude from your Applications folder on macOS, the Start menu on Windows, or your application launcher on Linux, then sign in with your Anthropic account. 2 Open the Code tab Click the **Code** tab at the top of the sidebar. If the tabs show only icons, hover over one to see its name. If a prompt or an error appears after you click **Code**, follow the matching fix: - **Prompt to upgrade**: you need to [subscribe to a paid plan](../17-Billing-Plans/pricing.md) first - **Prompt to sign in online**: complete the sign-in and restart the app - **403 error**: see [authentication troubleshooting](desktop.md#403-or-authentication-errors-in-the-code-tab) The desktop app includes Claude Code, so you don’t need to install Node.js or the CLI to use the Code tab. [​](#start-your-first-session) Start your first session With the Code tab open, choose a project and give Claude something to do. 1 Choose an environment and folder In the [row under the prompt box](desktop.md#start-a-session), click the first control, the environment selector, and select the top entry in the **Local** group. Then click the project folder control beside the environment selector, select **Open folder…**, and choose your project’s directory.If no environment selector appears under your prompt box, you have the earlier layout. See [Check which layout you have](desktop.md#check-which-layout-you-have). Start with a small project you know well. It’s the fastest way to see what Claude Code can do. You can also select: - **Cloud**: Run sessions in the cloud that continue even if you close the app. See [Use Claude Code in the cloud](../02-Claude-Code-CLI/claude-code-on-the-web.md) for how cloud sessions work. - **SSH**: Connect to a remote machine over SSH, such as your own servers, cloud VMs, or dev containers. [Add a connection](desktop.md#ssh-sessions) first. Desktop installs Claude Code on the remote machine automatically the first time you connect. A running task can [keep going while Desktop is disconnected](desktop.md#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires. - **WSL** (Windows): Run the session inside a [WSL 2 distribution](desktop-wsl.md); Claude Code, tools, and git execute on the Linux side with native paths. 2 Choose a model Select a model from the model picker toward the right end of the row under the prompt box. See [models](../02-Claude-Code-CLI/model-config.md#available-models) for a comparison of the available models. You can change the model later from the model picker. 3 Tell Claude what to do Type what you want Claude to do: - `Find a TODO comment and fix it` - `Add tests for the main function` - `Create a CLAUDE.md with instructions for this codebase` A [session](desktop.md#work-in-parallel-with-sessions) is a conversation with Claude about your code. Each session tracks its own context and changes. 4 Review and accept changes Check your [permission mode](desktop.md#choose-a-permission-mode) in the row under the prompt box to see whether Claude waits for your approval: - **Auto or Accept edits**: Claude applies its file changes, and an indicator such as `+12 -1` appears so you can review them in the [diff view](desktop.md#review-changes-with-diff-view) - **Manual**: Claude proposes each change and waits for your approval before applying it In Manual mode, you’ll see: 1. A diff showing exactly what will change 2. Buttons to approve or decline each change 3. Real-time updates as Claude works through your request [​](#now-what) Now what? You’ve made your first edit. For the full reference on everything Desktop can do, see [Use Claude Code Desktop](desktop.md). Here are some things to try next. **Interrupt and steer.** You can redirect Claude at any point. Click the stop button to interrupt immediately, or type a correction and press **Enter** to send it without stopping the running action. Either way, you don’t have to wait for it to finish or start over. **Give Claude more context.** Type `@filename` in the prompt box to pull a specific file into the conversation. The more context Claude has, the better the results. See [Add files and context](desktop.md#add-files-and-context-to-prompts). **Use skills for repeatable tasks.** Type `/` or click **+** → **Slash commands** to browse [built-in commands](../02-Claude-Code-CLI/commands.md), [custom skills](../08-Plugins-Skills/skills.md), and plugin skills. Skills are reusable prompts you can invoke whenever you need them, like code review checklists or deployment steps. **Review changes before committing.** After Claude edits files, a `+12 -1` indicator appears. Click it to open the [diff view](desktop.md#review-changes-with-diff-view), review modifications file by file, and comment on specific lines. Claude reads your comments and revises. To have Claude review the changes itself, enter [`/code-review`](desktop.md#review-your-code) in the prompt box. **Adjust how much control you have.** Your [permission mode](desktop.md#choose-a-permission-mode) sets how much Claude can do without asking for approval: - **Auto**: a classifier reviews actions in the background and blocks the risky ones instead of asking you. - **Manual**: Claude asks before editing files or running commands. - **Accept edits**: Claude auto-accepts file edits for faster iteration. - **Plan**: Claude proposes an approach without editing any files, which is useful before a large refactor. **Add plugins for more capabilities.** Install [plugins](desktop.md#install-plugins) that add skills, agents, MCP servers, and more. **Arrange your workspace.** Drag the chat, diff, terminal, file, and browser panes into whatever layout you want. Open the terminal with **Ctrl+\`** to run commands alongside your session, or click a file path to open it. See [Arrange your workspace](desktop.md#arrange-your-workspace). **Preview your app.** When you run your dev server in the desktop, your app opens in the Browser pane, which can also [open external sites](desktop.md#browse-external-sites). Claude can view the running app, test endpoints, inspect logs, and iterate on what it sees. See [Preview your app](desktop.md#preview-your-app). **Track your pull request.** After opening a PR, Claude Code monitors CI check results and can automatically fix failures. See [Monitor pull request status](desktop.md#monitor-pull-request-status). **Put Claude on a schedule.** Set up [scheduled tasks](desktop-scheduled-tasks.md) to run Claude automatically on a recurring basis: a daily code review every morning, a weekly dependency audit, or a briefing that pulls from your connected tools. **Scale up when you’re ready.** Open [parallel sessions](desktop.md#work-in-parallel-with-sessions) from the sidebar to work on multiple tasks at once, optionally each in its own Git worktree, and open the [tasks pane](desktop.md#watch-background-tasks) to watch the subagents and background commands a session has running. Open a [side chat](desktop.md#ask-a-side-question-without-derailing-the-session) to ask a question without derailing the main thread. Send [long-running work to the cloud](desktop.md#run-long-running-tasks-in-the-cloud) so it continues even if you close the app, or [move a session you already started to the cloud](desktop.md#continue-in-another-surface) if a task takes longer than expected. [Connect external tools](desktop.md#extend-claude-code) like GitHub, Slack, and Linear to bring your workflow together. [​](#what’s-next) What’s next - [Use Claude Code Desktop](desktop.md): permission modes, parallel sessions, diff view, connectors, and enterprise configuration - [Coming from the CLI?](desktop.md#coming-from-the-cli): run Desktop and the CLI on the same project, and compare features, flag equivalents, and what’s not available in Desktop - [Troubleshooting](desktop.md#troubleshooting): solutions to common errors and setup issues - [Best practices](../02-Claude-Code-CLI/best-practices.md): tips for writing effective prompts and getting the most out of Claude Code - [Common workflows](../02-Claude-Code-CLI/common-workflows.md): tutorials for debugging, refactoring, testing, and more --- ## Schedule recurring tasks in Claude Code Desktop - Claude Code Docs Source: https://code.claude.com/docs/en/desktop-scheduled-tasks Path: 16-Mobile-Desktop/desktop-scheduled-tasks.md ## On this page - [Compare scheduling options](#compare-scheduling-options) - [Create a scheduled task](#create-a-scheduled-task) - [Dialog with Only on this computer at the top](#dialog-with-only-on-this-computer-at-the-top) - [Schedule options](#schedule-options) - [How scheduled tasks run](#how-scheduled-tasks-run) - [Find a run’s session](#find-a-runs-session) - [Missed runs](#missed-runs) - [Permissions for scheduled tasks](#permissions-for-scheduled-tasks) - [Manage scheduled tasks](#manage-scheduled-tasks) - [Related resources](#related-resources) Claude Code on desktop # Schedule recurring tasks in Claude Code Desktop Copy pageCopy page Set up scheduled tasks in Claude Code Desktop to run Claude automatically on a recurring basis for daily code reviews, dependency audits, or morning briefings. Copy pageCopy page Scheduled tasks start a new session automatically at a time and frequency you choose. Use them for recurring work like daily code reviews, dependency update checks, or morning briefings that pull from your calendar and inbox. The Desktop app’s **Scheduled tasks** page lists both local scheduled tasks and [cloud scheduled tasks](../02-Claude-Code-CLI/web-scheduled-tasks.md), formerly routines: - **Local task**: runs on your machine with direct access to your files and tools, but only fires while the app is open and your computer is awake - **Cloud task**: runs even when your computer is off, and can also start on API calls or GitHub events This page covers local scheduled tasks; for cloud scheduled tasks and their trigger options, see [Automate work with scheduled tasks](../02-Claude-Code-CLI/web-scheduled-tasks.md). [​](#compare-scheduling-options) Compare scheduling options Claude Code offers three ways to schedule recurring or one-off work: | | [Cloud](../02-Claude-Code-CLI/web-scheduled-tasks.md) | [Desktop](desktop-scheduled-tasks.md) | [`/loop`](../02-Claude-Code-CLI/scheduled-tasks.md) | |:---------------------------|:--------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------| | Runs on | Cloud, Anthropic-managed by default | Your machine | Your machine | | Requires machine on | No | Yes | Yes | | Requires open session | No | No | Yes | | Persistent across restarts | Yes | Yes | Restored on `--resume`, with [exceptions](../02-Claude-Code-CLI/scheduled-tasks.md#limitations) | | Access to local files | No (fresh clone) | Yes | Yes | | MCP servers | Connectors configured per task | [Config files](../06-MCP-Tools/General/mcp.md) and connectors | Inherits from session | | Permission prompts | [Auto mode](../02-Claude-Code-CLI/web-scheduled-tasks.md#permission-prompts-during-a-run) by default | Configurable per task | Inherits from session | | Customizable schedule | Yes | Yes | Yes | | Minimum interval | 1 hour | 1 minute when Claude sets it, [1 hour in the forms](desktop-scheduled-tasks.md#schedule-options) | 1 minute | Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session. By default, local scheduled tasks run against whatever state your working directory is in, including uncommitted changes. To give each run its own [isolated Git worktree](desktop.md#run-a-session-in-its-own-worktree) instead, select **Worktree** in the task’s [**Edit** form](#manage-scheduled-tasks) after you create it. The checkbox is available when the task’s folder is a Git repository. [​](#create-a-scheduled-task) Create a scheduled task Local scheduled tasks require Claude Desktop 1.1.5368 or later. 1 Open the Scheduled tasks page In the [**Code** tab](desktop.md), click **Scheduled** in the sidebar or in the sidebar’s **More** menu. 2 Start a new task Click **New task**. If a menu opens with **Create with Claude** and **Set up manually**, select **Set up manually**. The **New scheduled task** dialog opens. If **Only on this computer** is at the top of the dialog, go to [Dialog with Only on this computer at the top](#dialog-with-only-on-this-computer-at-the-top) before you enter anything. 3 Name the task Enter a name in the **Name** field. Desktop converts it to lowercase kebab-case and uses it as the task’s folder name on disk, so the name must be unique across your tasks. 4 Write the instructions In the box below the name, enter what Claude should do when the task runs. 5 Turn on Only on this computer Skip past the **Trigger** card for now and expand **Advanced settings** below it. On the **General** tab, turn on **Only on this computer**. With it on, the task runs on your machine in a local folder.If the switch is unavailable, clear the repository or the GitHub event or API trigger, because those make the task a [cloud scheduled task](../02-Claude-Code-CLI/web-scheduled-tasks.md). 6 Pick the local folder In the **Local folder** row, select a folder. **Create** stays unavailable until you pick one. 7 Set the schedule Back in the **Trigger** card, select a [schedule preset](#schedule-options). 8 Choose the permission mode and model In the instructions box’s toolbar, select a [permission mode](#permissions-for-scheduled-tasks) and model. If you leave them unchanged, runs use your Claude Code settings and the default model. 9 Create the task Click **Create**. If you haven’t trusted the folder yet, Desktop asks you to trust it at this point. The task’s detail page opens. On the detail page, click the pencil icon to open the [**Edit** form](#manage-scheduled-tasks). There you can change the **Description** that Desktop filled in from your instructions, select **Worktree**, or switch the schedule to **Manual** or **Custom**. You can also create a task by describing what you want in any session. For example, “set up a daily code review that runs every morning at 9am” creates a recurring task. A request like “remind me at 3pm tomorrow to check the deploy” creates a one-time task that disables itself after it fires. [​](#dialog-with-only-on-this-computer-at-the-top) Dialog with Only on this computer at the top If **Only on this computer** is at the top of the **New scheduled task** dialog when it opens, turn it on before you enter anything. When you turn it on, a separate blank form for a local task replaces the form. Then fill in the local form’s fields: - **Name**: enter a name, as in the [steps to create a scheduled task](#create-a-scheduled-task). - **Description**: enter a description. **Create** stays unavailable until you do. - **The instructions box**: enter what Claude should do when the task runs. Select the permission mode and model from the menus in the box. - **Working folder**: select the folder the task runs in. **Create** stays unavailable until you select one. - **Trigger**: select a schedule. For the presets, see [Schedule options](#schedule-options). Click **Create**. The task’s detail page opens. [​](#schedule-options) Schedule options When you turn on **Only on this computer** under **Advanced settings**, the **Trigger** card offers Hourly, Daily, Weekdays, and Weekly. To get **Manual** or **Custom** for such a task, open its [**Edit** form](#manage-scheduled-tasks) after you create it. That form and the [dialog with **Only on this computer** at the top](#dialog-with-only-on-this-computer-at-the-top) offer these six options: - **Hourly**: runs every hour - **Daily**: runs every day at the local time you pick - **Weekdays**: same as Daily but skips Saturday and Sunday - **Weekly**: shows a time picker and a day picker - **Manual**: no schedule, only runs when you click **Run now**. Useful for saving a prompt you trigger on demand - **Custom**: runs on a cron expression that you enter and that is evaluated in your local time, such as `0 9 * * *` for 9:00 AM each day. Write days of the week and months as numbers, since their names aren’t accepted. Sunday is `0`, not `7`. The form rejects an expression that runs more often than once per hour. You can also ask Claude in any Desktop session to set the schedule. Claude isn’t held to the once-per-hour limit and can set a single run at a future time. For example, ask “run the test suite every 30 minutes” or “next Monday at 9am, summarize the pull requests merged since Friday.” [​](#how-scheduled-tasks-run) How scheduled tasks run Local scheduled tasks run on your machine. Desktop checks the schedule every minute while the app is open and starts a fresh session when a task is due, independent of any manual sessions you have open. Each task gets a small delay of a few minutes after the scheduled time to stagger API traffic. The delay is deterministic: the same task always starts at the same offset. Tasks only run while the desktop app is running and your computer is awake. If your computer sleeps through a scheduled time, the run is skipped. To prevent idle-sleep, turn on **Keep computer awake** in **Settings \> This computer \> System**. Closing the laptop lid still puts it to sleep. For tasks that need to run even when your computer is off, or that should trigger on an API call or GitHub event, create a [cloud scheduled task](../02-Claude-Code-CLI/web-scheduled-tasks.md) instead. [​](#find-a-runs-session) Find a run’s session To open the session a run started, go to the task’s [detail page](#manage-scheduled-tasks) and click that run’s row in the **History** list. The sidebar’s session list can show a **Scheduled** group as well, with one row per task. To open the session of a task’s latest run, click the task’s row in that group. To show the group, [check which layout you have](desktop.md#check-which-layout-you-have): - **Current layout**: open the [**Group and sort** menu](desktop.md#organize-and-find-sessions), select **Show**, then select **Scheduled**. The group starts collapsed, so click its heading to expand it. **Show** lists **Scheduled** when at least one of your tasks is **Active**, the **Status** a task’s detail page shows. If it isn’t listed, use the **History** list, which works whether or not the group shows. - **Earlier layout**: the group is in the session list with nothing to turn on In a run’s session, whichever way you reached it, you can see what Claude did, review changes, and respond to permission prompts. Claude can edit files, run commands, create commits, and open pull requests, the same as in a session you start yourself. [​](#missed-runs) Missed runs When the app starts or your computer wakes, Desktop checks whether each task missed any runs in the last seven days. If it did, Desktop starts exactly one catch-up run for the most recently missed time and discards anything older. A daily task that missed six days runs once on wake. Desktop shows a notification when a catch-up run starts. Keep this in mind when writing prompts. A task scheduled for 9am might run at 11pm if your computer was asleep all day. If timing matters, add guardrails to the prompt itself, for example: “Only review today’s commits. If it’s after 5pm, skip the review and post a summary of what was missed.” [​](#permissions-for-scheduled-tasks) Permissions for scheduled tasks Each task has its own permission mode, which you set when creating or editing the task. Allow rules from `~/.claude/settings.json` also apply to scheduled task sessions. If a task runs in [Manual mode](desktop.md#choose-a-permission-mode) and needs to run a tool it doesn’t have permission for, the run stalls until you approve it. To approve it, [find the run’s session](#find-a-runs-session) and answer the permission prompt there. To avoid stalls, click **Run now** after creating a task, watch for permission prompts, and select “always allow” for each one. Future runs of that task auto-approve the same tools without prompting. You can review and revoke these approvals from the task’s detail page. MCP tools marked [`requiresUserInteraction`](../06-MCP-Tools/General/mcp.md#require-approval-for-a-specific-tool) prompt on every call and don’t offer an always-allow option. Runs that call these tools stall each time. [​](#manage-scheduled-tasks) Manage scheduled tasks In the **Code** tab, click **Scheduled** in the sidebar, then click a task in the list to open its detail page. From here you can: - **Run now**: start the task immediately without waiting for the next scheduled time - **Status**: toggle between Active and Paused to pause or resume scheduled runs without deleting the task - **Edit**: change the instructions, schedule, folder, or other settings - **Review history**: see every past run, including skipped runs. Hover a skipped entry to see why: your computer was asleep, the previous run was still in progress, or other scheduled tasks were already running. Click **Show more** to load older entries. - **Review allowed permissions**: see and revoke saved tool approvals for this task from the **Always allowed** panel - **Delete**: remove the task. The sessions the task created are [archived](desktop.md#organize-and-find-sessions), not deleted. The folder holding the task’s `SKILL.md` file stays on disk at `~/.claude/scheduled-tasks//`, or at `scheduled-tasks//` under [`CLAUDE_CONFIG_DIR`](../02-Claude-Code-CLI/env-vars.md) if you set that variable. To remove that folder, delete it yourself. You can also list, create, edit, and pause tasks by asking Claude in any Desktop session. For example, “pause my dependency-audit task” or “show me my scheduled tasks.” To delete a task, use the **Delete** button on its detail page. A scheduled task can also modify its own schedule or prompt from within a running session using the `update_scheduled_task` MCP tool. This lets a task reschedule itself based on what it finds, for example, rescheduling a code review to run earlier when it detects a release branch has been created. To edit a task’s prompt on disk, open `~/.claude/scheduled-tasks//SKILL.md` (or under [`CLAUDE_CONFIG_DIR`](../02-Claude-Code-CLI/env-vars.md) if set). The file uses YAML frontmatter for `name` and `description`, with the prompt as the body. Changes take effect on the next run. Schedule, folder, model, and enabled state are not in this file: change them through the Edit form or ask Claude. [​](#related-resources) Related resources - [Cloud scheduled tasks](../02-Claude-Code-CLI/web-scheduled-tasks.md): run tasks in the cloud on a schedule, via API call, or in response to GitHub events, even when your computer is off - [Run prompts on a schedule](../02-Claude-Code-CLI/scheduled-tasks.md): session-scoped scheduling with `/loop` in the CLI - [Claude Code GitHub Actions](../02-Claude-Code-CLI/github-actions.md): run Claude on a schedule in CI instead of on your machine - [Use Claude Code Desktop](desktop.md): the full Desktop app guide --- ## Claude Code Desktop in WSL - Claude Code Docs Source: https://code.claude.com/docs/en/desktop-wsl Path: 16-Mobile-Desktop/desktop-wsl.md ## On this page - [Requirements](#requirements) - [Start a WSL session](#start-a-wsl-session) - [What works in a WSL session](#what-works-in-a-wsl-session) - [If the terminal or connectors are unavailable](#if-the-terminal-or-connectors-are-unavailable) - [Managed devices](#managed-devices) Claude Code on desktop # Claude Code Desktop in WSL Copy pageCopy page Run Code sessions inside a WSL 2 distribution on Windows Copy pageCopy page On Windows, the Code tab can run a session inside a WSL 2 distribution instead of on Windows itself. The session’s Claude Code process, its tools, and git all execute inside the distribution, using its Linux toolchain and native Linux paths, the same environment your project targets. Use a WSL session when your repository lives inside the distribution’s filesystem. Working on those files from Windows goes through a network filesystem, which is slow and breaks file watching; running the session inside the distribution avoids both. [​](#requirements) Requirements - Windows 10 or 11 with [WSL 2](https://learn.microsoft.com/windows/wsl/install). WSL 1 isn’t supported. - At least one installed distribution (for example, Ubuntu). - `git` installed inside the distribution. [​](#start-a-wsl-session) Start a WSL session 1 Pick a distribution Start a new session in the Code tab and open the [environment selector](desktop.md#start-a-session) under the prompt box, or above it in the [earlier layout](desktop.md#check-which-layout-you-have). Your installed WSL 2 distributions appear under **WSL**. Pick one. 2 Choose a folder The session starts in the distribution’s home directory. Use the folder picker to choose a project folder. Browsing happens inside the distribution, with Linux paths like `/home/you/project`. 3 Trust the folder The first session in a folder shows the workspace trust dialog. You grant trust per distribution and folder. A folder you trust in one distribution isn’t trusted in another distribution or at the same path on Windows. The first session in a distribution takes a little longer while Claude sets up inside it. You can also open a `\\wsl.localhost\...` folder from the normal folder picker, and it reopens inside that distribution. [​](#what-works-in-a-wsl-session) What works in a WSL session Parallel sessions, side chats, visual diff review, branch and pull request status, and worktrees all work, backed by the git and toolchain inside the distribution. “Open in editor” opens VS Code connected to the distribution through [Remote - WSL](https://code.visualstudio.com/docs/remote/wsl). If a Desktop feature is unavailable or limited in a WSL session, check whether it’s one of these: - **Terminal and connectors**: your session may lack the [integrated terminal](desktop.md#run-commands-in-the-terminal), [connectors](desktop.md#connect-external-tools), or both. See [If the terminal or connectors are unavailable](#check-for-the-terminal-and-connectors). - **[Plugins](desktop.md#install-plugins)**: not available in WSL sessions - **File editing**: you can view files in the [file pane](desktop.md#open-and-edit-files) but can’t edit them there, so ask Claude to make the changes - **Attachments**: if the **+** menu shows **Add image** in place of **Add files or photos**, you can attach only images. See [Add files and context to prompts](desktop.md#add-files-and-context-to-prompts). [​](#if-the-terminal-or-connectors-are-unavailable) If the terminal or connectors are unavailable You can’t turn on the integrated terminal or connectors for a WSL session yourself: - **Claude account**: the two features are rolling out separately. Select **Help \> Check for Updates…**, and if a feature is still missing after you update, there’s nothing to do. - **[Third-party provider](../02-Claude-Code-CLI/third-party-integrations.md)**: WSL sessions don’t get the terminal or connectors, and updating Desktop doesn’t change that [​](#managed-devices) Managed devices On devices managed by an organization, WSL sessions may be unavailable. If session start fails with a message that the device is managed, that’s controlled by your administrator. Administrators: see [how settings reach devices](../13-Enterprise-Admin/admin-setup.md#decide-how-settings-reach-devices) in the deployment guide. --- ## Desktop application - Claude Code Docs Source: https://code.claude.com/docs/en/desktop Path: 16-Mobile-Desktop/desktop.md ## On this page - [Start a session](#start-a-session) - [Work with code](#work-with-code) - [Use the prompt box](#use-the-prompt-box) - [Accept a suggested prompt](#accept-a-suggested-prompt) - [Add files and context to prompts](#add-files-and-context-to-prompts) - [Choose a permission mode](#choose-a-permission-mode) - [Auto mode availability](#auto-mode-availability) - [Preview your app](#preview-your-app) - [Browse external sites](#browse-external-sites) - [Approve Claude’s actions on a site](#approve-claude%E2%80%99s-actions-on-a-site) - [Choose between the Browser and the Chrome extension](#choose-between-the-browser-and-the-chrome-extension) - [Restrict external browsing for your organization](#restrict-external-browsing-for-your-organization) - [Review changes with diff view](#review-changes-with-diff-view) - [Review your code](#review-your-code) - [Monitor pull request status](#monitor-pull-request-status) - [Arrange your workspace](#arrange-your-workspace) - [See session details](#see-session-details) - [Hide or show the session details panel](#hide-or-show-the-session-details-panel) - [Run commands in the terminal](#run-commands-in-the-terminal) - [Open and edit files](#open-and-edit-files) - [Save edits in the file pane](#save-edits-in-the-file-pane) - [Open files in other apps](#open-files-in-other-apps) - [Switch view modes](#switch-view-modes) - [Keyboard shortcuts](#keyboard-shortcuts) - [Check usage](#check-usage) - [Let Claude use your computer](#let-claude-use-your-computer) - [When computer use applies](#when-computer-use-applies) - [Enable computer use](#enable-computer-use) - [App permissions](#app-permissions) - [Manage sessions](#manage-sessions) - [Work in parallel with sessions](#work-in-parallel-with-sessions) - [Run a session in its own worktree](#run-a-session-in-its-own-worktree) - [Add folders to a session](#add-folders-to-a-session) - [Archive a session](#archive-a-session) - [Keep uncommitted changes when a session is archived](#keep-uncommitted-changes-when-a-session-is-archived) - [Organize and find sessions](#organize-and-find-sessions) - [Check and free up context](#check-and-free-up-context) - [Get notified when a session finishes](#get-notified-when-a-session-finishes) - [Ask a side question without derailing the session](#ask-a-side-question-without-derailing-the-session) - [Watch background tasks](#watch-background-tasks) - [Work across sessions](#work-across-sessions) - [Start a task that Claude suggests](#start-a-task-that-claude-suggests) - [Run long-running tasks in the cloud](#run-long-running-tasks-in-the-cloud) - [Continue in another surface](#continue-in-another-surface) - [Control which sessions appear on your other devices](#control-which-sessions-appear-on-your-other-devices) - [Sessions from Dispatch](#sessions-from-dispatch) - [Follow a session that Dispatch started](#follow-a-session-that-dispatch-started) - [Set up Dispatch](#set-up-dispatch) - [Extend Claude Code](#extend-claude-code) - [Connect external tools](#connect-external-tools) - [Use skills](#use-skills) - [Install plugins](#install-plugins) - [Configure preview servers](#configure-preview-servers) - [Auto-verify changes](#auto-verify-changes) - [Configuration fields](#configuration-fields) - [Port conflicts](#port-conflicts) - [Examples](#examples) - [Environment configuration](#environment-configuration) - [Create a saved environment](#create-a-saved-environment) - [Environments that Desktop creates for you](#environments-that-desktop-creates-for-you) - [Use, edit, or remove a saved environment](#use-edit-or-remove-a-saved-environment) - [Local sessions](#local-sessions) - [Set environment variables for local sessions](#set-environment-variables-for-local-sessions) - [Set environment variables for dev servers](#set-environment-variables-for-dev-servers) - [Use the local environment editor](#use-the-local-environment-editor) - [Environment variables Desktop sets itself](#environment-variables-desktop-sets-itself) - [Turn off extended thinking](#turn-off-extended-thinking) - [Fixed thinking budgets](#fixed-thinking-budgets) - [Local sessions on managed devices](#local-sessions-on-managed-devices) - [Cloud sessions](#cloud-sessions) - [SSH sessions](#ssh-sessions) - [Remote machine requirements for SSH sessions](#remote-machine-requirements-for-ssh-sessions) - [Set a proxy or a CA certificate for SSH sessions](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions) - [Use your SSH configuration on macOS and Linux](#use-your-ssh-configuration-on-macos-and-linux) - [Reach a port on the remote machine](#reach-a-port-on-the-remote-machine) - [Windows remote machines](#windows-remote-machines) - [Keep a task running while Desktop is disconnected](#keep-a-task-running-while-desktop-is-disconnected) - [Choose where SSH session worktrees go](#choose-where-ssh-session-worktrees-go) - [Files and processes on the remote machine](#files-and-processes-on-the-remote-machine) - [Connections that close before login](#connections-that-close-before-login) - [Use MCP servers set up on the remote machine](#use-mcp-servers-set-up-on-the-remote-machine) - [Open an SSH session from a link](#open-an-ssh-session-from-a-link) - [Pre-configure SSH connections for your team](#pre-configure-ssh-connections-for-your-team) - [Restrict which SSH hosts users can connect to](#restrict-which-ssh-hosts-users-can-connect-to) - [Turn off local sessions and distribute SSH connections](#turn-off-local-sessions-and-distribute-ssh-connections) - [Enterprise configuration](#enterprise-configuration) - [Admin console controls](#admin-console-controls) - [Managed settings](#managed-settings) - [Device management policies](#device-management-policies) - [Network access requirements](#network-access-requirements) - [Authentication and SSO](#authentication-and-sso) - [Data handling](#data-handling) - [Deployment](#deployment) - [Coming from the CLI?](#coming-from-the-cli) - [CLI flag equivalents](#cli-flag-equivalents) - [Shared configuration](#shared-configuration) - [MCP servers from the Claude Desktop chat app](#mcp-servers-from-the-claude-desktop-chat-app) - [Feature comparison](#feature-comparison) - [What’s not available in Desktop](#what%E2%80%99s-not-available-in-desktop) - [Troubleshooting](#troubleshooting) - [Check your version](#check-your-version) - [Claude Code version in the Code tab](#claude-code-version-in-the-code-tab) - [Check which layout you have](#check-which-layout-you-have) - [403 or authentication errors in the Code tab](#403-or-authentication-errors-in-the-code-tab) - [Blank or stuck screen on launch](#blank-or-stuck-screen-on-launch) - [”Failed to load session”](#%E2%80%9Dfailed-to-load-session%E2%80%9D) - [Session not finding installed tools](#session-not-finding-installed-tools) - [Git and Git LFS errors](#git-and-git-lfs-errors) - [MCP servers not working on Windows](#mcp-servers-not-working-on-windows) - [SSH connection fails after you log in](#ssh-connection-fails-after-you-log-in) - [Get Desktop’s logs for an SSH problem](#get-desktop%E2%80%99s-logs-for-an-ssh-problem) - [App won’t quit](#app-won%E2%80%99t-quit) - [Windows-specific issues](#windows-specific-issues) - [”Branch doesn’t exist yet” when opening in CLI](#%E2%80%9Dbranch-doesn%E2%80%99t-exist-yet%E2%80%9D-when-opening-in-cli) - [Still stuck?](#still-stuck) Claude Code on desktop # Desktop application Copy pageCopy page Get more out of Claude Code Desktop: parallel sessions with Git isolation, drag-and-drop pane layout, integrated terminal and file editor, side chats, computer use, Dispatch sessions from your phone, visual diff review, app previews, PR monitoring, connectors, and enterprise configuration. Copy pageCopy page In the Claude Desktop app, Claude Code is the **Code** tab. The app also has chat and [Cowork](../15-Claude-AI-Features/product-cowork.md), which handles Dispatch and longer agentic work. This page is the reference for the Code tab. ## Download for macOS Universal build for Intel and Apple Silicon ## Download for Windows For x64 processors ## Get Claude for Linux (beta) apt or .deb for Ubuntu and Debian For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](desktop-linux.md). After installing, launch Claude, sign in, and click the **Code** tab. For a walkthrough of your first session, see the [Get started guide](desktop-quickstart.md). In the Code tab, each conversation is a **session**: it has its own chat history and project folder, independent of any other session. The sidebar lists your sessions and lets you run several in parallel. Within a session you can: - [Review and comment on diffs](#review-changes-with-diff-view), then [watch the resulting PR through CI](#monitor-pull-request-status) - [Preview your running app](#preview-your-app) in the Browser pane while Claude verifies its own changes, and [open external sites](#browse-external-sites) alongside it - Watch Claude [run and test your iOS app](desktop-ios-simulator.md) in the iOS Simulator pane - [Arrange panes](#arrange-your-workspace) for the chat, diff, browser, terminal, and file editor side by side - Ask a [side question](#ask-a-side-question-without-derailing-the-session) that uses the session’s context without derailing it - Let Claude [check on, message, or archive your other sessions](#work-across-sessions) - [Connect external tools](#connect-external-tools) like GitHub, Slack, and Linear - Let Claude [open apps and control your screen](#let-claude-use-your-computer) - Run on your machine, in the [cloud](#run-long-running-tasks-in-the-cloud), or over [SSH](#ssh-sessions) For [scheduled recurring work](desktop-scheduled-tasks.md), [keyboard shortcuts](#keyboard-shortcuts), or [sending tasks from your phone](#sessions-from-dispatch), see the linked pages and sections. If you already use the terminal-based CLI, see the [CLI comparison](#coming-from-the-cli) for what carries over. [​](#start-a-session) Start a session Before you send your first message, choose the environment, project folder, permission mode, and model in the row under the prompt box: - **Environment**: use the environment selector, the first control in the row, to choose where Claude runs. See [environment configuration](#environment-configuration). - If a new session has no environment selector under the prompt box, follow the [earlier layout’s steps](#check-which-layout-you-have). - **Project folder**: click the project folder control, next to the environment selector, to choose the folder Claude works in. - **Cloud session**: select [repositories](#run-long-running-tasks-in-the-cloud) instead of a folder - **[Saved local or SSH environment](#create-a-saved-environment)**: the environment already holds its folders, so the row shows no project folder control. To change the folders, [edit the environment](#use-edit-or-remove-a-saved-environment). - **Permission mode**: use the [mode selector](#choose-a-permission-mode) to choose how much autonomy Claude has. You can change the permission mode during the session. - **Model**: pick a [model](../02-Claude-Code-CLI/model-config.md#available-models) from the model picker toward the right end of the row. You can change the model during the session. Type your task and press **Enter** to start. Each session tracks its own context and changes independently. [​](#work-with-code) Work with code Give Claude the right context, control how much it does on its own, and review what it changed. [​](#use-the-prompt-box) Use the prompt box Type what you want Claude to do and press **Enter** to send. Claude reads your project files, makes changes, and runs commands based on your [permission mode](#choose-a-permission-mode). You can redirect Claude at any point: click the stop button to interrupt immediately, or type a correction and press **Enter** to send it without stopping the running action. Claude reads the correction as soon as the current action completes and adjusts before its next step. Click the **+** button next to the prompt box for file attachments, [skills](#use-skills), [connectors](#connect-external-tools), and [plugins](#install-plugins). [​](#accept-a-suggested-prompt) Accept a suggested prompt After Claude replies, the Code tab can show a suggested next prompt as gray text in the empty prompt box. Claude Code [generates each suggestion](../02-Claude-Code-CLI/interactive-mode.md#prompt-suggestions) from your conversation with a short background request that counts toward your plan’s usage limits or your API costs. - **Use the suggestion**: press **Tab** or **Right arrow** to place it in the prompt box, edit it if you want, then press **Enter** to send it. Pressing **Enter** before you accept the suggestion doesn’t send it. - **Write your own prompt**: start typing. The suggestion shows only while the prompt box is empty and has no attached files. Go to **Settings \> Claude Code** and turn off **Prompt suggestions** under **Sessions** to stop suggestions in each session from the next time it starts or resumes. [​](#add-files-and-context-to-prompts) Add files and context to prompts To give Claude a file, @mention it or attach it in the prompt box: - **@mention files**: type `@` followed by a filename to add a file to the conversation context. - **In a cloud session**: `@` can list files only after you send your first message. If `@` lists none, send your first message without the file, then @mention the file in your next message. - **Attach files**: attach images, PDFs, and other files to your prompt from the **+** button next to the prompt box, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents. - **In a [WSL session](desktop-wsl.md)**: if the **+** menu shows **Add image** instead of **Add files or photos**, you can attach only images. To give Claude any other file from the session’s folder, @mention it. [​](#choose-a-permission-mode) Choose a permission mode Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch permission modes at any time using the mode selector in the row under the prompt box. To approve each change yourself, switch to Manual. To set a default mode for new local sessions, add `permissions.defaultMode` to your [settings file](../02-Claude-Code-CLI/settings.md#where-settings-live). The desktop app reads the same settings files as the CLI. A mode you pick in the selector is remembered per folder and takes precedence over `defaultMode` for that folder, except Plan, which applies to the current session only. | Mode | Settings key | Behavior | |------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Manual** | `default` | Claude asks before editing files or running commands. You see a diff and can accept or reject each change. | | **Accept edits** | `acceptEdits` | Claude auto-accepts file edits and common filesystem commands like `mkdir`, `touch`, and `mv`, but still asks before running other terminal commands. Use this when you trust file changes and want faster iteration. | | **Plan** | `plan` | Claude reads files and runs commands to explore, then proposes a plan without editing your source code. Good for complex tasks where you want to review the approach first. | | **Auto** | `auto` | Claude runs without routine prompts; before actions such as shell commands and network requests run, a background classifier checks that they align with your request. Appears when [auto mode is available](#auto-mode-availability); there is no separate Settings toggle for it. | | **Bypass permissions** | `bypassPermissions` | Claude runs without permission prompts, except for the [actions no mode auto-approves](../02-Claude-Code-CLI/permission-modes.md#actions-no-mode-auto-approves), safety classifiers when Claude [acts on external sites](#browse-external-sites), or desktop actions such as deleting a session, though not [archiving one](#work-across-sessions). Equivalent to `--dangerously-skip-permissions` in the CLI. On Pro and Max plans, enable it in your Settings → Claude Code under “Allow bypass permissions mode”; on Team and Enterprise plans there is no Settings toggle, and organization policy controls it instead. Only use this in sandboxed containers or VMs. | Earlier versions of the Code tab labeled these modes Ask permissions, Auto accept edits, and Plan mode. The `dontAsk` permission mode is available only in the [CLI](../02-Claude-Code-CLI/permission-modes.md#allow-only-pre-approved-tools-with-dontask-mode). Start complex tasks in Plan so Claude maps out an approach before making changes. Once you approve the plan, switch to Accept edits or Manual to execute it. See [explore first, then plan, then code](../02-Claude-Code-CLI/best-practices.md#explore-first-then-plan-then-code) for more on this workflow. Cloud sessions support Accept edits, Plan, and Auto. Accept edits corresponds to `default` mode: cloud sessions pre-approve file edits, so the selector shows Accept edits instead of Manual. Bypass permissions isn’t available in cloud sessions, including sessions in a [self-hosted environment](../13-Enterprise-Admin/self-hosted-environments.md). Enterprise admins can restrict which permission modes are available. See [enterprise configuration](#enterprise-configuration) for details. [​](#auto-mode-availability) Auto mode availability Auto mode is available to all users on the Anthropic API and requires Claude Opus 4.6 or later, Sonnet 4.6 or later, Haiku 5.5, or a [Fable model](../02-Claude-Code-CLI/model-config.md#work-with-fable). Organization administrators can turn auto mode off with the `disableAutoMode` key in [managed settings](#managed-settings). In Enterprise deployments that route Desktop to Google Cloud’s Agent Platform, auto mode is also available by default; see [Auto mode on Bedrock, Agent Platform, or Foundry](../02-Claude-Code-CLI/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry) for the supported models. [​](#preview-your-app) Preview your app Claude can start a dev server and open it in the Browser pane to verify its changes. This works for frontend web apps as well as backend servers: Claude can test API endpoints, view server logs, and iterate on issues it finds. In most cases, Claude starts the server automatically after editing project files. You can also ask Claude to preview at any time. By default, Claude [auto-verifies](#auto-verify-changes) changes after every edit. In a local session, click an HTML, PDF, or video path in the chat to open it in the Browser pane. In an [SSH session](#ssh-sessions), Claude can’t open your app in the Browser pane, because it doesn’t have the pane’s tools there. To look at the app yourself, [forward its port to your computer](#reach-a-port-on-the-remote-machine). If the Browser pane isn’t open after Claude starts a server in a local session, click **Open** on the server’s card in the chat. From the Browser pane, you can: - Interact with your running app directly in the Browser pane - Watch Claude verify its own changes automatically: it takes screenshots, inspects the DOM, clicks elements, fills forms, and fixes issues it finds - Start or stop servers, or stop them all at once, from the **Dev servers** menu in the Browser pane’s header - Choose whether the Browser keeps cookies after you quit the app with **Keep cookies** in the Browser pane’s **⋮** menu, so you don’t have to sign in again during development Claude creates the initial server configuration based on your project. If your app uses a custom dev command, edit `.claude/launch.json` to match your setup. See [Configure preview servers](#configure-preview-servers) for the full reference. To clear the Browser’s saved data, select **Clear browsing data** in the Browser pane’s **⋮** menu. To turn the Browser off entirely, turn off **Browser tools** in **Settings \> Claude Code**. [​](#browse-external-sites) Browse external sites The Browser pane is a tabbed browser, so you can open documentation, issue trackers, or any other site next to your running app. To open the Browser, press **Cmd+Shift+B** on macOS or **Ctrl+Shift+B** on Windows, or click **Browser** in the session’s title bar. You can sign in to sites in the pane, including popup sign-in flows such as Google OAuth. The first time you click an external link in the chat, a dialog asks whether links open in the Browser pane or in your default browser. To change your choice later, use **Open links in built-in browser** in the Browser pane’s **⋮** menu. **Cmd**-click on macOS or **Ctrl**-click on Windows opens a link in your default browser directly. Claude can read and interact with external pages using the same tools it uses to [verify your app](#preview-your-app), with two additional safety checks: - Safety classifiers review Claude’s write actions on external pages, such as clicking and typing, in every permission mode. These are the same classifiers [auto mode](#choose-a-permission-mode) uses, and when they flag an action, you get a permission prompt regardless of mode. - In permission modes other than Auto and Bypass permissions, a domain allowlist check also applies before Claude navigates to a new site. [​](#approve-claude’s-actions-on-a-site) Approve Claude’s actions on a site The first time Claude acts on an external site, a permission card appears and Claude waits for your choice: **Allow once**, **Always allow**, or **Deny**. **Allow once** approves the action without saving anything. **Always allow** saves the approval for that site on your device, and you can revoke it in Settings. Each site needs its own approval, including subdomains. Your local dev servers and project files don’t need approval, so [auto-verify](#auto-verify-changes) keeps working without prompts. Even on an approved site, Claude won’t purchase items, create accounts, or bypass CAPTCHAs without your input. Browsing in the Browser pane uses the same safety model as the [Claude in Chrome extension](../03-IDE-Integrations/chrome.md). See [Using Claude in Chrome safely](../15-Claude-AI-Features/using-claude-in-chrome-safely.md) for how Claude handles sensitive sites and risky actions. [​](#choose-between-the-browser-and-the-chrome-extension) Choose between the Browser and the Chrome extension The Browser pane uses a clean browser profile, separate from your personal browser, with none of your saved logins or history. Use it for building and testing your app and for sites that don’t need your identity. When you want Claude to act as you in your logged-in sessions, use the [Claude in Chrome extension](../03-IDE-Integrations/chrome.md) instead, which shares your browser’s login state. [​](#restrict-external-browsing-for-your-organization) Restrict external browsing for your organization The Browser follows the same [site allowlist and blocklist controls](../13-Enterprise-Admin/claude-for-chrome-admin-controls.md) as the Claude in Chrome extension. If your organization already configured those lists for the extension, the Browser respects them automatically. Administrators can also turn off Claude’s tools on external pages with the [`browserExternalPageTools` managed setting](#managed-settings). With tools disabled, users can still visit external sites; Claude’s tools can’t read or act on them. To turn off external browsing entirely, set the [`disableBrowserExternalNavigation` managed setting](#managed-settings) to `true`. This blocks all external navigation in the Browser, including sites on your organization’s allowlist; localhost dev servers and file previews keep working. Use `browserExternalPageTools` to let users keep browsing external sites without Claude’s tools, and `disableBrowserExternalNavigation` to block external sites for both users and Claude. [​](#review-changes-with-diff-view) Review changes with diff view After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request. To open the diff view, click the line counts, such as `+12 -1`, in the **Changes** card of the [session details panel](#see-session-details). You can also click **Changes** in the session’s title bar. To comment on specific lines, click any line in the diff to open a comment box. Type your feedback and press **Enter** to add the comment. After adding comments to multiple lines, submit all comments at once: - **macOS**: press **Cmd+Enter** - **Windows**: press **Ctrl+Enter** Claude reads your comments and makes the requested changes, which appear as a new diff you can review. [​](#review-your-code) Review your code To have Claude review your changes before you commit, enter `/code-review` in the [prompt box](#use-the-prompt-box). The findings arrive in the conversation when the review completes. In local, [SSH](#ssh-sessions), and [WSL](desktop-wsl.md) sessions, the findings appear as a **Code review** card, grouped by file. Use the card to act on them: - Click **Walk through in diff** to open the diff view and step through the findings one at a time. A finding in the current diff appears at its line, where you can click **Fix this one** or dismiss it. - Click **Apply fixes** to ask Claude to fix the findings that are still open. In any session, you can also ask Claude in the prompt box to fix what the review found. For what `/code-review` looks for and the arguments it takes, see [Review locally with `/code-review`](../02-Claude-Code-CLI/code-review-local.md). [​](#monitor-pull-request-status) Monitor pull request status To have Claude fix failing checks, or to have GitHub merge the pull request, turn on **Auto-fix** or **Merge when ready**. After you open a pull request, it appears in the **Changes** card of the [session details panel](#see-session-details) with the status of its CI checks. Open the **⋮** menu beside its title: - **Auto-fix**: in a local session, Claude also addresses new review comments that someone other than you leaves. The comment’s author has to be the repository’s owner, an organization member, a collaborator, or a GitHub App. - **Merge when ready**: turns on GitHub’s auto-merge for the PR. In a local session, Desktop requests a squash merge unless the base branch uses a merge queue. - **In SSH and WSL sessions**: **Merge when ready** is disabled, so turn on auto-merge for the pull request on GitHub - **If the repository doesn’t allow auto-merge**: **Merge when ready** doesn’t turn on, so enable auto-merge in your [GitHub repository settings](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository) first - **[Earlier layout](#check-which-layout-you-have)**: once the session has a pull request, click **CI** on its status bar. To archive the session automatically once the PR merges or closes, turn on [auto-archive](#archive-a-session) in **Settings \> Claude Code**. PR monitoring requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated on your machine. If `gh` is not installed, Desktop prompts you to install it the first time you try to create a PR.In an [SSH session](#ssh-sessions), set up `git` and `gh` on the remote machine before you click **Create PR**, because Claude pushes the branch and runs `gh pr create` there. Install `gh` there yourself, because Desktop doesn’t prompt you to in an SSH session. Then check there that `git push` works and that `gh auth status` reports that you are logged in. [​](#arrange-your-workspace) Arrange your workspace The Code tab is built around panes you can arrange in any layout: chat, diff, browser, terminal, file, plan, tasks, and subagent, along with the [iOS Simulator](desktop-ios-simulator.md) on macOS. Drag a pane by its header to reposition it, or drag a pane edge to resize it. Press **Cmd+\\** on macOS or **Ctrl+\\** on Windows to close the focused pane. To open another pane, click its icon button in the session’s title bar. Hover to see each button’s name, such as **Terminal**, **Changes** for the diff view, **Browser**, and **Files**. If the pane you want has no button in the title bar, select it from the **⋮** menu beside the buttons: - **When the window is narrow**: buttons that don’t fit move into the menu - **For panes with no button**: panes such as **Background tasks** and **Plan** are listed once the session has something to show in those panes To work across screens, pop a pane such as the diff or terminal out into its own window, and dock it back when you’re done. Claude keeps working in the main window. The pane layout, terminal, file editor, and view modes in this section require Claude Desktop v1.2581.0 or later. Open **Claude \> Check for Updates…** on macOS or **Help \> Check for Updates…** on Windows to update. [​](#see-session-details) See session details The session details panel is a set of cards beside the chat that show where the session runs, what it changed, what it’s running, and its context usage. The panel appears after you start a session, while the chat is wide enough for it. [​](#hide-or-show-the-session-details-panel) Hide or show the session details panel To hide or show the panel, click **Hide session rail** or **Show session rail** in the session’s title bar, or in the bar’s **⋮** menu when the window is narrow. If you still don’t see the panel, [check which Code tab layout you have](#check-which-layout-you-have). [​](#run-commands-in-the-terminal) Run commands in the terminal The integrated terminal lets you run commands alongside your session without switching to another app. Click **Terminal** in the session’s title bar or press **Ctrl+\`** on macOS or Windows. The terminal opens in your session’s working directory and shares the same environment as Claude, so commands like `npm test` or `git status` see the same files Claude is editing. To open a second terminal tab, click **+** in the terminal pane header or right-click a folder in the chat to choose **Open in terminal**. If a WSL session has no terminal, see [If the terminal or connectors are unavailable](desktop-wsl.md#check-for-the-terminal-and-connectors). The terminal is available in local and [SSH](#ssh-sessions) sessions, with a limit on [Windows remote machines](#windows-remote-machines). [​](#open-and-edit-files) Open and edit files To open a file Claude mentions, click its path in the chat. To edit a file yourself, use the [file pane](#arrange-your-workspace): - **Local sessions**: you can edit files inside the session’s working directory, except some view-only ones such as `.mcp.json` and `.claude/settings.json`. To change one, [open it in another app](#open-files-in-other-apps). - **Cloud, SSH, and WSL sessions**: the file pane is view-only, so ask Claude to make edits. [​](#save-edits-in-the-file-pane) Save edits in the file pane By default, your edits in the file pane save on their own, so the pane shows no **Save** button. To save your edits yourself, uncheck **Auto save** in the pane’s **⋮** menu. With **Auto save** off, click **Save** after you change a file to write your edits, or **Cancel** to revert them. If the pane warns that the file changed on disk, click **Override** to write your edits over the version on disk, or **Discard** to drop your edits. [​](#open-files-in-other-apps) Open files in other apps Right-click any file path in the chat, diff viewer, or file pane to open a context menu: - **Attach as context**: add the file to your next prompt - **Open in**: open the file in an installed editor such as VS Code, Cursor, or Zed - **Show in Finder** on macOS, **Show in Explorer** on Windows: open the containing folder - **Copy**: a submenu that copies the file’s **Absolute path**, **Relative path**, or **Filename** [​](#switch-view-modes) Switch view modes View modes control how much detail appears in the chat transcript. To switch view modes, open the session menu from the caret beside the session title and select **Transcript view**, or press **Ctrl+O** on macOS or Windows to cycle through them. The Thinking mode appears in the menu only after Claude has produced thinking in the session you’re viewing. | Mode | What it shows | |--------------|----------------------------------------------------------------------------------------| | **Normal** | Tool calls collapsed into summaries, with full text responses | | **Thinking** | Tool calls collapsed into summaries, plus Claude’s thinking | | **Verbose** | Every tool call, file read, and intermediate step Claude takes, plus Claude’s thinking | Use Thinking to follow Claude’s reasoning with tool calls still collapsed. Use Verbose when debugging why Claude took a particular action. Claude Desktop versions before 1.46388.1 also list a Summary mode, and a session still set to Summary opens in Normal once you update. [​](#keyboard-shortcuts) Keyboard shortcuts Press **Cmd+/** on macOS or **Ctrl+/** on Windows to see all shortcuts available in the Code tab. The table in this section shows the macOS keys. On Windows and Linux, change these keys: - **Cmd+Option**: press **Alt** - **Cmd+Ctrl**: press **Ctrl+Alt** - **Cmd**: press **Ctrl** Session cycling, the terminal toggle, and the view-mode toggle use **Ctrl** on every platform. | Shortcut | Action | |---------------------------------------|---------------------------------------------------------------------------------------------------------------------| | `Cmd` `/` | Show keyboard shortcuts | | `Cmd` `N` | New session | | `Cmd` `Option` `1`–`9` | On the new session screen in the [current layout](#check-which-layout-you-have), select an environment | | `Cmd` `Option` `0` | On the new session screen in the current layout, open the [**New environment** dialog](#create-a-saved-environment) | | `Cmd` `W` | Close session | | `Ctrl` `Tab` / `Ctrl` `Shift` `Tab` | Next or previous session | | `Cmd` `Shift` `]` / `Cmd` `Shift` `[` | Next or previous session | | `Esc` | Stop Claude’s response | | `Tab` / `Right arrow` | [Accept the suggested prompt](#accept-a-suggested-prompt) in an empty prompt box | | `Cmd` `Shift` `D` | Toggle diff pane | | `Cmd` `Shift` `B` | Toggle Browser pane | | `Cmd` `Shift` `S` | Select an element in the Browser | | `Ctrl` `` ` `` | Toggle terminal pane | | `Cmd` `\` | Close focused pane | | `Cmd` `Ctrl` `W` | Take focused session out of [split view](#work-in-parallel-with-sessions) | | `Cmd` `;` | Open side chat | | `Ctrl` `O` | Cycle view modes | | `Cmd` `Shift` `M` | Open permission mode menu | | `Cmd` `Shift` `I` | Open model menu | | `Cmd` `Shift` `E` | Open effort menu | | `1`–`9` | Select item in an open menu | These shortcuts apply to the Code tab. In Desktop, `Shift+Tab` doesn’t cycle permission modes as it does in the terminal’s [interactive mode](../02-Claude-Code-CLI/interactive-mode.md#keyboard-shortcuts). [​](#check-usage) Check usage To see how full this session’s context window is, find your Code tab layout: - **Current layout**: the header of the **Context** card in the [session details panel](#see-session-details) shows it as a percentage. Open the card to see what is using the window by category. - **[Earlier layout](#check-which-layout-you-have)**: click the usage ring next to the model picker. Its popover shows your context window usage. In either layout, type `/context` in the prompt box to print a per-category breakdown of this session’s context window in the chat. Both layouts have the usage ring next to the model picker. Click it to see your plan usage, which is shared across all your Claude Code surfaces. [​](#let-claude-use-your-computer) Let Claude use your computer Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to interact with a desktop tool that has no CLI, or automate something that only works through a GUI. For running and testing iOS apps, Desktop opens the dedicated [iOS Simulator pane](desktop-ios-simulator.md) instead of controlling your screen; the pane works without enabling computer use. Computer use is a research preview on macOS and Windows that requires a Pro or Max plan. It is not available on Team or Enterprise plans. The Claude Desktop app must be running. On macOS, computer use requires macOS 14 or later. Computer use is off by default. [Enable it in Settings](#enable-computer-use) before Claude can control your screen. On macOS, you also need to grant Accessibility and Screen Recording permissions. On macOS, computer use can also run in the background: Claude works in the apps you’ve approved while you keep working. Unlike the [sandboxed Bash tool](../02-Claude-Code-CLI/sandboxing.md), computer use runs on your actual desktop with access to whatever 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. [​](#when-computer-use-applies) When computer use applies Claude has several ways to interact with an app or service, and computer use is the broadest and slowest. It tries the most precise tool first: - If you have a [connector](#connect-external-tools) for a service, Claude uses the connector. - If the task is a shell command, Claude uses Bash. - If the task is browser work and you have [Claude in Chrome](../03-IDE-Integrations/chrome.md) set up, Claude uses that. - If the task is running or testing an iOS app, Claude uses the [iOS Simulator pane](desktop-ios-simulator.md), which doesn’t use screen control. - If none of those apply, Claude uses computer use. The [per-app access tiers](#app-permissions) reinforce this: browsers are capped at view-only, and terminals and IDEs at click-only, steering Claude toward the dedicated tool even when computer use is active. Screen control is reserved for things nothing else can reach, like native apps, hardware control panels, or proprietary tools without an API. [​](#enable-computer-use) Enable computer use Computer use is off by default. If you ask Claude to do something that needs it while it’s off, Claude tells you it could do the task if you enable computer use in Settings. 1 Update the desktop app Make sure you have the latest version of Claude Desktop. On macOS and Windows, download or update at [claude.com/download](https://claude.com/download); on Linux, update through your package manager ([instructions](desktop-linux.md)). Then restart the app. 2 Turn on the toggle In the desktop app, go to **Settings \> This computer \> System**. Under **Computer use**, turn on **Enable computer use**. On Windows, the toggle takes effect immediately and setup is complete. On macOS, continue to the next step.If you don’t see the toggle, confirm you’re on macOS or Windows with a Pro or Max plan, then update and restart the app. 3 Grant macOS permissions On macOS, grant two system permissions before the toggle takes effect: - **Accessibility**: lets Claude click, type, and scroll - **Screen Recording**: lets Claude see what’s on your screen The Settings page shows the current status of each permission. If either is denied, click the badge to open the relevant System Settings pane. [​](#app-permissions) App permissions The first time Claude needs to use an app, a prompt appears in your session. Click **Allow for this session** or **Deny**. Approvals last for the current session, or 30 minutes in [Dispatch-spawned sessions](#sessions-from-dispatch). The prompt also shows what level of control Claude gets for that app. These tiers are fixed by app category and can’t be changed: | Tier | What Claude can do | Applies to | |:-------------|:---------------------------------------------------------|:----------------------------| | View only | See the app in screenshots | Browsers, trading platforms | | Click only | Click and scroll, but not type or use keyboard shortcuts | Terminals, IDEs | | Full control | Click, type, drag, and use keyboard shortcuts | Everything else | Apps with broad reach, like terminals, Finder or File Explorer, and System Settings or Settings, show an extra warning in the prompt so you know what approving them grants. The **Computer use** section in **Settings \> This computer \> System** includes these options: - **Denied apps**: add apps here to reject them without prompting. Claude may still affect a denied app indirectly through actions in an allowed app, but it can’t interact with the denied app directly. - **Unhide apps when Claude finishes**: when computer use isn’t running in the background, Claude hides your other windows while it works so it interacts with only the approved app. When Claude finishes, hidden windows are restored unless you turn this setting off. [​](#manage-sessions) Manage sessions Each session is an independent conversation with its own context and changes. You can run multiple sessions in parallel, branch off side chats, let Claude check on and message your other sessions, send work to the cloud, or let Dispatch start sessions for you from your phone. [​](#work-in-parallel-with-sessions) Work in parallel with sessions Click **+ New** in the sidebar, or press **Cmd+N** on macOS or **Ctrl+N** on Windows, to work on multiple tasks in parallel. Press **Ctrl+Tab** and **Ctrl+Shift+Tab** to cycle through sessions in the sidebar. You can also open a second session next to the current session or in a window of its own: - **Side by side**: hold **Option** on macOS or **Alt** on Windows and click a session in the sidebar, or right-click the session and select **Open in**, then **Split view** - **In its own window**: hold **Cmd** on macOS or **Ctrl** on Windows and click a session, or right-click the session and select **Open in**, then **New window** In the split view, the pane you opened or clicked last has focus, and the other pane is dimmed. To change which session a pane shows, click in that pane to give it focus, then click a session in the sidebar. To take the focused session out of the split view, press **Cmd+Ctrl+W** on macOS or **Ctrl+Alt+W** on Windows. [​](#run-a-session-in-its-own-worktree) Run a session in its own worktree In a project that’s a Git repository, turn on **Worktree** before you start a session to run it in its own [Git worktree](../02-Claude-Code-CLI/worktrees.md), an isolated copy of the project. By default, **Worktree** is off and Claude works in the project folder itself. Click the project folder control in the [row under the prompt box](#start-a-session) and turn on **Worktree**. - **With a [saved environment](#create-a-saved-environment)**: set **Worktree** when you create or edit the environment - **[Earlier layout](#check-which-layout-you-have)**: select the **worktree** checkbox beside the branch name, above the prompt box Worktrees are stored in `/.claude/worktrees/` by default. To store them in a custom directory instead: - **Local sessions**: set **Worktree location** in **Settings \> Claude Code** - **SSH sessions**: set **Worktree folder** on the [SSH connection](#choose-where-ssh-session-worktrees-go) You can also set a **Branch prefix** in **Settings \> Claude Code**. Desktop prepends it to every worktree branch name, which is useful for keeping Claude-created branches organized. To include gitignored files like `.env` in new worktrees, create a [`.worktreeinclude` file](../02-Claude-Code-CLI/worktrees.md#copy-gitignored-files-into-worktrees) in your project root. See [What worktrees share with the main checkout](../02-Claude-Code-CLI/worktrees.md#what-worktrees-share-with-the-main-checkout) for where a worktree session reads project settings, hooks, and skills. Session isolation requires [Git](https://git-scm.com/downloads). Most Macs include Git by default. Run `git --version` in Terminal to check; if it prints a version number, Git is installed. If you run into Git errors, ask Claude in [Cowork](../15-Claude-AI-Features/product-cowork.md) to help troubleshoot your setup. [​](#add-folders-to-a-session) Add folders to a session Add folders before the session starts or while it runs: - **Before a local session starts**: add the folders under **Folders** when you [create a saved environment](#create-a-saved-environment) or edit one, then [start the session from that saved environment](#use-edit-or-remove-a-saved-environment). - **While a local or [SSH](#ssh-sessions) session runs**: click **+** next to the prompt box and select **Add folder**. Claude works in that folder itself, with no [worktree](#run-a-session-in-its-own-worktree). [​](#archive-a-session) Archive a session Before you archive a session whose worktree has uncommitted changes, see [Keep uncommitted changes when a session is archived](#keep-uncommitted-changes-when-a-session-is-archived). To archive a session, hover over it in the sidebar, open its menu, and select **Archive**. The session moves to your [archived sessions](#organize-and-find-sessions). To have sessions archive themselves when their pull request merges or closes, turn on **Auto-archive after PR merge or close** in **Settings \> Claude Code**. Cloud sessions and sessions that are still running don’t archive themselves. [​](#keep-uncommitted-changes-when-a-session-is-archived) Keep uncommitted changes when a session is archived You can lose uncommitted changes in a session’s worktree when the session is archived, so commit what you want to keep first: - **If Desktop asks about the changes**: select **Archive anyway** to discard them, or cancel and commit them - **If the only changes are untracked files**: commit the ones you want to keep before a pull request that Claude opened in the session merges, because Desktop can then delete them without asking - **In any other case**: the worktree stays on disk with its changes. For a local session, Desktop removes both about 30 days after the session is archived or you last open it, whichever is later. To keep the changes, open the session from the [**Archived** tab](#organize-and-find-sessions) and select **Unarchive** [​](#organize-and-find-sessions) Organize and find sessions You group, sort, and find sessions from an icon in the sidebar’s session list: - **Current layout**: hover over a heading in the session list to show the **Group and sort** icon, then click it. To find archived sessions, select **View all**, the menu’s last row, then open the **Archived** tab. - **[Earlier layout](#check-which-layout-you-have)**: the **Filter** icon shows without hovering. Click it to arrange the list with **Group by** or **Sort by**. To show archived sessions, select **Status**, then **Archived**. To rename a session, open it and click the session title in the title bar. [​](#check-and-free-up-context) Check and free up context To check context usage, see [Check usage](#check-usage). When context fills up, Claude automatically summarizes the conversation and continues working. You can also type `/compact` to trigger summarization earlier and free up context space. See [the context window](../02-Claude-Code-CLI/how-claude-code-works.md#the-context-window) for details on how compaction works. [​](#get-notified-when-a-session-finishes) Get notified when a session finishes The desktop app sends an OS notification when a Code session finishes a task and you aren’t currently viewing that session. For sessions that belong to a [project](../02-Claude-Code-CLI/claude-projects.md#see-what-needs-you-in-overview), you get the project’s notifications instead. [​](#ask-a-side-question-without-derailing-the-session) Ask a side question without derailing the session A side chat lets you ask Claude a question that uses your session’s context but doesn’t add anything back to the main conversation. Use it when you want to understand a piece of code, check an assumption, or explore an idea without steering the session off course. Press **Cmd+;** on macOS or **Ctrl+;** on Windows to open a side chat, or type `/btw` in the prompt box. The side chat can read everything in the main thread up to that point. When you’re done, close the side chat and continue the main session where you left off. Side chats are available in local, SSH, and WSL sessions. The desktop app doesn’t save side chats to disk, so you can’t return to one after you close the app. [​](#watch-background-tasks) Watch background tasks The tasks pane shows the background work running inside the current session: subagents, background shell commands, and [dynamic workflows](../02-Claude-Code-CLI/workflows.md). Once the session has background work, open the pane with **Background tasks** in the title bar’s **⋮** menu. Click any entry to see its output in the subagent pane or stop it. To see what other sessions are doing, use the [sidebar](#work-in-parallel-with-sessions), or ask Claude to [check on them for you](#work-across-sessions). [​](#work-across-sessions) Work across sessions Claude can list your other Code tab sessions, read what each has been doing, and send messages between them. Ask in plain language: “which session touched the auth refactor?”, “what did the API session conclude?”, or “tell the payments session the schema changed”. You can also ask Claude to rename or archive a session. For example, ask it to archive the sessions whose PRs have merged. Through this surface, Claude sees only the sessions the desktop app runs itself: local, [SSH](#ssh-sessions), and [WSL](desktop-wsl.md) sessions in the Code tab. Claude doesn’t see cloud sessions, or sessions you started from the terminal CLI or the VS Code extension, even in worktrees of the same project, so with nine terminal worktrees open and two desktop sessions, Claude answering in one of them reports the one other desktop session. Claude never lists the session you’re asking from. By default it sees the 20 most recently active sessions and skips archived sessions unless you ask for them. [Cross-session messaging](../02-Claude-Code-CLI/cross-session-messaging.md) separately lets Claude message [your other Claude Code sessions](../02-Claude-Code-CLI/cross-session-messaging.md#see-which-sessions-claude-can-reach), including terminal sessions. When Claude messages another session through this surface, Claude Code shows it there as a card labeled with the sending session’s title and a link back, so you can always tell where a message came from. If the receiving session is mid-task, Claude Code holds the message and Claude reads it once the current work finishes. The receiving Claude can reply, and Claude Code delivers the reply back through this surface. Claude can’t deliver to an archived session, and tells you when a message doesn’t go through. Claude Code applies three safety behaviors across sessions: - You get an approval card before Claude archives a session, except in Auto mode and Bypass permissions mode, where Claude can archive a session without one. To be asked, switch to Manual. - Claude Code checks each message from this surface against the receiving session’s [inbound controls](../02-Claude-Code-CLI/cross-session-messaging.md#control-inbound-messages), even when the receiving session doesn’t have [cross-session messaging](../02-Claude-Code-CLI/cross-session-messaging.md#availability) itself. If you set [`crossSessionInbound`](../02-Claude-Code-CLI/settings-reference.md#crosssessioninbound) to `refuse` in the receiving session, Claude Code drops messages from this surface. Claude Code reports the refusal to the Claude desktop app. Before v2.1.234, Claude Code dropped every message from this surface to a receiving session without cross-session messaging. - Claude Code quotes each incoming message and attributes it to the session that sent it, and Claude still follows the receiving session’s own permission settings when acting on one. [​](#start-a-task-that-claude-suggests) Start a task that Claude suggests When Claude notices something worth fixing outside your current task, it suggests that work as a task. In local and SSH sessions on the [current layout](#check-which-layout-you-have), the suggestion is a card in the chat, and its buttons either start the task or keep it in this session: - **Start**: starts the task in another session. By default the task runs in the current session’s environment. The card then shows the started session’s state, and the [sidebar](#work-in-parallel-with-sessions) lists the started session under the current session. - **Do it here**: sends the task to the current session as a message - **Options**: review or change settings such as the environment, model, [worktree](#run-a-session-in-its-own-worktree), and permissions before you click **Start** - **Start all**: when the card lists several tasks, starts each task in its own session without waiting for one task to finish before starting the next In cloud sessions, and in local and SSH sessions on the earlier layout, the suggestion is a **Suggested task** card. To start the task where the card’s main button says, for example **Send to cloud** or **Start with worktree**, click that button. Click the caret beside the main button for other ways to start the task, including **Do it here**. [​](#run-long-running-tasks-in-the-cloud) Run long-running tasks in the cloud For large refactors, test suites, migrations, or other long-running tasks, select an environment under **Cloud** in the [environment selector](#start-a-session) when starting a session. Cloud sessions run on Anthropic-managed infrastructure by default and continue even if you close the app or shut down your computer. Check back anytime to see progress or steer Claude in a different direction. You can also monitor cloud sessions from [claude.ai/code](https://claude.ai/code) or the [Claude mobile app](mobile.md). Cloud sessions also support multiple repositories. Choose the repositories: - **Current layout**: in the row under the prompt box, once you select a cloud environment. - **[Earlier layout](#check-which-layout-you-have)**: above the prompt box. To add another repository, click **+** beside the selected one. See [Use Claude Code in the cloud](../02-Claude-Code-CLI/claude-code-on-the-web.md) for more on how cloud sessions work. When one body of work needs many cloud sessions, use a [project](../02-Claude-Code-CLI/claude-projects.md): Claude starts and tracks the sessions for you from one conversation. [Create a project](../02-Claude-Code-CLI/claude-projects.md#create-a-project) has the steps. A task in an [SSH session](#ssh-sessions) can also [keep going while Desktop is disconnected](#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires. [​](#continue-in-another-surface) Continue in another surface To continue a session somewhere else, open the session menu from the caret beside the session title or from the session’s row in the sidebar, then select **Open in**: - Select **Cloud** to continue the session as a [cloud session](../02-Claude-Code-CLI/claude-code-on-the-web.md), with your conversation carried over as a summary. Before you confirm, the dialog states whether your files move too and whether this session is archived once the cloud one is ready. You can’t move a session that runs over [SSH](#ssh-sessions) or in [WSL](desktop-wsl.md) this way. - Select an installed editor or your file manager to open the session’s folder on disk there. [​](#control-which-sessions-appear-on-your-other-devices) Control which sessions appear on your other devices A local session shows up on your other devices once [Remote Control](../02-Claude-Code-CLI/remote-control.md) connects it. A connected session appears in the session list at [claude.ai/code](https://claude.ai/code) and in the Claude apps on devices signed in to your claude.ai account. A local session connects when you turn Remote Control on for it, or when it connects automatically as it starts: - **You turn it on for that session**: with the session’s **Remote Control** switch, or by typing `/remote-control` in its prompt box. - **It connects when it starts**: new sessions connect automatically while **Connect new sessions to Remote Control** is on in **Settings \> Claude Code**. If you’ve never changed that setting, Desktop follows [`remoteControlAtStartup`](../02-Claude-Code-CLI/settings-reference.md#remotecontrolatstartup) in your user or managed settings, then your organization’s default. To see whether a session is connected, check the **Remote Control** switch in the **Environment** card of its [session details panel](#see-session-details). To keep sessions off your other devices, turn Remote Control off at the level you need: - **One session**: turn off its **Remote Control** switch. In a session that connected when it started, typing `/remote-control` leaves Remote Control on and shows `Remote Control is already on. This session connected automatically when it started.` Click **Turn off** on that line to disconnect. - **New Desktop sessions on this computer**: turn off **Connect new sessions to Remote Control** in **Settings \> Claude Code**. If it already shows off, turn it on and then off so Desktop saves your choice. Once saved, it takes precedence over `remoteControlAtStartup` and the defaults. - **Any session on this computer, including the CLI**: set [`disableRemoteControl`](../02-Claude-Code-CLI/settings-reference.md#disableremotecontrol) to `true` in `~/.claude/settings.json` to stop sessions from connecting. A session that was already connected when you saved the file stays connected until you turn Remote Control off for it. To hide a session that already appears on your other devices, archive it in Desktop. Desktop archives the session’s Remote Control copy too, so it leaves the default session list on those devices. To view or delete it there, see [Archive sessions](../02-Claude-Code-CLI/claude-code-on-the-web.md#archive-sessions). [​](#sessions-from-dispatch) Sessions from Dispatch [Dispatch](https://support.claude.com/en/articles/13947068) is a persistent conversation with Claude that lives in [Cowork](../15-Claude-AI-Features/product-cowork.md). You message Dispatch a task, and it decides how to handle it. A task can end up as a Code session in two ways: you ask for one directly, such as “open a Claude Code session and fix the login bug”, or Dispatch decides the task is development work and spawns one on its own. Tasks that typically route to Code include fixing bugs, updating dependencies, running tests, or opening pull requests. Research, document editing, and spreadsheet work stay in Cowork. [​](#follow-a-session-that-dispatch-started) Follow a session that Dispatch started The session that Dispatch starts appears in the Code tab’s sidebar with your other sessions. With the sidebar’s [default grouping and sorting](#organize-and-find-sessions), look for the newest session in the group for the folder it runs in. You get a push notification on your phone when it finishes or needs your approval. If you have [computer use](#let-claude-use-your-computer) enabled, Dispatch-spawned Code sessions can use it too. App approvals in those sessions expire after 30 minutes and re-prompt, rather than lasting the full session like regular Code sessions. [​](#set-up-dispatch) Set up Dispatch For setup, pairing, and Dispatch settings, see the [Dispatch help article](https://support.claude.com/en/articles/13947068). Dispatch requires a Pro or Max plan and is not available on Team or Enterprise plans. Dispatch is one of several ways to work with Claude when you’re away from your terminal. For a comparison with the other options, see [Platforms and integrations](../02-Claude-Code-CLI/platforms.md#work-when-you-are-away-from-your-terminal). [​](#extend-claude-code) Extend Claude Code Connect external services, add reusable workflows, customize Claude’s behavior, and configure preview servers. To manage connectors, skills, and plugins in one place, click **Customize** in the sidebar. [Cowork](../15-Claude-AI-Features/product-cowork.md) in the Desktop app sources its skills, plugins, and connectors from this Customize configuration, which syncs through your claude.ai account, not from the CLI’s `~/.claude` directory. Claude Code also loads the skills and plugins enabled for your claude.ai account in terminal sessions where you sign in with the same account. See [Skills synced from claude.ai](../08-Plugins-Skills/skills.md#how-synced-skills-behave) and [Plugins synced from claude.ai](../08-Plugins-Skills/plugins-loading.md#synced-plugins). [​](#connect-external-tools) Connect external tools Connectors are [MCP servers](../06-MCP-Tools/General/mcp.md) with a graphical setup flow. Click **+** next to the prompt box, before or during the session, to add connectors in a local or [SSH](#ssh-sessions) session with a Claude account. Select **Add connectors** to open the connector directory. If the menu shows **Connectors** instead, select it, then **Browse connectors**. These cases are covered on other pages: - **Connectors is grayed out in a WSL session**: see [If the terminal or connectors are unavailable](desktop-wsl.md#check-for-the-terminal-and-connectors) - **Cloud sessions**: see [How connectors reach Claude Code](../06-MCP-Tools/General/mcp.md#how-connectors-reach-claude-code) Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session. To manage or disconnect connectors, go to **Settings \> Connectors** in the desktop app. For integrations not listed in Connectors, add MCP servers manually via [settings files](../06-MCP-Tools/General/mcp.md#installing-mcp-servers). You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). [​](#use-skills) Use skills [Skills](../08-Plugins-Skills/skills.md) extend what Claude can do. Claude loads them automatically when relevant, or you can invoke one directly: type `/` in the prompt box or click the **+** button and select **Slash commands** to browse what’s available. This includes [built-in commands](../02-Claude-Code-CLI/commands.md), your [custom skills](../08-Plugins-Skills/skills.md#create-your-first-skill), project skills from your codebase, and skills from any [installed plugins](../08-Plugins-Skills/discover-plugins.md). Select one and it appears highlighted in the input field. Type your task after it and send as usual. You can send a command while Claude is working, the same as any other message, and the session returns to idle once the turn finishes. Local sessions load your personal skills from `~/.claude/skills/`. An [SSH](#ssh-sessions) session reads `~/.claude/skills/` from the remote host’s home directory, not from your machine. Local and cloud sessions also load the skills enabled for your claude.ai account, except local sessions when your organization sets [`disableSideloadFlags`](../02-Claude-Code-CLI/settings-reference.md#disablesideloadflags). Cloud sessions load them instead of `~/.claude/skills/`, as [Skills in Cowork and cloud sessions](../08-Plugins-Skills/skills.md#skills-in-cowork-and-cloud-sessions) describes. [​](#install-plugins) Install plugins [Plugins](../08-Plugins-Skills/plugins.md) are reusable packages that add skills, agents, hooks, MCP servers, and LSP configurations to Claude Code. You can install plugins from the desktop app without using the terminal. In a local session or an [SSH session](#ssh-sessions), click **+** next to the prompt box and select **Add plugins** to open the plugin browser. If the menu shows **Plugins** instead, select it, then **Browse plugins**, or **Manage plugins** to enable, disable, or uninstall plugins. You can scope plugins to your user account, a specific project, or local-only. If your organization manages plugins centrally, those plugins are available in desktop sessions the same way they are in the CLI, except the ones the desktop app [withholds under `disableSideloadFlags`](../02-Claude-Code-CLI/settings-reference.md#disablesideloadflags). The plugin browser is not available in cloud sessions, and plugins you install from the desktop app aren’t available for cloud sessions. A cloud session also doesn’t install plugins that the repository’s `.claude/settings.json` declares, as [What carries over from your setup](../02-Claude-Code-CLI/cloud-environments.md#what-carries-over-from-your-setup) explains. Plugins aren’t available in WSL sessions. For the full plugin reference including creating your own plugins, see [plugins](../08-Plugins-Skills/plugins.md). [​](#configure-preview-servers) Configure preview servers Claude automatically detects your dev server setup and stores the configuration in `.claude/launch.json` at the root of the folder you selected when starting the session. Preview uses this folder as its working directory, so if you selected a parent folder, subfolders with their own dev servers won’t be detected automatically. To work with a subfolder’s server, either start a session in that folder directly or add a configuration manually. To customize how your server starts, for example to use `yarn dev` instead of `npm run dev` or to change the port, edit `.claude/launch.json`. The file supports JSON with comments. ```python { "version": "0.0.1", "configurations": [ { "name": "my-app", "runtimeExecutable": "npm", "runtimeArgs": ["run", "dev"], "port": 3000 } ] } ``` You can define multiple configurations to run different servers from the same project, such as a frontend and an API. See the [examples](#examples) below. [​](#auto-verify-changes) Auto-verify changes When `autoVerify` is enabled, Claude automatically verifies code changes after editing files. It takes screenshots, checks for errors, and confirms changes work before completing its response. Auto-verify is on by default. Disable it per-project by adding `"autoVerify": false` to `.claude/launch.json`, or turn off **Auto-verify changes** in the Browser pane’s **⋮** menu. ```python { "version": "0.0.1", "autoVerify": false, "configurations": [ { "name": "my-app", "runtimeExecutable": "npm", "runtimeArgs": ["run", "dev"], "port": 3000 } ] } ``` When disabled, preview tools are still available and you can ask Claude to verify at any time. Auto-verify makes it automatic after every edit. [​](#configuration-fields) Configuration fields Each entry in the `configurations` array accepts the following fields: | Field | Type | Description | |---------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `name` | string | A unique identifier for this server | | `runtimeExecutable` | string | The command to run, such as `npm`, `yarn`, or `node` | | `runtimeArgs` | string\[\] | Arguments passed to `runtimeExecutable`, such as `["run", "dev"]` | | `port` | number | The port your server listens on. Defaults to 3000 | | `cwd` | string | Working directory relative to your project root. Defaults to the project root. Use `${workspaceFolder}` to reference the project root explicitly | | `env` | object | Additional environment variables as key-value pairs, such as `{ "NODE_ENV": "development" }`. Don’t put secrets here since this file is committed to your repo. For secrets, see [Set environment variables for dev servers](#set-environment-variables-for-dev-servers). | | `autoPort` | boolean | How to handle port conflicts. See [Port conflicts](#port-conflicts) | | `program` | string | A script to run with `node`. See [when to use `program` vs `runtimeExecutable`](#when-to-use-program-vs-runtimeexecutable) | | `args` | string\[\] | Arguments passed to `program`. Only used when `program` is set | | `url` | string | The address the preview opens instead of `http://localhost:`. See [open the preview at a specific URL](#open-the-preview-at-a-specific-url) | ##### When to use `program` vs `runtimeExecutable` Use `runtimeExecutable` with `runtimeArgs` to start a dev server through a package manager. For example, `"runtimeExecutable": "npm"` with `"runtimeArgs": ["run", "dev"]` runs `npm run dev`. Use `program` when you have a standalone script you want to run with `node` directly. For example, `"program": "server.js"` runs `node server.js`. Pass additional flags with `args`. ##### Open the preview at a specific URL By default, the preview opens `http://localhost:`. Set `url` when your server needs a different address. Common cases are servers that require local HTTPS, apps that use `*.localhost` subdomains, and apps that sign you in through a redirect. ```python { "version": "0.0.1", "configurations": [ { "name": "my-app", "runtimeExecutable": "npm", "runtimeArgs": ["run", "dev"], "port": 8443, "url": "https://localhost:8443" } ] } ``` Localhost addresses open directly, exactly like the default port address. This includes `localhost`, any `*.localhost` subdomain, `127.0.0.1`, and `::1`. For security, a localhost `url` must be your server’s origin alone, with no path or query. Its port must match the entry’s port. To show a specific page, ask Claude to navigate there after the preview opens. A localhost `url` with a path, query, or mismatched port is reported as a configuration error that names the url and shows the fix. For any other address, Desktop asks for your permission the first time the preview opens it, the same as when you browse to a new site in the preview. External addresses may include paths. Choose **Always allow** to skip the prompt for that site in the future. Organization policies that restrict external sites in the preview still apply. To preview a server you already run yourself, set `url` without a command. Claude attaches the preview to your running server instead of starting one: ```python { "version": "0.0.1", "configurations": [ { "name": "my-app", "url": "https://app.localhost:3000" } ] } ``` The `url` must be `http` or `https`, and must not contain a username or password. [​](#port-conflicts) Port conflicts The `autoPort` field controls what happens when your preferred port is already in use: - **`true`**: Claude finds and uses a free port automatically. Suitable for most dev servers. - **`false`**: Claude fails with an error. Use this when your server must use a specific port, such as for OAuth callbacks or CORS allowlists. - **Not set (default)**: your server gets the next free port, as with `true`, except in the one case below. Before Claude Desktop v2.37337.0, Claude asks whether the server needs that exact port instead, then saves your answer in `launch.json`. If your preferred port is in use and `autoPort` is unset, your server stays stopped when all of these hold: - You start the server through an `npm`, `yarn`, `pnpm`, or `bun` script. - Your preferred port is hardcoded in that script, or Claude can’t inspect the script. - You don’t pass the port in `runtimeArgs`. In that case, free the port, remove the hardcoded value, or change `port` to match the script. Setting `"autoPort": true` instead works only for a script that reads `PORT`. Have your server read its port from the `PORT` environment variable, which carries the assigned port. When Claude moves your server to a different port, it also rewrites a `--port` or `-p` value in `runtimeArgs` to match. [​](#examples) Examples These configurations show common setups for different project types: - Next.js - Multiple servers - Node.js script This configuration runs a Next.js app using Yarn on port 3000: ```python { "version": "0.0.1", "configurations": [ { "name": "web", "runtimeExecutable": "yarn", "runtimeArgs": ["dev"], "port": 3000 } ] } ``` For a monorepo with a frontend and an API server, define multiple configurations. The frontend uses `autoPort: true` so it picks a free port if 3000 is taken, while the API server requires port 8080 exactly: ```python { "version": "0.0.1", "configurations": [ { "name": "frontend", "runtimeExecutable": "npm", "runtimeArgs": ["run", "dev"], "cwd": "apps/web", "port": 3000, "autoPort": true }, { "name": "api", "runtimeExecutable": "npm", "runtimeArgs": ["run", "start"], "cwd": "server", "port": 8080, "env": { "NODE_ENV": "development" }, "autoPort": false } ] } ``` To run a Node.js script directly instead of using a package manager command, use the `program` field: ```python { "version": "0.0.1", "configurations": [ { "name": "server", "program": "server.js", "args": ["--verbose"], "port": 4000 } ] } ``` [​](#environment-configuration) Environment configuration The environment you pick when [starting a session](#start-a-session) determines where Claude executes and how you connect: - **Local**: runs on your machine with direct access to your files - **Cloud**: runs on Anthropic-managed infrastructure by default. Sessions continue even if you close the app. - **SSH**: runs on a remote machine you connect to over SSH, such as your own servers, cloud VMs, or dev containers. A running task can [keep going while Desktop is disconnected](#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires. - **WSL** (Windows): runs inside a [WSL 2 distribution](desktop-wsl.md) on your machine, using its Linux toolchain and native paths [​](#create-a-saved-environment) Create a saved environment A saved environment is an entry in the [environment selector](#start-a-session) that records where Claude runs, so you can start later sessions there. A local or SSH environment also holds the folders Claude works in. Saved local and SSH environments are part of the [current layout](#check-which-layout-you-have), so if you don’t see them, check which layout you have and how to get the current one. 1 Open the New environment dialog Open the environment selector under the prompt box and select **New environment** at the bottom of its menu. 2 Choose where Claude runs Select the **Local**, **SSH**, or [**Cloud**](#cloud-sessions) tab and fill in the form on that tab. On the **SSH** tab, choose a [connection](#ssh-sessions) and a folder on the remote machine. 3 Save the environment Select **Create environment**, or **Add environment** on the **Cloud** tab. [​](#environments-that-desktop-creates-for-you) Environments that Desktop creates for you If the environment selector lists local or SSH environments you didn’t create, Desktop created them for you. The first time you open the Code tab in the [current layout](#check-which-layout-you-have), Desktop creates up to eight environments. The environments come from the local and SSH folders you used most in the last month. You can [edit or delete them](#use-edit-or-remove-a-saved-environment). [​](#use-edit-or-remove-a-saved-environment) Use, edit, or remove a saved environment Find the environment’s entry in the [environment selector](#start-a-session): - **Start a session**: select the entry. - **Edit or delete**: hover over the entry and click the gear icon. To delete a local or SSH environment, click **Delete environment** in **Edit environment**. - **Archive cloud environments**: see [Archive an environment](../02-Claude-Code-CLI/cloud-environments.md#archive-an-environment). [​](#local-sessions) Local sessions The desktop app does not always inherit your full shell environment. On macOS, when you launch the app from the Dock or Finder, it reads your shell profile, such as `~/.zshrc` or `~/.bashrc`, to give Claude Code `PATH` and a fixed set of Claude Code variables, but not other variables you export there. On Windows, the app inherits user and system environment variables but does not read PowerShell profiles. [​](#set-environment-variables-for-local-sessions) Set environment variables for local sessions Add the variables to a saved local environment and start your sessions from it. Desktop [sets some variables itself](#environment-variables-desktop-sets-itself), such as `API_TIMEOUT_MS`, and your sessions get its value for those instead of yours. If your environment selector is above the prompt box, you have the [earlier layout](#check-which-layout-you-have), which has no saved local environments. Use the [local environment editor](#use-the-local-environment-editor) instead. 1 Open the environment's form Open [**New environment**](#create-a-saved-environment) or [**Edit environment**](#use-edit-or-remove-a-saved-environment). 2 Enter the variables Select **Environment variables**, enter one `KEY=value` per line, and select **Done**. 3 Save the environment Select **Create environment** or **Save**. Only sessions you start from that environment get the variables. To set a variable for every local session, add it to the [`env` key](../02-Claude-Code-CLI/env-vars.md#set-variables-in-settings-files) in your `~/.claude/settings.json` file. Claude Code [ignores the value](../02-Claude-Code-CLI/settings-reference.md#how-env-values-interact-with-your-shell) if that variable is already in the environment Desktop starts the session with. See [environment variables](../02-Claude-Code-CLI/env-vars.md) for the full list of supported variables. [​](#set-environment-variables-for-dev-servers) Set environment variables for dev servers To give a dev server a secret without committing it to [`launch.json`](#configure-preview-servers), set it in one of these places, then restart Desktop: - **macOS and Linux**: export it in your shell profile - **Windows**: add it to your user or system environment variables - **Any platform**: save it in the [local environment editor](#use-the-local-environment-editor), if you can open it Dev servers don’t get the variables you add to a [saved environment](#create-a-saved-environment) or to `~/.claude/settings.json`. [​](#use-the-local-environment-editor) Use the local environment editor To open the local environment editor, click the gear icon on the entry for your own computer, not the one on a saved environment: - **Selector under the prompt box**: hover over the entry for your computer, the first under **Local**. If a gear icon appears, click it. If not, the editor isn’t available, so set the variable for [local sessions](#set-environment-variables-for-local-sessions) or [dev servers](#set-environment-variables-for-dev-servers) another way. - **Selector above the prompt box**: hover over **Local** and click the gear icon Enter one `KEY=value` per line and select **Save changes**. Variables you save here are stored encrypted on your machine. Local sessions get them, except any variable that [Desktop sets itself](#environment-variables-desktop-sets-itself), such as `API_TIMEOUT_MS`. Restart Desktop to give your variables to dev servers. [​](#environment-variables-desktop-sets-itself) Environment variables Desktop sets itself If you set `API_TIMEOUT_MS` or `ANTHROPIC_BASE_URL` and nothing changed in your local sessions, it’s because Desktop sets those [variables](../02-Claude-Code-CLI/env-vars.md#variables), among others, itself. A local session gets Desktop’s value whether you set yours in your shell profile, your Windows user or system variables, the local environment editor, or a saved environment. Moving yours to a settings file doesn’t help, because Claude Code [ignores that value](../02-Claude-Code-CLI/settings-reference.md#how-env-values-interact-with-your-shell) in a local session. - `API_TIMEOUT_MS`: a local session gets `900000`, which is 15 minutes. For a longer timeout, [install the Claude Code CLI](../01-Getting-Started/quickstart.md) and use it instead of Desktop. [Set the variable in your shell](../02-Claude-Code-CLI/env-vars.md#set-variables-in-your-shell) and run `claude` in your terminal. - `ANTHROPIC_BASE_URL`: a local session gets Anthropic’s API host when you’re signed in with a Claude account. To use a gateway, set up Desktop’s [third-party inference configuration](../13-Enterprise-Admin/llm-gateway-connect.md#desktop-app) instead. [​](#turn-off-extended-thinking) Turn off extended thinking [Extended thinking](../02-Claude-Code-CLI/model-config.md#extended-thinking) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To turn it off, set `MAX_THINKING_TOKENS` to `0` in a [saved local environment](#set-environment-variables-for-local-sessions) or the [local environment editor](#use-the-local-environment-editor). Thinking then turns off on the Anthropic API, except on Opus 5.5, Sonnet 5.5, Haiku 5.5, and the Fable models, which always use extended thinking. On Opus 5, also select effort `high` or lower before you start the session. In the [current layout](#check-which-layout-you-have), open the model picker and select a level under **Effort**. If you started the session at a higher level, start a new one at `high` or lower. [​](#fixed-thinking-budgets) Fixed thinking budgets On models with [adaptive reasoning](../02-Claude-Code-CLI/model-config.md#adjust-effort-level), Claude Code ignores the number itself in a positive `MAX_THINKING_TOKENS` value because adaptive reasoning controls thinking depth instead. On Opus 4.6 and Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` to `1` to use a fixed thinking budget; Fable models, Sonnet 5 and later, Haiku 5.5, and Opus 4.7 and later always use adaptive reasoning and have no fixed-budget mode. [​](#local-sessions-on-managed-devices) Local sessions on managed devices If the entry for your computer is grayed out in the environment selector, with the tooltip **Disabled by your organization**, your administrator has [turned off local sessions](#managed-settings). On Windows the [WSL](desktop-wsl.md) entry, whose availability on managed devices is [governed separately](../13-Enterprise-Admin/admin-setup.md#wsl-sessions-in-claude-code-desktop), is grayed out the same way. New sessions default to the first SSH connection if one is configured. If you try to continue an existing local session, Desktop shows a message that local sessions aren’t available on this device. [Saved local environments](#create-a-saved-environment) show this error when you select one: `Couldn’t switch environments: the Local environment isn’t available anymore.` Choose an [SSH](#ssh-sessions) or [cloud](#cloud-sessions) environment instead, or contact your IT team. [​](#cloud-sessions) Cloud sessions Cloud sessions continue in the background even if you close the app. Usage counts toward your [subscription plan limits](../17-Billing-Plans/costs.md) with no separate compute charges. To add, edit, or [archive](../02-Claude-Code-CLI/cloud-environments.md#archive-an-environment) a cloud environment, open the [environment selector](#start-a-session): - **Add an environment**: select **New environment** at the bottom of the selector’s menu, then the **Cloud** tab of the [**New environment** dialog](#create-a-saved-environment) - **Edit or archive one of your own environments**: hover over it and click the gear icon See [Configure cloud environments](../02-Claude-Code-CLI/cloud-environments.md) for details on configuring network access and environment variables. [​](#ssh-sessions) SSH sessions SSH sessions let you run Claude Code on a remote machine while using the desktop app as your interface. This is useful for working with codebases that live on cloud VMs, dev containers, or servers with specific hardware or dependencies. If you use Desktop with a [third-party provider](../02-Claude-Code-CLI/third-party-integrations.md), SSH sessions need their own setup. See [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). Add an SSH connection in the [**New environment** dialog](#create-a-saved-environment), then start a session on that connection. If a new session has no environment selector under the prompt box, you have the earlier layout. See [Check which layout you have](#check-which-layout-you-have). 1 Open the New environment dialog Before you start a session, open the environment selector under the prompt box and select **New environment** at the bottom of its menu. 2 Add the connection On the **SSH** tab of the **New environment** dialog, open the **Host** list, select **Add SSH connection…**, and fill in the connection details: - **Name**: a friendly label for this connection. - **SSH host**: `user@hostname` or a host defined in `~/.ssh/config`. - **SSH port**: defaults to 22 if left empty, or uses the port from your SSH config. - **SSH key (optional)**: path to your private key, such as `~/.ssh/id_ed25519`. Leave empty to use your SSH config or SSH agent. - **Worktree folder**: a folder on the remote machine, such as `~/worktrees`, where new sessions create their worktrees. Leave empty to use the [remote machine’s default](#choose-where-ssh-session-worktrees-go). Then select **Add SSH connection**. 3 Start a session on the connection Select a folder on the remote machine and click **Create environment**. You keep the machine and folder together as a [saved environment](#create-a-saved-environment) for later sessions. Desktop selects it for the new session, so type your task and press **Enter**. The remote machine can run Linux, macOS, or [Windows](#windows-remote-machines). Desktop installs Claude Code on the remote machine automatically the first time you connect. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers. [​](#remote-machine-requirements-for-ssh-sessions) Remote machine requirements for SSH sessions A Linux or macOS remote machine needs a supported processor, an SSH server with SFTP, an install folder that isn’t mounted `noexec`, a working shell, and network access. Check each requirement before you connect, or when a connection fails after you log in: - **System**: an x86_64 or arm64 processor. The machine also has to meet Claude Code’s [system requirements](../01-Getting-Started/setup.md#system-requirements). On Linux, Claude Code needs glibc 2.17 or later, or musl. To see which one the machine has, run `ldd --version` there. On a musl-based distribution such as Alpine Linux, also install the [packages that Claude Code needs](../01-Getting-Started/setup.md#alpine-linux-and-musl-based-distributions). - **SFTP**: the SSH server has to offer the SFTP subsystem, which a `Subsystem sftp` line in its `sshd_config` turns on. To check, connect to the same host and port with `sftp` in a terminal on your computer. A working server shows the `sftp>` prompt. - **Sessions per connection**: Desktop on macOS and Linux opens several sessions on one SSH connection. If the server’s `sshd_config` sets `MaxSessions 1`, raise it, for example to OpenSSH’s default of 10. - **Install folder**: Desktop installs a helper program and Claude Code under `~/.claude/remote/` in your home directory. It runs them from there, so that folder can’t be on a file system mounted `noexec`. Allow about 1 GB of disk space in the home directory of each user who connects. For what that folder holds, see [Files and processes on the remote machine](#files-and-processes-on-the-remote-machine). - **Shell**: the shell set for your account on the remote machine has to run commands sent over SSH, as Bash, Zsh, and `sh` do - **Network**: Claude Code runs on the remote machine and makes its network requests from there, so the machine needs the [network access that Claude Code requires](../13-Enterprise-Admin/network-config.md#network-access-requirements). If the machine can’t download Claude Code, Desktop downloads it on your computer and uploads it. Claude Code’s other requests still go out from the remote machine. On a Linux remote machine, if those requests need a proxy, [set it for SSH sessions](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions). [​](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions) Set a proxy or a CA certificate for SSH sessions If a Linux remote machine reaches the internet through a proxy or needs a CA certificate, add the [proxy and CA variables](../13-Enterprise-Admin/network-config.md) under `env` in `~/.claude/settings.json` there. Add them even if you already export them in `~/.profile`, `~/.bash_profile`, `~/.zprofile`, or `~/.zshrc` on that machine. An SSH session doesn’t get them from those files, even when `claude` in a terminal on that machine does. The session can then hang, or show **The connection from … to the API failed** or **Authentication failed**, and signing in again doesn’t help. 1 Add the variables For the CA file, use [`NODE_EXTRA_CA_CERTS`](../13-Enterprise-Admin/network-config.md#custom-ca-certificates), because Claude Code doesn’t trust a CA from `SSL_CERT_FILE` in `~/.claude/settings.json`. This example sets a proxy and a CA file: ~/.claude/settings.json ```python { "env": { "HTTPS_PROXY": "http://proxy.example.com:8080", "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem" } } ``` 2 Send your message again Send your message again, because a variable that you add or change in that file takes effect within seconds. Start a new session if it still fails. ##### Find a proxy or CA variable set elsewhere on the remote machine Check whether the Linux remote machine sets the proxy or CA variable elsewhere, because sessions use that value and [ignore the one in any settings file](../02-Claude-Code-CLI/settings-reference.md#how-env-values-interact-with-your-shell): 1 List the variables that the remote machine sets In a terminal on your computer, run `ssh devbox env`, with your own host. 2 Change the variable where it is set If the list has the variable, change it in the file that sets it, such as `~/.zshenv`, `/etc/environment`, or `~/.bashrc` on the remote machine. 3 Give sessions the new value Restart the remote machine, or quit Desktop and end the helper’s processes, as in the first two steps to [remove the helper](#files-and-processes-on-the-remote-machine). Do this when no task is running, because either way interrupts Claude’s work. [​](#use-your-ssh-configuration-on-macos-and-linux) Use your SSH configuration on macOS and Linux On macOS and Linux, Desktop connects by running the OpenSSH client on your computer, so it uses your `~/.ssh/config`. Connecting through the OpenSSH client requires Claude Desktop v1.37937.0 or later. Enter a `Host` name from that file in the **SSH host** field to use settings from its entry, such as `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump`, and `ProxyCommand`. Before you add the connection, check the client and the entry in a terminal on your computer: - **Client version**: run `ssh -V`. The client has to be OpenSSH 7.6 or later. - **Entry**: run `ssh` with the `Host` name, such as `ssh devbox`. If that fails, fix the entry first. You can leave the **SSH port** and **SSH key (optional)** fields empty. If you fill one in, Desktop uses it with the entry: - **SSH port**: a value here overrides the entry’s `Port` - **SSH key (optional)**: Desktop offers the key file you pick in addition to the entry’s `IdentityFile` and the keys in your SSH agent ##### Reach a machine behind a jump host To reach a machine behind a jump host, also called a bastion, set `ProxyJump` or `ProxyCommand` in the entry. The following entry reaches `devbox.internal.example.com` through `bastion.example.com`: ~/.ssh/config ```python Host devbox HostName devbox.internal.example.com User alice ProxyJump bastion.example.com ``` Enter `devbox` in the **SSH host** field. If your administrator [restricts SSH hosts](#allow-jump-hosts), the jump host has to be on the list too. Run `ssh -G bastion.example.com` in a terminal on your computer, and ask them to allow the `hostname` that it prints. ##### Reach a container on a remote machine To run a session inside a container that publishes no SSH port, reach it with a `ProxyCommand`, because Desktop doesn’t run the `RemoteCommand` of the entry you connect to. If your entry uses `RemoteCommand` to step into the container, the session runs on the machine that the entry logs in to, not in the container. 1 Add the entry Add the following entry at the end of your `~/.ssh/config`, or directly above your first `Host *` entry if you have one. Replace the Docker container `devbox`, its user `dev`, and the machine `build.example.com` with your own. The entry’s command starts an SSH server inside the container for each connection: ~/.ssh/config ```python Host devbox-container User dev ProxyCommand ssh build.example.com docker exec -i devbox /usr/sbin/sshd -i ``` 2 Prepare the container - Install the OpenSSH server, with a host key that stays the same when you rebuild the image or recreate the container - Give the account named in `User` a way to log in, such as an `authorized_keys` file - Check that the container meets the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions) 3 Check the allowlist If your administrator [restricts SSH hosts](#restrict-which-ssh-hosts-users-can-connect-to), run `ssh -G devbox-container` in a terminal on your computer. Ask them to allow the `hostname` that it prints, here `devbox-container`, in `sshHostAllowlist`. When they allow that name, they allow whatever your entry’s `ProxyCommand` connects to. 4 Test the entry, then connect Run `ssh devbox-container` in a terminal on your computer. Fix what it reports, and run it again until it opens a shell in the container without asking you anything: - **If `ssh` asks for a password, passphrase, or code**: switch to a login that works without a prompt, such as a key that your SSH agent holds - **If `ssh` reports `Cannot execute command-line and remote command.` or `Bad packet length`**: take `RemoteCommand` and `RequestTTY` out of your entry for `build.example.com`. After that, `ssh build.example.com` in a terminal on your computer opens a shell on that machine, not in the container. - **If `ssh` reports `Connection closed by UNKNOWN port 65535`**: run `ssh build.example.com docker exec devbox /usr/sbin/sshd -t` in the same terminal. - If it prints `Missing privilege separation directory: /run/sshd`, create that folder in the container. - If it prints `no hostkeys available` and the container has host keys, add `-u root` after `exec` in this command and in the entry. Then enter `devbox-container` in the **SSH host** field. ##### Use variables from your shell in a `ProxyCommand` To use an environment variable of your own in a `ProxyCommand` or `Match exec` command, export it in a shell startup file, such as `~/.zshrc`, then quit and reopen Desktop. When Desktop starts, it reads what your login shell exports, and it keeps those values until you quit. This requires Claude Desktop v2.37337.0 or later and an `env` command that accepts `-0`, which you can check by running `env -0` in a terminal on your computer. If your shell sets temporary AWS credentials, [give the AWS CLI a profile](#use-aws-credentials-in-a-proxycommand) instead of exporting `AWS_*` variables. ##### Use AWS credentials in a `ProxyCommand` If you set temporary AWS credentials in a shell startup file, a `ProxyCommand` that runs the AWS CLI can connect in a terminal and fail in Desktop. When your shell exports `AWS_SESSION_TOKEN`, `AWS_SECURITY_TOKEN`, or `AWS_CREDENTIAL_EXPIRATION`, `ssh` and your `ProxyCommand` in Desktop don’t get the shell’s AWS credentials, `AWS_REGION`, or `AWS_PROFILE`. If the AWS CLI has no other source for a region or credentials, it fails with `You must specify a region` or `Unable to locate credentials`. To connect from Desktop, give the AWS CLI a profile that it reads from `~/.aws/config`: 1 Add a profile with a region and a source of credentials This example adds a profile named `corp` that gets its credentials from a helper program: ~/.aws/config ```python [profile corp] region = us-east-1 credential_process = /full/path/to/your-credential-helper ``` - **`region`**: give the AWS Region of the machines you connect to - **`credential_process`**: give the full path of a program that prints credentials in the [JSON form that AWS documents](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html). Choose a program that needs no input from you, because the AWS CLI runs it at every connection, including reconnects while you’re away. - **IAM Identity Center**: add the profile’s [IAM Identity Center settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) in place of `credential_process`. Run `aws sso login --profile corp` in a terminal before you connect, and again when that sign-in lapses. 2 Name the profile in the ProxyCommand This example adds `--profile` to the [command that AWS documents for Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-enable-ssh-connections.html): ~/.ssh/config ```python Host i-* ProxyCommand sh -c "aws ssm start-session --profile corp --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'" ``` 3 Connect again Run `ssh` with the host in a terminal to confirm that the entry still connects there, then connect from Desktop. ##### Raise the SSH connection timeout If your SSH configuration sets no `ConnectTimeout` for the host, Desktop gives `ssh` 30 seconds to connect. Through a jump host or a `ProxyCommand`, that time includes the time the route takes to connect. If your route needs longer, add a higher value to the entry: ~/.ssh/config ```python Host devbox HostName devbox.internal.example.com User alice ProxyJump bastion.example.com ConnectTimeout 120 ``` `ssh` uses the first value it finds for a host, so keep the entry above any `Host *` entry that sets `ConnectTimeout`. To confirm, run `ssh -G devbox` in a terminal on your computer. Its output includes `connecttimeout 120`. After you change the value, quit and reopen Desktop. If the remote machine itself waits for an approval on your phone, approve within 45 seconds, whatever `ConnectTimeout` you set. You can’t raise this limit, because Desktop sets `ServerAliveInterval` and `ServerAliveCountMax` itself, and `ssh` then closes a login in which the remote machine sends nothing for that long. If a jump host or a `ProxyCommand` waits for you instead, raise `ConnectTimeout` in the remote machine’s entry to cover that time. ##### Fix a `Match host` block that only Desktop applies If Desktop uses a setting that `ssh devbox` in a terminal doesn’t, look for a `Match host` block above the entry’s `HostName` line. In a terminal, `ssh` reads a block there before the `HostName` line, so it compares the block with `devbox`. Desktop gives `ssh` the `HostName` value on the command line, so `ssh` compares the block with that value. To check, run `ssh -G` in a terminal on your computer with the entry’s `HostName` and `User` values on the command line, as Desktop does: ```python ssh -G -o HostName=devbox.internal.example.com -l alice devbox ``` Compare the output with that of `ssh -G devbox`. If the block’s settings, such as `proxycommand`, show only in the first output, the block takes effect only in Desktop. To have Desktop skip it too, add `!originalhost devbox` to its `Match` line: ~/.ssh/config ```python Match host *.internal.example.com !originalhost devbox ``` To confirm, run the first command again. The block’s settings no longer show in its output. ##### Forwarding settings that Desktop leaves off On its connection to the remote machine, Desktop leaves `ForwardAgent`, `ForwardX11`, `LocalForward`, `RemoteForward`, `DynamicForward`, and `Tunnel` off, even where your SSH configuration turns them on. In the [terminal](#run-commands-in-the-terminal) or a `!` command, expect your forwarding settings to apply [only sometimes](#limits-while-desktop-is-disconnected), because Desktop can start a separate `ssh` there that follows them. - **To reach a port on the remote machine**: [forward it yourself](#reach-a-port-on-the-remote-machine) - **To use your own keys from the remote machine**: set up a credential on the remote machine itself, for example for `git push` To keep Desktop from forwarding your SSH agent or a port, run `ssh -G devbox` in a terminal on your computer. Then run it again as Desktop can run it, with the `hostname` and `user` values that it prints, as in `ssh -G -o HostName=devbox.internal.example.com -l alice devbox`. The second output can show settings from a `Match` block that the first skips. Look in both outputs for a `forwardagent` line that says anything but `no`, and for lines that begin with `localforward`, `remoteforward`, or `dynamicforward`. If you find one, remove that setting from your SSH configuration. Do the same for a host that your `ProxyCommand` reaches with `ssh`. [​](#reach-a-port-on-the-remote-machine) Reach a port on the remote machine To open a server that runs on the remote machine, such as a dev server on port 3000, forward the port yourself. In a terminal on your computer, run `ssh` with `-L` and the host you connect to, such as `devbox`: ```python ssh -N -L 3000:localhost:3000 devbox ``` If you filled in **SSH port** or **SSH key (optional)** on the connection, add `-p` or `-i` with the same value. Leave that command running, and open `http://localhost:3000` in a browser on your computer to reach port 3000 of the remote machine. If `ssh` prints `open failed: administratively prohibited`, ask the machine’s administrator to allow TCP forwarding, which `AllowTcpForwarding` in the SSH server’s `sshd_config` controls. [​](#windows-remote-machines) Windows remote machines A Windows remote machine requires Claude Desktop v2.31226.0 or later. Use Microsoft’s OpenSSH Server. The machine can be x64 or ARM64. The shell that the SSH server starts can be `cmd.exe`, Windows PowerShell 5.1, or Git Bash. Windows remote machines get less testing than Linux ones. Try your own work there before you rely on it. Expect these limits, among others, on a Windows remote machine: - **Terminal**: the [terminal](#run-commands-in-the-terminal) doesn’t open in a session whose folder is a Windows path, such as `C:/projects/app` - **Sandbox**: Claude Code runs there on native Windows, where it runs commands unsandboxed. See [where the sandbox runs](../02-Claude-Code-CLI/sandboxing.md). - **Plugins**: Desktop doesn’t copy a plugin that holds a file or folder name Windows can’t store, such as a name with `:`. The session lists the plugins that Desktop left out. - **MCP servers**: on some Windows remote machines, Claude’s calls to MCP servers from `claude_desktop_config.json` go through Desktop, so Claude can’t call their tools [while Desktop is disconnected](#limits-while-desktop-is-disconnected). Before Claude Desktop v2.37337.0, this holds on every Windows remote machine. - **Worktrees**: worktrees go in `/.claude/worktrees/`. If you [choose another folder](#choose-where-ssh-session-worktrees-go), Desktop ignores it. - **Earlier messages**: if the SSH server’s shell is `cmd.exe` or Windows PowerShell, you may have to connect before you see a session’s earlier messages - **Forks**: if the SSH server’s shell is `cmd.exe` or Windows PowerShell, you can fork a session only at its first message - **Running while disconnected**: a task [keeps running while Desktop is disconnected](#keep-a-task-running-while-desktop-is-disconnected) only if the SSH server lets a program outlive the connection that started it. To find out, [test the remote machine](#prepare-a-long-task). - **Leftover processes**: after a session ends, check the machine for programs that Claude Code started, because they can keep running. The [background helper](#keep-a-task-running-while-desktop-is-disconnected) that Desktop installs doesn’t stop on its own there. [​](#keep-a-task-running-while-desktop-is-disconnected) Keep a task running while Desktop is disconnected If your computer sleeps, you lose your network, or you quit Desktop, the task goes on until it finishes, needs you, or reaches one of the [limits](#limits-while-desktop-is-disconnected). Closing the lid counts as sleep. A restart of Desktop or of your computer, including for an update, counts as a quit. Claude Code runs as a process on the remote machine, under a background helper that Desktop installs there, so it doesn’t need your SSH connection to keep running. The behavior in this section requires Claude Desktop v2.31226.0 or later. If you sign in to Desktop with a Claude account, don’t count on a task to run overnight. Desktop renews that sign-in for the task only while Desktop is running and connected, so the task’s sign-in can expire after you disconnect, and the task then stops. How much time is left when you disconnect varies, and it can be only a few minutes.The work done so far stays on the remote machine, and you can continue with a message when you return.If the task must run through the night: - [Keep your computer awake](desktop-scheduled-tasks.md#how-scheduled-tasks-run) and online, with the lid open and Desktop running - Use a login that works without a prompt, such as a key that your SSH agent holds, for the remote machine and for any jump host on the way. Desktop can then reconnect on its own after a drop. For a task that must run while your computer is asleep or off, start a [cloud session](#run-long-running-tasks-in-the-cloud) instead. - **After sleep or a network loss**: you get the running task back if the process [still runs](#limits-while-desktop-is-disconnected) and Desktop can log in without a prompt. If it can’t, [send a message](#reconnect-after-sleep-or-a-network-loss). - **After a quit**: the task keeps running, but you lose it when the session opens again unless Desktop can rejoin its process. Check [when Desktop can rejoin](#reopen-a-session-after-you-quit-desktop) before you quit. If you lost the task, send a message to continue. When you come back and the task isn’t done, check for word that Desktop can’t reconnect, an authentication error, or a waiting request: - **Desktop can’t reconnect**: the session says why, and a notification may say so too. Desktop may [need you to log in](#reconnect-after-sleep-or-a-network-loss). - **Authentication error**: the [sign-in token or credential](#limits-while-desktop-is-disconnected) may have expired. With a Claude account, send a message to continue. With a third-party provider, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). - **Waiting request**: [answer it](#handle-requests-that-arrive-while-you-are-away) - **None of these**: send a message to continue ##### Prepare a long task - **Update first**: update Desktop before you start a long task. On macOS and Windows, Desktop can restart on its own to install an update that it has downloaded. That restart waits while Claude is working on an SSH task. On macOS with a Claude account, by default the restart can go ahead anyway once the update has waited 72 hours. - **Don’t quit on Windows, or before v2.42304.0 with a third-party provider**: after a quit there you lose the running task, so leave Desktop open during the task. In any other case, see [what you get back](#reopen-a-session-after-you-quit-desktop) before you quit. - **Reduce requests**: choose a permission mode, rules, or hooks that [make the task wait for you less often](#handle-requests-that-arrive-while-you-are-away) - **Check the jump host**: if your jump host asks for a sign-in, for example a push to a phone, switch to a login that works without a prompt. Otherwise Desktop can send another push each time it tries to reconnect. - **Test the remote machine**: start a short task, quit Desktop while the task is still running, and open the session again well after the task should be done. If the task isn’t finished and the session shows no authentication error, check the remote machine for [what can end a task](#limits-while-desktop-is-disconnected). - **Keep commands out of Desktop’s terminal**: if the remote machine [logs out idle terminals](#limits-while-desktop-is-disconnected), run your own commands from an SSH login outside Desktop ##### Limits while Desktop is disconnected A task that you leave running can end when its sign-in expires, when the remote machine ends it, or when the helper stops or is replaced: - **Sign-in token or credential**: with a Claude account, the task stops with an authentication error when the token expires. With a third-party provider, the same holds for a credential that expires, such as one from single sign-on or a credential helper. See [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). With a Claude account, [keep Desktop running and connected](#keep-a-task-running-while-desktop-is-disconnected) so that it can renew the sign-in. - **The remote machine**: if the remote machine restarts, or ends your processes when your SSH connection closes, the running task ends. Nothing starts it again while Desktop is disconnected. Linux machines where systemd-logind’s `KillUserProcesses` is `yes` and applies to your user end your processes this way. To keep a task running there, ask the administrator to exempt your user, for example with `KillExcludeUsers`. - **Idle terminals**: some Linux remote machines log out a terminal that nobody types in for a set time (systemd-logind’s `StopIdleSessionSec`). With Desktop on macOS or Linux, a session’s [terminal](#run-commands-in-the-terminal) and `!` commands share Desktop’s SSH connection by default. That logout then ends the connection while Desktop is connected, and the running task can end with it. Closing the terminal pane doesn’t prevent it, so [keep commands out of that terminal](#prepare-a-long-task). - **Desktop updates**: if an update brings a new helper, Desktop replaces the helper on the remote machine at a later connection, which can end a task that still runs - **Long absences**: on a Linux or macOS remote machine, if Desktop doesn’t connect for 30 days, the helper stops and ends every Claude Code process that runs under it. Connect before then. File edits and some tools can fail while Desktop is disconnected. If the task needs them, keep Desktop connected: - **Worktrees**: in a session that uses a [worktree](#run-a-session-in-its-own-worktree), Desktop checks each file edit before Claude makes it. While Desktop is disconnected, each edit waits about 30 seconds and then fails. Shell commands still run. On a Linux or macOS remote machine, [edits can keep working](#worktree-edits-while-disconnected). If you aren’t sure, start the session without a worktree. - **Folder restrictions**: if your organization restricts which folders sessions may use, Desktop checks each file read, search, and edit, with or without a worktree. While Desktop is disconnected, each one waits up to 10 minutes and then fails. - **Connectors**: [connectors](#connect-external-tools) and other tools that Desktop provides run through Desktop, so while it is disconnected each call fails after about 30 seconds - **Workflows**: Desktop checks each new [workflow](../02-Claude-Code-CLI/workflows.md) before it starts, so while Desktop is disconnected a new one waits up to 10 minutes and then fails - **MCP servers**: MCP servers that Claude Code starts on the remote machine don’t run through Desktop, so Claude can still call their tools. Servers from `claude_desktop_config.json` are among them only if Desktop doesn’t use its [built-in SSH client](#worktree-edits-while-disconnected). Otherwise, and on [some Windows remote machines](#windows-remote-machines), Claude can’t call their tools while Desktop is disconnected. When edits in a worktree keep working On a Linux or macOS remote machine, the check doesn’t go through Desktop, so edits inside the worktree keep working while Desktop is disconnected. Before Claude Desktop v2.37337.0, this holds on a Linux remote machine only.Edits still fail in some cases, including these: - **Built-in SSH client**: Desktop uses it, for example in a Microsoft Store install, on a Windows computer without Microsoft’s OpenSSH 9.4 or later, or by default on Windows with a third-party provider - **Repository location**: the repository is your home directory, a folder above it, or `~/.claude` - **macOS paths**: on a macOS remote machine, the repository is under `/Volumes`, or a folder name in the path of the repository or the worktree has a `~` or a non-ASCII character - **Folder restrictions**: your organization restricts which folders sessions may use - **Corporate launcher**: before Claude Desktop v2.37337.0, you sign in with a Claude account, and your organization starts Claude Code on the remote machine through a [corporate launcher](../13-Enterprise-Admin/corporate-launcher.md) A session without a worktree has no such check, unless your organization restricts which folders sessions may use. ##### Handle requests that arrive while you are away If Claude needs your approval or asks you a question while Desktop is disconnected, Claude waits on the remote machine. The wait has no time limit of its own. When Desktop rejoins the process, it shows you the request. If Desktop starts a new process instead, you lose the request. If a request that waited for you is gone when you come back, one cause is that Desktop restarted on its own, for example to install an update. You keep a request through a restart only if Desktop can rejoin the process, so check [when Desktop can rejoin](#reopen-a-session-after-you-quit-desktop) before you leave a task running. If you lose a request, send a message to continue. To reduce how often a task stops to wait for you, and to hear from it while you are away, set up any of these before you leave: - **Auto mode**: choose [Auto mode](#choose-a-permission-mode) if [it is available to you](#auto-mode-availability). After repeated blocks, you are [asked again](../02-Claude-Code-CLI/permission-modes.md#when-auto-mode-falls-back). - **Allow rules**: in your user settings file on the remote machine, `~/.claude/settings.json`, add [allow rules](../02-Claude-Code-CLI/permissions.md#manage-permissions) for the commands the task needs. If your organization [accepts permission rules from managed settings only](../02-Claude-Code-CLI/settings-reference.md#allowmanagedpermissionrulesonly), ask your administrator to add them to the [managed settings](#managed-settings) that reach the remote machine. For allow rules in a project’s `.claude/settings.json`, see [Project allow rules and workspace trust](../02-Claude-Code-CLI/permissions.md#project-allow-rules-and-workspace-trust). - **A hook that answers**: configure a [`PermissionRequest` hook](../07-Hooks/hooks.md#permissionrequest) in `~/.claude/settings.json` on the remote machine to allow or deny requests in your place - **A hook that alerts you**: configure a [`Notification` hook](../07-Hooks/hooks.md#notification) with the `permission_prompt` matcher in the same file to send yourself a message when a request is waiting - **A hook that tells you when Claude is done**: configure a [`Stop` hook](../07-Hooks/hooks.md#stop) in the same file to send yourself a message when Claude has finished responding. It doesn’t run when an API error ends the turn. For that case, configure a [`StopFailure` hook](../07-Hooks/hooks.md#stopfailure). If your organization [runs managed hooks only](../02-Claude-Code-CLI/settings-reference.md#allowmanagedhooksonly), ask your administrator to add the hook to the [managed settings](#managed-settings) that reach the remote machine. Claude Code doesn’t auto-approve [a few actions](../02-Claude-Code-CLI/permission-modes.md#actions-no-mode-auto-approves) in any permission mode, including Bypass permissions. Depending on the permission mode, Claude Code denies such an action or asks you, and the task then waits for your answer. ##### Reconnect after sleep or a network loss If Desktop hasn’t reconnected when you come back, send a message in the session. Desktop reconnects on its own only where it can log in without a prompt, for example with a key that your SSH agent holds. - **Remembered password**: a password that you let Desktop remember also works without a prompt, but for a long absence prefer a key that your SSH agent holds. If sign-ins with that password break off or hang, Desktop can stop reconnecting and wait for you. - **Any other prompt**: if the remote machine prompts for anything else, such as a one-time code, you can get a notification on your computer. Click the notification, or send a message in the session, and Desktop shows the prompt. If a jump host asks for a sign-in, the outage is long, output is missing, or the process is gone - **Jump host, pushes stop while you’re away**: this can happen with Desktop on macOS or Linux when nobody answers a jump host’s sign-in, for example a push to a phone. Desktop then stops reconnecting while nobody is at your computer. When you unlock or use the computer, you can get another push, because Desktop can try again. After three unanswered attempts it waits until you retry or send a message. - **Jump host, pushes keep coming**: where Desktop can’t tell that nobody answers, as with Desktop on Windows, it keeps trying while it has a process to rejoin, whether or not that process still runs. You can get another push with each attempt. To end the attempts, quit Desktop, which [can cost you the running task](#reopen-a-session-after-you-quit-desktop). - **Long outage**: Desktop slows to about one attempt every five minutes. To reconnect sooner, retry in the session or send a message, which Desktop delivers once it is connected. - **Missing output**: while Desktop is disconnected, the helper keeps each session’s most recent Claude Code output in a 16 MiB buffer and drops older output. After Desktop reconnects, the session can show `Loading recent output from …`. If Desktop can’t load all of the output, you see the row `Some output produced while you were disconnected may be missing here.` The row doesn’t mean that the task stopped. - **Process gone**: the process ended while Desktop was disconnected, as when the remote machine restarts. Desktop can then start a new one from the conversation’s saved history and tell Claude to continue the task. If the task stays stopped, send a message. With a third-party provider, update to Claude Desktop v2.42304.0 or later, because earlier versions never continue the task on their own. ##### Reopen a session after you quit Desktop After you quit Desktop, the task keeps running on the remote machine, but it stops when the session opens again unless Desktop can rejoin its process. While Desktop is closed, the task runs until it finishes, needs you, or reaches one of the [limits](#limits-while-desktop-is-disconnected). - **Desktop on Windows**: you don’t get the running task back, because Desktop never rejoins after a quit. Start Desktop again only when you expect the task to be done, because the session can open as Desktop starts. - **Third-party provider, task from an earlier version**: if you started the task in a Desktop version before v2.42304.0, you don’t get it back on macOS or Linux either. Start Desktop again only when you expect the task to be done. - **Any other task, with Desktop on macOS or Linux**: start Desktop and open the session, and the task goes on if Desktop rejoins. It can’t always rejoin, for example after some Desktop updates, so [update before a long task](#prepare-a-long-task). When Desktop can’t rejoin, you also lose any approval or question that was waiting for you. If the task doesn’t continue on its own, send a message, and Claude continues from the conversation’s saved history. For third-party deployments, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). While a conversation’s Claude Code process is still running, don’t run [`claude --resume`](../02-Claude-Code-CLI/cli-reference.md#cli-flags) for it on the remote machine. Claude Code doesn’t stop you, and both processes then write to the same conversation. If you aren’t sure, add `--fork-session`, which continues in a copy of the conversation, but both processes still work on the same files. [​](#choose-where-ssh-session-worktrees-go) Choose where SSH session worktrees go Unless your organization restricts which folders sessions may use, new SSH sessions create their [worktrees](#run-a-session-in-its-own-worktree) in the first of these locations that is set: 1. **Worktree folder** on the SSH connection 2. [`worktree.location`](../02-Claude-Code-CLI/settings-reference.md#worktree-location) in `~/.claude/settings.json` on the remote machine 3. `/.claude/worktrees/`, the default Each project gets its own subfolder in the folder you set, so with `~/worktrees` a worktree’s path is `~/worktrees/-/`. If the folder you set is inside the project, Desktop ignores it for that project and uses the default. On a [Windows remote machine](#windows-remote-machines), Desktop always uses the default. ##### Set the worktree folder on an existing connection Set **Worktree folder** in the settings of a connection you added earlier or one your organization manages. The field requires Claude Desktop v1.44121.0 or later. If your organization restricts which folders sessions may use, Desktop hides the field and keeps worktrees inside the project. 1 Find the connection Open the [environment selector](#start-a-session) and find the connection under **SSH**. 2 Open the connection's settings Hover over the connection and click the gear icon. If the dialog that opens shows **Edit connection…** next to **Host**, select **Edit connection…**. 3 Set the folder In **Worktree folder**, enter a folder on the remote machine, such as `~/worktrees`, and select **Save changes**. [​](#files-and-processes-on-the-remote-machine) Files and processes on the remote machine Desktop installs a helper program and Claude Code under `~/.claude/remote/` in the home directory of each user who connects to a Linux or macOS remote machine. The helper listens on no network port, but Claude Code and the programs it starts, such as MCP servers and development servers, can. | Folder | Contents | |--------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| | `~/.claude/remote/srv/` | The helper, in one folder per version | | `~/.claude/remote/ccd-cli/` | Claude Code, in one file per version | | `~/.claude/remote/run/` | The helper’s runtime files, such as its socket and log, in one folder per computer that connects | | `~/.claude/remote/plugins/` | Plugins that Desktop copies from the user’s computer | | [`~/.claude/uploads/`](../02-Claude-Code-CLI/claude-directory.md#clear-local-data) | Files that the user attaches to messages, in one folder per session | To list one user’s processes, run `pgrep -fl "$HOME/.claude/remote/"` on the remote machine as that user, or with the user’s home directory in place of `$HOME`: - **Helper**: one or more `server` processes for each computer that connects - **Claude Code**: the processes that the helper starts for the user’s sessions, each from a file named after its version, such as `2.1.295-…` Desktop reaches the helper through the user’s SSH connection, over the Unix socket `rpc.sock` in the helper’s folder under `~/.claude/remote/run/`. Apart from root, other users on the machine can’t connect to that socket, because it has mode 600 and its folder has mode 700. For when the helper stops on its own, see [Limits while Desktop is disconnected](#limits-while-desktop-is-disconnected). To remove the helper and Claude Code for one user: 1 Quit Desktop Quit Desktop on each computer that the user connects from. It installs both programs again the next time it connects, and it can reconnect on its own. 2 End the processes Logged in as that user on the remote machine, run `kill` with the ID of each Claude Code process that [`pgrep`](#files-and-processes-on-the-remote-machine) lists. Once those are gone from the list, run `kill` with the ID of each `server` process. If you end a `server` process first, a command that Claude Code is running can keep running.Then list the user’s remaining processes, for example with `ps -u "$(id -un)" -f`, and end any that you recognize as started by Claude Code. Programs that it left in the background can keep running after it ends, without being in the `pgrep` list. 3 Delete the folder Delete `~/.claude/remote/`. To remove Claude Code’s own files in `~/.claude/` and `~/.claude.json`, see [Remove configuration files](../01-Getting-Started/setup.md#remove-configuration-files). ##### End one session’s process To end one session’s Claude Code process, [archive the session](#archive-a-session) in Desktop while Desktop is connected to the remote machine. The process keeps running after its task is done and after you quit Desktop. Before you archive a session whose worktree has uncommitted changes, see [Keep uncommitted changes when a session is archived](#keep-uncommitted-changes-when-a-session-is-archived). ##### See which user the processes run as The helper and Claude Code run as the user that Desktop logs in as over SSH. Installing and starting them takes no `sudo`. To check the user, run `ps -o user= -p` on the remote machine with a process ID that [`pgrep`](#files-and-processes-on-the-remote-machine) lists. Programs that Claude Code starts, such as shell commands and MCP servers, start as that user too. Review that user’s rights on the remote machine, its `sudo` rules included, as you would for a person who runs commands there. ##### See who connected to the remote machine To find out who connected to a remote machine, read the SSH server’s log on that machine, where a login from Desktop looks like one from a terminal. With Desktop on macOS or Linux, expect an entry each time Desktop connects, not one for each session. You won’t find Desktop’s SSH connections in Claude Code’s [metrics and events](../13-Enterprise-Admin/monitoring-usage.md#available-metrics-and-events). To find out from them which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](../13-Enterprise-Admin/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions). For Desktop’s own record of its connections, see [Get Desktop’s logs for an SSH problem](#get-desktops-logs-for-an-ssh-problem). [​](#connections-that-close-before-login) Connections that close before login If the SSH server’s log shows connections that close before any login, they can be Desktop’s tests of the SSH port. Desktop tests whether a machine answers, for example after a connection to it failed. It opens a connection to the port and closes it at once, without sending anything. Expect one test or several in a row, for example eight in about two minutes. If nothing bans or refuses addresses for such connections, you don’t have to do anything about Desktop’s tests. If an address that Desktop connects from is refused or banned, check [whether the SSH server itself refuses the address](#check-whether-the-ssh-server-itself-refuses-the-address) and [whether fail2ban counts Desktop’s tests](#check-whether-fail2ban-counts-desktops-tests). ##### Recognize a test in the SSH server’s log Compare the lines in your log with those that an OpenSSH server on Linux writes for a test at the default `LogLevel`, in the row for your server’s version. You can see the lines in the last column instead if the server’s greeting arrives before Desktop closes the connection: | OpenSSH version | Lines for a test | Lines if the greeting arrives first | |-----------------|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| | 6.6 to 7.9 | A line with `Did not receive identification string from 203.0.113.7` | The same line | | 8.0 to 8.2 | `error: kex_exchange_identification: Connection closed by remote host` | `error: kex_exchange_identification: read: Connection reset by peer` | | 8.3 to 9.4 | `error: kex_exchange_identification: Connection closed by remote host`, then `Connection closed by 203.0.113.7 port 51234` | `error: kex_exchange_identification: read: Connection reset by peer`, then `Connection reset by 203.0.113.7 port 51234` | | 9.5 to 10.2 | `Connection closed by 203.0.113.7 port 51234` | `error: kex_exchange_identification: read: Connection reset by peer`, then `Connection reset by 203.0.113.7 port 51234` | | 10.3 to 10.5 | `Connection closed by 203.0.113.7 port 51234 [preauth]` | `error: kex_exchange_identification: read: Connection reset by peer [preauth]`, then `Connection reset by 203.0.113.7 port 51234 [preauth]` | Other programs that open the port and close it can leave the same lines. Where a line has an address, check that it is one that a computer with Desktop connects from. The lines of 8.0 to 8.2 have no address. To get one, set `LogLevel VERBOSE` in `sshd_config` and run `sshd -T | grep -i loglevel` as root. If it prints `loglevel VERBOSE`, reload the SSH server. Then look for a line with `Connection from 203.0.113.7 port 51234` before the test’s line. ##### Check whether the SSH server itself refuses the address If connections are refused from an address that many computers with Desktop share, look in the SSH server’s log for a line that ends like this one: ```python drop connection #0 from [203.0.113.7]:51234 on [192.0.2.10]:22 penalty: connections without attempting authentication ``` With the default `LogLevel`, OpenSSH 9.8 and later can write such a line when refusing an address for connections that closed without trying to log in, as Desktop’s tests do. With the default settings, you don’t see such a line after a few tests alone. To prevent the refusal, set `PerSourcePenaltyExemptList` in `sshd_config` to the addresses that people connect from, for example `PerSourcePenaltyExemptList 203.0.113.7`. The server then applies none of its penalties to those addresses, including those for failed logins. To check the file, run `sshd -T | grep -i persourcepenalt` as root. If it prints your list, reload the SSH server. ##### Check whether fail2ban counts Desktop’s tests If fail2ban 0.10.5 or later banned an address that Desktop connects from, find your jail’s mode in `jail.conf`, `jail.local` or under `jail.d/`: - **A `filter` line that names a mode in brackets**, such as `filter = sshd[mode=aggressive]`: use that mode. - **Only the stock `filter` line**, with `[mode=%(mode)s]`: use the `mode` line, or `normal` if there is none. If the mode is `normal`, fail2ban doesn’t count the lines of Desktop’s tests, so look for another cause of the ban. For another mode, copy the lines from your own log to a file on the remote machine. Copy each line whole, from its date to its end, and both lines where a test leaves two. Run `fail2ban-regex` there with the file and your jail’s mode, for example `aggressive`: ```python fail2ban-regex -o ip lines.log "sshd[mode=aggressive]" ``` For each failure that fail2ban counts, the command prints the address on a line of its own, such as `203.0.113.7`. In that case, [prevent a ban](#prevent-a-ban-by-fail2ban). If it prints nothing, fail2ban counts none of those lines in that mode, so look for another cause of the ban. ##### Prevent a ban by fail2ban To keep fail2ban from banning an address for Desktop’s tests, change one of two settings of the jail, each at a cost: - **`mode`**: set it to `normal` wherever your jail sets it, in a `mode` line or in the brackets of a line such as `filter = sshd[mode=aggressive]`. You give up every count that only the other modes make, for example of clients that connect and leave without trying to log in. - **`ignoreip`**: set it to the addresses that people connect from, for example `ignoreip = 203.0.113.7`. fail2ban then counts nothing from those addresses, failed logins included. [​](#use-mcp-servers-set-up-on-the-remote-machine) Use MCP servers set up on the remote machine To use an [MCP server](../06-MCP-Tools/General/mcp.md) from `~/.claude.json` or a project’s `.mcp.json` in an SSH session, set it up in those files on the remote machine. Claude Code starts their stdio servers there, so install the commands those servers run on the remote machine. For servers from `claude_desktop_config.json`, see [Limits while Desktop is disconnected](#limits-while-desktop-is-disconnected). [​](#open-an-ssh-session-from-a-link) Open an SSH session from a link A `claude://code/new` link opens Desktop’s new-session page, and it can name an SSH connection. Put such a link in a runbook, dashboard, or wiki page to open Desktop set up for the right machine and folder. For platforms that strip such links, see [The link renders as plain text instead of being clickable](../02-Claude-Code-CLI/deep-links.md#the-link-renders-as-plain-text-instead-of-being-clickable). SSH links require Claude Desktop v2.110.0 or later. The following link names the user `dev` on `build.example.com`, port 2222, and the folder `/srv/payments`, and fills in a prompt: ```python claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=/srv/payments&q=Investigate%20the%20failed%20deploy ``` An SSH link takes these parameters, and only `ssh_host` is required: | Parameter | Value | |:-------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `ssh_host` | `host` or `user@host`, written as in the **SSH host** field. The value can’t start with `-`, and the host part takes only letters, digits, `.`, `_`, `:`, and `-` | | `ssh_port` | A port number from 1 to 65535 | | `ssh_folder` | A folder on the remote machine. Start it with `/` or `~/`, or use `~` | | `q` | URL-encoded text for the prompt box | An alias from `~/.ssh/config` works as `ssh_host` only for people who have that entry. To match a connection people already have, give the link the same user, host, and port as that connection. When you open the link, Desktop asks you to confirm before it selects the connection: - **A connection you already have**: if the host, user, and port match one of your connections, Desktop asks whether to use it, and shows you the connection’s name and host, and the folder if the link names one. - **A new connection**: otherwise Desktop opens the dialog for adding an SSH connection. When you add the connection, Desktop asks whether to connect before it saves anything, and shows you the host from the link, and the port and folder if the link names them. Until you confirm, Desktop doesn’t save the host, port, or folder from the link, and doesn’t select or open a connection with them. If an SSH connection is already selected, the new-session page can still connect to it on its own, as it does without a link, even when the link names the same host. A link can’t carry a key file, a password, or a command. Anyone can write a link, so check what it filled in: - **Before you confirm**: check the host and folder. - **Before you send**: check the prompt and the selected environment. Desktop fills in the prompt when the link opens, in place of any text you haven’t sent, and never sends it for you. It treats the prompt as plain text, so a leading `/` or `!` and an `@` file mention don’t act as a command or a mention. If you cancel, the prompt stays in the box and the environment you had selected doesn’t change. A link doesn’t bypass [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to). Desktop checks the allowlist when it connects. If the link opens Desktop without a dialog about the connection, look for one of these causes: - **You’re signed out**: sign in, then open the link again. - **Another dialog is open**: close it, then open the link again. - **The link isn’t valid**: Desktop shows a message that says what to fix, and doesn’t fill in the prompt. - **Desktop is older than v2.110.0**: earlier versions ignore the SSH parameters and open the new-session page with only the prompt. - **SSH sessions are turned off**: if your administrator sets the allowlist to an empty array, Desktop refuses SSH links. [​](#pre-configure-ssh-connections-for-your-team) Pre-configure SSH connections for your team Administrators can distribute SSH connections to team members by setting `sshConfigs` in [managed settings](../13-Enterprise-Admin/managed-settings.md). - **What users see**: connections defined this way appear in each user’s environment selector automatically. - **What users can change**: users can select a managed connection and [set their own **Worktree folder**](#set-the-worktree-folder-on-an-existing-connection) for it. They can’t edit its other fields or delete it in the app. The following example pre-configures a single connection: ```python { "sshConfigs": [ { "id": "shared-dev-vm", "name": "Shared Dev VM", "sshHost": "user@dev.example.com", "sshPort": 22, "sshIdentityFile": "~/.ssh/id_ed25519" } ] } ``` Each entry requires `id`, `name`, and `sshHost`. The `sshPort` and `sshIdentityFile` fields are optional. Users can also add `sshConfigs` to their own `~/.claude/settings.json`. If you leave `user@` out of `sshHost`, Desktop connects as the `User` that each developer’s `~/.ssh/config` sets for the host, or else as their username on their own computer. [​](#restrict-which-ssh-hosts-users-can-connect-to) Restrict which SSH hosts users can connect to Administrators can limit Desktop’s SSH sessions to an approved set of hosts by setting `sshHostAllowlist` in [managed settings](../13-Enterprise-Admin/managed-settings.md). When set, users can only connect to hosts whose resolved hostname matches one of the patterns. Set it to an empty array to disable SSH sessions. The [`sshHostAllowlist` reference entry](../02-Claude-Code-CLI/settings-reference.md#sshhostallowlist) says how an empty array combines with lists in other managed sources. The following example allows connections to any host under `devboxes.example.com` and to a single named bastion host: ```python { "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"] } ``` If your organization delivers [server-managed settings](../13-Enterprise-Admin/server-managed-settings.md), set `sshHostAllowlist` there. By default, Desktop reads the key only from the [highest-ranked managed source that delivers a policy key](../13-Enterprise-Admin/managed-settings.md#how-claude-code-combines-managed-sources). If that source leaves the key unset, Desktop ignores a list in a lower-ranked MDM policy or managed settings file and treats the key as [unset](../02-Claude-Code-CLI/settings-reference.md#sshhostallowlist). Desktop shows no warning.Also keep the same list on each user’s machine, in the highest-ranked MDM policy or managed settings file there. Desktop fetches server-managed settings at launch and keeps no cached copy, so until a fetch succeeds the machine’s list is the one that applies. Patterns are case-insensitive. `*` matches any host, and `*.example.com` matches `example.com` and any subdomain. Anything else is an exact match. The check runs against the hostname after `~/.ssh/config` resolution via `ssh -G`, so a `Host` alias is permitted as long as its resolved `HostName` matches. A session’s [jump hosts](#allow-jump-hosts) have to match too. `sshHostAllowlist` is read from managed settings only; values in user or project settings are ignored. Only the Claude Desktop app honors this setting; the Claude Code CLI and IDE extensions do not read it, and it does not restrict `ssh` commands run through the Bash tool. It governs which hosts the Desktop app connects to, not network egress, so pair it with your organization’s network or zero-trust controls if you need a hard boundary. ##### Allow jump hosts Add each jump host that Desktop checks to `sshHostAllowlist`, by its own resolved `HostName`. Add the jump hosts before users update to Claude Desktop v3.1623.0 or later, or they can’t connect through them. The list has one kind of entry, so users can also start a session on any host that you list. List only jump hosts that you’d also let users run sessions on. Desktop checks jump hosts in the `ProxyJump` that the user’s `~/.ssh/config` sets for the session’s host, or in a `ProxyCommand` written as `ssh -W %h:%p `. If one that it checks isn’t on the list when Desktop connects or reconnects a session, the connection fails. When a user starts a session or sends a message, the error’s details give that jump host’s `HostName`, which is the name to add: ```python SSH host "bastion.example.com" is not allowed by your organization's managed settings. It is a jump host on the way to "devbox". ``` If the message says `managed settings on this computer`, add the name to the list on the user’s computer. If more than one jump host is missing, the error names one at a time. To find every name before users update, use a terminal on a user’s computer: 1 Find the route Run `ssh -G` with a host that users connect to, such as `ssh -G devbox`. Look for a `proxyjump` line, or a `proxycommand` line written as `ssh -W %h:%p `. The command still counts with any of `-l`, `-p`, `-J`, `-q`, `-v`, `-N`, `-T`, `-x`, or `-a`, and the hosts after `-J` are jump hosts too. If a `proxycommand` line runs a program other than `ssh`, add nothing for it. 2 Look up each jump host Run `ssh -G` with each jump host on that line, without any `:port`, and note the `hostname` that it prints. If the output for the first jump host on that line has a line of either kind, repeat this step with it. Ignore such a line in a later jump host’s output. 3 Add the names Add each hostname, or a wildcard that covers it, to `sshHostAllowlist` in every managed source where you set a list. Then have users quit and reopen Desktop, because it fetches server-managed settings at launch. [​](#turn-off-local-sessions-and-distribute-ssh-connections) Turn off local sessions and distribute SSH connections To turn off local sessions and limit SSH sessions to hosts that you choose, deploy [`disableDesktopLocalSessions`](../02-Claude-Code-CLI/settings-reference.md#disabledesktoplocalsessions), [`sshConfigs`](#pre-configure-ssh-connections-for-your-team), and [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to) together. This setup is for users who sign in with a Claude account. With a [third-party provider](../02-Claude-Code-CLI/third-party-integrations.md), SSH sessions are off by default, and setting `sshHostAllowlist` can turn them on. Read [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions) before you deploy these keys. The following example turns off local sessions, adds one connection, and limits SSH sessions to that connection’s host: managed-settings.json ```python { "disableDesktopLocalSessions": true, "sshConfigs": [ { "id": "shared-dev-vm", "name": "Shared Dev VM", "sshHost": "dev.example.com" } ], "sshHostAllowlist": ["dev.example.com"] } ``` The keys apply to the desktop app. They leave other ways to run Claude Code as they are, such as the CLI, Cowork, and cloud sessions: - **The CLI**: none of the keys stops a developer from running the Claude Code CLI on their own computer - **Cowork**: none of the keys applies to [Cowork](https://claude.com/docs/cowork/overview) sessions or Cowork scheduled tasks - **Cloud sessions**: none of the keys changes whether [cloud sessions](#cloud-sessions) are available. To turn them off, use the **Cloud sessions** setting under [Admin console controls](#admin-console-controls). When you adapt the example, check the hostnames, the Desktop version, and the file’s permissions: - **Hostnames**: make sure that a pattern in `sshHostAllowlist` matches the hostname of each `sshConfigs` entry, without `user@`, or developers can’t connect to it. Also add a pattern that matches each [jump host](#allow-jump-hosts) that Desktop checks on the way to it. For how Desktop matches a hostname, see [Restrict which SSH hosts users can connect to](#restrict-which-ssh-hosts-users-can-connect-to). - **Version**: `disableDesktopLocalSessions` requires Claude Desktop v1.37937.0 or later - **File permissions**: make sure that each developer’s account on the computer can read the managed settings file. Desktop doesn’t apply the keys in a file that the account can’t read, and Claude Code [starts without them](../13-Enterprise-Admin/managed-settings.md#find-entries-claude-code-dropped) too. Put the three keys in one [managed source](../13-Enterprise-Admin/managed-settings.md#how-claude-code-combines-managed-sources), the highest-ranked one that you deliver. If you deliver [server-managed settings](../13-Enterprise-Admin/server-managed-settings.md), also keep a copy of the three keys in the highest-ranked MDM policy or managed settings file on each computer. Desktop fetches server-managed settings at launch, and the copy on the computer applies until a fetch succeeds. To confirm that the settings apply, check a developer’s computer: 1 Check the environment selector Quit and reopen Desktop, then open the [environment selector](#start-a-session). The settings applied if it shows: - The entry for that computer, in gray - **Shared Dev VM** under **SSH**. If it isn’t listed there, click the single **SSH** row, or **More** at the end of the group. If the entry for the computer is still available, check for these causes: - **Desktop version**: update Desktop if it’s earlier than v1.37937.0. - **Managed settings file**: make sure that the file is valid JSON. - **Managed source**: make sure that the computer reads the [managed source](../13-Enterprise-Admin/managed-settings.md#how-claude-code-combines-managed-sources) that holds the keys. 2 Add a host that isn't on the allowlist [Add an SSH connection](#ssh-sessions) with a hostname that isn’t on the allowlist, such as `other.example.com`. Desktop saves the connection but refuses to connect, and says that your organization’s settings don’t allow the connection. [​](#enterprise-configuration) Enterprise configuration Organizations on Team or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies. [​](#admin-console-controls) Admin console controls These settings are configured through the [admin settings console](https://claude.ai/admin-settings/claude-code): - **Desktop**: control whether users in your organization can access Claude Code in the desktop app - **Cloud sessions**: enable or disable [cloud sessions](../02-Claude-Code-CLI/claude-code-on-the-web.md) for your organization - **Remote Control**: enable or disable [Remote Control](../02-Claude-Code-CLI/remote-control.md) for your organization In Enterprise organizations that have HIPAA enabled, the **Desktop** toggle is off by default and an [Owner](../13-Enterprise-Admin/server-managed-settings.md#access-control) can turn it on. Applying the [HIPAA configuration](../02-Claude-Code-CLI/hipaa-setup.md) turns it off, even if it was on, so an Owner has to turn it on afterward. **Cloud sessions** and **Remote Control** are also off by default, and an Owner can’t turn them on once the organization has the HIPAA configuration applied. The OpenTelemetry form for Cowork under **Monitoring** in the admin console’s [Data and privacy settings](https://claude.ai/admin-settings/data-privacy-controls) applies to Cowork sessions only. In a Cowork session on this machine, the desktop app passes that collector to Claude Code as `OTEL_*` environment variables, so the form takes effect even though Claude Code in that session [never fetches admin-console settings](#managed-settings).To export telemetry from Code tab sessions, set `CLAUDE_CODE_ENABLE_TELEMETRY` and the `OTEL_*` variables in the `env` block of your Claude Code managed settings, as shown in [administrator configuration for monitoring](../13-Enterprise-Admin/monitoring-usage.md#administrator-configuration). Local, cloud, and SSH sessions each read [managed settings from different sources](#managed-settings). For the hosts a cloud session can reach, see [network access](../02-Claude-Code-CLI/cloud-environments.md#network-access). For the `service.name` that Code tab sessions report, see [service information](../13-Enterprise-Admin/monitoring-usage.md#service-information).To find out which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](../13-Enterprise-Admin/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions). [​](#managed-settings) Managed settings Managed settings override project and user settings and apply to Claude Code sessions in Desktop. You can set these keys in your organization’s [managed settings](../13-Enterprise-Admin/managed-settings.md) file or push them remotely through the admin console. | Key | Description | |--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Bypass permissions mode. | | `disableAutoMode` | set to `"disable"` to remove [Auto](../02-Claude-Code-CLI/permission-modes.md#eliminate-prompts-with-auto-mode) mode from the mode selector. Also accepted under `permissions`. | | `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure auto mode](../02-Claude-Code-CLI/auto-mode-config.md). | | `browserExternalPageTools` | set to `"disabled"` to prevent Claude from using tools to read or act on external pages in the [Browser pane](#browse-external-sites). Users can still navigate to external sites themselves, and local dev server previews are unaffected. | | `disableMobileSimulatorTools` | set to `true` to block Claude’s tools for controlling and capturing devices in the [iOS Simulator pane](desktop-ios-simulator.md#turn-off-simulator-access). The pane stays usable for the user’s own taps; only Claude’s access is removed. The value must be the JSON boolean `true`; the string `"true"` is ignored. | | `disableBrowserExternalNavigation` | set to `true` to turn off external browsing in the [Browser pane](#browse-external-sites) entirely. Neither users nor Claude can navigate to external sites, and localhost dev server previews are unaffected. The value must be the JSON boolean `true`; the string `"true"` is ignored. | | `sshConfigs` | pre-configure [SSH connections](#pre-configure-ssh-connections-for-your-team) that appear in the environment selector. Users can’t delete managed connections or edit anything but their own **Worktree folder**. | | `sshHostAllowlist` | restrict [SSH sessions](#restrict-which-ssh-hosts-users-can-connect-to) to hosts whose resolved hostname matches one of these patterns. Read from managed settings only. | | `disableDesktopLocalSessions` | set to `true` to turn off [Code sessions that run on the device](#local-sessions-on-managed-devices), leaving SSH sessions to other hosts and cloud sessions available. The value must be the JSON boolean `true`. Read from managed settings only. Requires Claude Desktop v1.37937.0 or later. | | `disableSshSavedPasswords` | set to `true` to stop Desktop from offering to remember SSH passwords and from using or showing the ones it saved earlier. Turning it on doesn’t delete them. Read from managed settings only. Requires Claude Desktop v1.49585.0 or later. | | `managedMcpServers` | push MCP server configurations to all users. Available in third-party (3P) Desktop deployments only. In each entry, set a transport of `"http"`, `"sse"`, or `"stdio"`, connection details, and optionally a `toolPolicy` map to restrict which of that server’s tools users can invoke. Deliver it through the managed settings file, MDM, or a Claude apps gateway policy’s [`desktop` block](../13-Enterprise-Admin/claude-apps-gateway-config.md#claude-desktop-overlay), since 3P deployments don’t receive admin-console settings. To deliver it through the gateway, you need Claude Code v2.1.232 or later on the gateway server. This is the desktop app’s own key; Claude Code reads a [same-named managed setting](../06-MCP-Tools/General/managed-mcp.md#provide-servers-through-managed-settings) of its own, with a different entry shape. | Which managed settings reach a Desktop session depends on where that session runs. Model restrictions such as [`availableModels`](../02-Claude-Code-CLI/model-config.md#restrict-model-selection) are enforced in Desktop’s Claude Code sessions the same way as in the terminal CLI; see [surface coverage](../02-Claude-Code-CLI/model-config.md#surface-coverage). - **Local sessions on this machine**: a managed settings file deployed to disk applies. Managed settings pushed remotely through the admin console also reach these sessions on Anthropic’s API when the session authenticates with an [eligible login](../13-Enterprise-Admin/server-managed-settings.md#platform-availability), following the same [settings precedence](../02-Claude-Code-CLI/settings.md#settings-precedence) as the terminal CLI. - **[Cloud sessions](#cloud-sessions)**: receive [server-managed settings](../13-Enterprise-Admin/server-managed-settings.md); device-deployed files don’t reach them, because they run on Anthropic-managed VMs. Sessions routed to a [self-hosted environment](../13-Enterprise-Admin/self-hosted-environments.md) also read the managed settings file in the runner image. [How Claude Code combines managed sources](../13-Enterprise-Admin/managed-settings.md#how-claude-code-combines-managed-sources) says when that file applies. - **[SSH sessions](#ssh-sessions)**: the session reads the managed settings file from the remote host. Desktop itself reads `sshConfigs`, `sshHostAllowlist`, `disableSshSavedPasswords`, and `disableDesktopLocalSessions` on the local machine. If you deliver more than one managed source, it reads them from [one by default](../13-Enterprise-Admin/managed-settings.md#how-claude-code-combines-managed-sources). - **[Cowork](https://claude.com/docs/cowork/overview) sessions**: in a Cowork session on this machine, Claude Code never fetches admin-console settings, even when the user signs in with a Team or Enterprise account, and reads policy deployed to the machine unless your Claude Desktop configuration sets `requireCoworkFullVmSandbox`. Remote Cowork sessions receive neither. See [where and when a policy applies](../13-Enterprise-Admin/managed-settings.md#where-and-when-a-policy-applies) for which device files reach Cowork, and [MCP permission rules](../02-Claude-Code-CLI/permissions.md#mcp) for how `Bash` and `WebFetch` rules apply to Cowork’s tools. In local and SSH sessions, the desktop app delivers each user’s connected claude.ai connectors to Claude Code directly. No MCP setting or `managed-mcp.json` reaches those connectors, whichever settings source or file location you use. To block a connector’s tools in these sessions, use your organization’s [connector tool controls](../06-MCP-Tools/General/mcp.md#organization-controls-on-connector-tools). [How connectors reach Claude Code](../06-MCP-Tools/General/mcp.md#how-connectors-reach-claude-code) shows which settings govern connectors in each kind of session. `permissions.disableBypassPermissionsMode` and `disableAutoMode` also work in user and project settings, but placing them in managed settings prevents users from overriding them. For the permission, plugin, and delivery keys only a managed source can set, see [Keys only managed settings can set](../13-Enterprise-Admin/managed-settings.md#managed-only-settings). [​](#device-management-policies) Device management policies IT teams can manage the desktop app through MDM on macOS, group policy on Windows, or a policy file on Linux. Available policies include enabling or disabling the Claude Code feature, controlling auto-updates on macOS and Windows, and setting a custom deployment URL. - **macOS**: configure via `com.anthropic.claudefordesktop` preference domain using tools like Jamf or Kandji - **Windows**: configure via registry at `SOFTWARE\Policies\Claude` - **Linux**: configure via a root-owned file at `/etc/claude-desktop/managed-settings.json`, which holds the policy keys as a JSON object. Desktop refuses the file if anyone but root can write to it or to its folder. It’s a different file from Claude Code’s [managed settings file](../13-Enterprise-Admin/managed-settings.md). [​](#network-access-requirements) Network access requirements Desktop loads its application code and user content from Anthropic CDN hosts. ```python anthropic.com *.anthropic.com claude.ai *.claude.ai claude.com *.claude.com claude.app *.claude.app *.claudeusercontent.com *.claudemcpcontent.com ``` Traffic is HTTPS on port 443 unless you configure a custom port for [OTLP](../13-Enterprise-Admin/monitoring-usage.md), an LLM gateway, or an MCP server. For proxy servers, custom certificate authorities, mTLS, and the domains the standalone CLI needs, see [network configuration](../13-Enterprise-Admin/network-config.md). To reduce the number of firewall wildcards, allow these Anthropic hosts instead. Certain subdomains are dynamically generated and must remain wildcards. ```python anthropic.com api.anthropic.com a-api.anthropic.com a-cdn.anthropic.com s-cdn.anthropic.com assets-proxy.anthropic.com claude.ai a.claude.ai assets.claude.ai downloads.claude.ai *.livepreview.claude.ai claude.com platform.claude.com sso.claude.com *.livepreview.claude.app *.claudeusercontent.com *.claudemcpcontent.com ``` If your organization has [IP allowlisting](../13-Enterprise-Admin/restrict-access-to-claude-with-ip-allowlisting.md) enabled for Claude, route `bridge.claudeusercontent.com` through the same proxy egress as `claude.ai` and `api.anthropic.com`. If you can’t route it that way, add the egress address your proxy uses for that host to your organization’s IP allowlist, but only when that address is dedicated to your organization: a shared proxy egress range also admits the proxy vendor’s other customers. Anthropic checks connections to that host against your organization’s IP allowlist using the address they arrive from. If your proxy sends traffic for it out through an address that isn’t on that allowlist, Claude in Chrome and other features that connect through the bridge stop working while the rest of the app keeps working. An [artifact](../02-Claude-Code-CLI/artifacts.md) that loads a typeface from [Google Fonts](../02-Claude-Code-CLI/artifacts.md#improve-the-visual-design) also requests `fonts.googleapis.com` and `fonts.gstatic.com`. Both hosts are optional. If you block them, artifacts render in fallback typefaces. Block with a fast rejection rather than a silent drop so the font request fails immediately instead of delaying the page’s first render. Artifacts can also load JavaScript libraries, such as React or a charting package, from `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com`, `code.jquery.com`, and `unpkg.com`, and from no other external host. If you block those hosts, the parts of an artifact that depend on a library don’t work, and unlike a blocked font, a blocked library has no fallback. Block with a fast rejection here too, so a blocked library request fails at once rather than hanging until it times out. [​](#authentication-and-sso) Authentication and SSO Team and Enterprise organizations can require SSO for all users. See [authentication](../02-Claude-Code-CLI/authentication.md) for plan-level details and [Setting up SSO](../21-Account-Support/setting-up-single-sign-on-sso.md) for SAML configuration; OIDC setup is covered in the [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide). [​](#data-handling) Data handling Claude Code processes your code locally in local sessions, or in cloud sessions on Anthropic-managed infrastructure, unless your organization routes them to a [self-hosted environment](../13-Enterprise-Admin/self-hosted-environments.md). Cloud sessions, including in a self-hosted environment, send conversations and code context to Anthropic’s API for processing; local and SSH sessions send them to whichever [model provider](#feature-comparison) your deployment configures, Anthropic’s API by default. See [data handling](../13-Enterprise-Admin/data-usage.md) for details on data retention, privacy, and compliance. [​](#deployment) Deployment Desktop can be distributed through enterprise deployment tools: - **macOS**: distribute via MDM such as Jamf or Kandji using the `.dmg` installer - **Windows**: deploy via the MSIX package. See [Deploy Claude Desktop for Windows](deploy-claude-desktop-for-windows.md) for enterprise deployment options including silent installation For the domains to allowlist in your firewall, see [network access requirements](#network-access-requirements) above. For proxy settings, custom certificate authorities, and LLM gateways, see [network configuration](../13-Enterprise-Admin/network-config.md). For the full enterprise configuration reference, see the [enterprise configuration guide](https://support.claude.com/en/articles/12622667-enterprise-configuration). [​](#coming-from-the-cli) Coming from the CLI? If you already use the Claude Code CLI, Desktop runs the same underlying engine with a graphical interface. You can run both simultaneously on the same machine, even on the same project. Each keeps its own session list, and you can bring a CLI session into Desktop. They share configuration and project memory via CLAUDE.md files. To move a CLI session into Desktop, run `/desktop` in the terminal. Claude saves your session and opens it in the desktop app, then exits the CLI. This command is available on macOS and x64 Windows when you are signed in with a Claude subscription. It is not available with API key authentication or on Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry. From your shell, [`claude --desktop`](../02-Claude-Code-CLI/cli-reference.md#cli-flags) opens Desktop directly without starting a terminal session. It requires Claude Code v2.1.285 or later and has the same platform and sign-in requirements as `/desktop`. With no other arguments, it opens Desktop on the current directory. To open an existing CLI session in Desktop, add `--continue` for the most recent conversation in this directory, or `--resume` with the session ID that `/status` shows: ```python claude --desktop --resume ``` Claude Code prints `Opening session in Claude Desktop`, the session opens in the app, and the command exits. A session name doesn’t work in place of the ID. Claude Code doesn’t move a session that is open in another terminal or still running in the background. If Claude Desktop isn’t installed, the command prints a download link and exits. You can also pick up a CLI session from inside Desktop with `/resume`. The command is available in local sessions, not in SSH, WSL, or cloud sessions. To continue a terminal session in Desktop: 1. Close the session in the terminal. 2. In the Desktop prompt box, type `/resume`. Desktop lists the sessions you started from the CLI on this computer. Search by title, folder, or branch, and preview where each one left off. 3. Select the session. It continues in the app with its full conversation and context. Desktop continues the same session rather than a copy, so `claude --resume` in the terminal still finds it afterwards. When to use Desktop vs CLI: use Desktop when you want to manage parallel sessions in one window, arrange panes side by side, or review changes visually. Use the CLI when you need scripting, automation, or prefer a terminal workflow. [​](#cli-flag-equivalents) CLI flag equivalents This table shows the desktop app equivalent for common CLI flags. Flags not listed have no desktop equivalent because they are designed for scripting or automation. | CLI | Desktop equivalent | |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--model sonnet` | Model picker in the row under the prompt box | | `--resume`, `--continue` | Click a session in the sidebar, or type `/resume` in the prompt box to pick up a session you started from the CLI | | `--permission-mode` | Mode selector in the row under the prompt box | | `--dangerously-skip-permissions` | Bypass permissions mode. On Pro and Max plans, enable it in Settings → Claude Code → “Allow bypass permissions mode”; on Team and Enterprise plans, organization policy controls it | | `--add-dir` | [Add folders to a session](#add-folders-to-a-session) in local and SSH sessions, or select [several repositories](#run-long-running-tasks-in-the-cloud) in a cloud session | | `--allowedTools`, `--disallowedTools` | No per-session equivalent. Permission rules in [settings files](../02-Claude-Code-CLI/settings.md) still apply. | | `--verbose` | [Verbose view mode](#switch-view-modes) | | `--print`, `--output-format` | Not available. Desktop is interactive only. | | `ANTHROPIC_MODEL` env var | Model picker in the row under the prompt box | | `MAX_THINKING_TOKENS` env var | See [Turn off extended thinking](#turn-off-extended-thinking) | [​](#shared-configuration) Shared configuration Desktop and CLI read the same configuration files, so your setup carries over: - **[CLAUDE.md](../02-Claude-Code-CLI/memory.md)** and `CLAUDE.local.md` files in your project are used by both - **[MCP servers](../06-MCP-Tools/General/mcp.md)** configured in `~/.claude.json` or `.mcp.json` work in both - **[Hooks](../07-Hooks/hooks.md)** and **[skills](../08-Plugins-Skills/skills.md)** defined in settings apply to both - **[Settings](../02-Claude-Code-CLI/settings.md)** in `~/.claude.json` and `~/.claude/settings.json` are shared. Permission rules, allowed tools, and other settings in `settings.json` apply to Desktop sessions. - **Models**: the same [models](../02-Claude-Code-CLI/model-config.md#available-models) are available in both. In Desktop, select the model from the model picker in the row under the prompt box. You can change the model mid-session from the same picker. [​](#mcp-servers-from-the-claude-desktop-chat-app) MCP servers from the Claude Desktop chat app The Desktop app loads MCP servers from `claude_desktop_config.json` into local Code tab sessions, alongside servers from `~/.claude.json` and `.mcp.json`. A server you define in `claude_desktop_config.json` is available in both the Desktop chat surface and local Code tab sessions. If you define the same server name in `claude_desktop_config.json` and in `~/.claude.json` or `.mcp.json`, the Code tab in local sessions connects once and uses the `claude_desktop_config.json` definition. The app also re-delivers stdio servers from `~/.claude.json` to the embedded CLI in local sessions. When the top level of `~/.claude.json` (user scope) and `.mcp.json` define the same stdio server name, the Code tab uses the `~/.claude.json` definition, departing from the CLI [scope hierarchy](../06-MCP-Tools/General/mcp.md#scope-hierarchy-and-precedence). The standalone CLI does not read `claude_desktop_config.json`. On macOS and WSL, run `claude mcp add-from-claude-desktop` to copy those servers into `~/.claude.json`. See [Import MCP servers from Claude Desktop](../06-MCP-Tools/General/mcp.md#import-mcp-servers-from-claude-desktop) for the import flow and scope options. [​](#feature-comparison) Feature comparison This table compares core capabilities between the CLI and Desktop. For a full list of CLI flags, see the [CLI reference](../02-Claude-Code-CLI/cli-reference.md). | Feature | CLI | Desktop | |------------------------------------------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Permission modes | All modes including `dontAsk` | Manual, Accept edits, Plan, and Auto. Bypass permissions appears in the mode selector once enabled: through the Settings toggle on Pro and Max plans, or through organization policy on Team and Enterprise plans | | [Third-party providers](../02-Claude-Code-CLI/third-party-integrations.md) | Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry | Anthropic’s API by default. For gateway routing, see [connect the desktop app to a gateway](../13-Enterprise-Admin/llm-gateway-connect.md#desktop-app). To run the Code tab on Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway, see [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview). | | [MCP servers](../06-MCP-Tools/General/mcp.md) | Configure in settings files | Connectors UI for local and SSH sessions, or settings files | | [Plugins](../08-Plugins-Skills/plugins.md) | `/plugin` command | Plugin manager UI | | @mention files | Text-based | With autocomplete, except for a cloud session’s first message | | File attachments | Not available | Images, PDFs | | Session isolation | [`--worktree`](../02-Claude-Code-CLI/cli-reference.md) flag | [Run a session in its own worktree](#run-a-session-in-its-own-worktree) | | Multiple sessions | Separate terminals | Sidebar tabs | | Recurring tasks | Cron jobs, CI pipelines | [Scheduled tasks](desktop-scheduled-tasks.md) | | Computer use | [Enable via `/mcp`](../02-Claude-Code-CLI/computer-use.md) on macOS | [App and screen control](#let-claude-use-your-computer) on macOS and Windows | | iOS simulator | Drive the simulator via [computer use](../02-Claude-Code-CLI/computer-use.md#test-a-simulator-flow) | [iOS Simulator pane](desktop-ios-simulator.md) opens automatically | | Dispatch integration | Not available | [Dispatch sessions](#sessions-from-dispatch) in the sidebar | | Scripting and automation | [`--print`](../02-Claude-Code-CLI/cli-reference.md), [Agent SDK](../02-Claude-Code-CLI/headless.md) | Not available | [​](#what’s-not-available-in-desktop) What’s not available in Desktop The following features aren’t available in Desktop, except where noted: - **Third-party providers**: Desktop connects to Anthropic’s API by default. To route Desktop through a gateway, or to run the Code tab on Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway, follow the links in the [Third-party providers row](#feature-comparison). - **Linux (beta)**: Computer Use isn’t yet available in the Linux desktop app. See [Claude Desktop on Linux](desktop-linux.md). - **Inline code suggestions**: Desktop doesn’t offer autocomplete-style code completions. It works through conversational prompts and explicit code changes, and can [suggest your next prompt](#accept-a-suggested-prompt) after Claude replies. - **Agent teams**: coordinated teams, where Claude as the team lead assigns tasks to teammates from a shared task list, are available in the [CLI](../09-Agents-Patterns/agent-teams.md), not in Desktop. For multi-agent work inside one session, use [dynamic workflows](../02-Claude-Code-CLI/workflows.md), which run in Desktop; Claude can also [message and manage your other sessions](#work-across-sessions) directly. - **Terminal-dialog commands**: built-in commands that open an interactive panel in the terminal behave differently in the Code tab. Edit [settings files](../02-Claude-Code-CLI/settings.md) directly to manage permission rules and configuration, or run the commands from the standalone CLI. - Commands with no argument form, such as `/permissions`, reply with `isn't available in this environment`. - `/config` opens **Settings \> Claude Code**. [​](#troubleshooting) Troubleshooting The sections below cover issues specific to the desktop app. For runtime API errors that appear in the chat such as `API Error: 500`, `529 Overloaded`, `429`, or `Prompt is too long`, see the [Error reference](../02-Claude-Code-CLI/errors.md). [​](#check-your-version) Check your version To see which version of the desktop app you’re running: - **macOS**: click **Claude** in the menu bar, then **About Claude** - **Windows**: click **Help**, then **About Claude** Click the version number to copy it to your clipboard. [​](#claude-code-version-in-the-code-tab) Claude Code version in the Code tab To see which version of Claude Code a session runs, type `/status` in a local session in the **Code** tab and read the **Claude Code** row, which shows a version such as `2.1.286`. To get a newer version for local sessions, open **Claude \> Check for Updates…** on macOS or **Help \> Check for Updates…** on Windows, then start a new session. In a local session, the **Code** tab runs its own copy of Claude Code, which has its own version number. The desktop app downloads and updates that copy, so it can differ from the `claude` command in your terminal, and updating one doesn’t update the other. [​](#check-which-layout-you-have) Check which layout you have If a new session has no [environment selector](#start-a-session) under the prompt box, you have the earlier layout: - **[Desktop older than v2.37337.0](#check-your-version)**: update to get the current layout. Select **Claude \> Check for Updates…** on macOS or **Help \> Check for Updates…** on Windows. - **[Third-party provider](../02-Claude-Code-CLI/third-party-integrations.md) with sessions on your computer**: the current layout requires Claude Desktop v3.1623.0 or later, so [check your version](#check-your-version). To update, select **Claude \> Check for Updates…** on macOS or **Help \> Check for Updates…** on Windows. If your organization [turns off auto-updates](#device-management-policies), **Check for Updates…** is hidden, so ask your administrator for v3.1623.0 or later. - **Third-party provider with sessions on your organization’s infrastructure**: when your organization runs sessions on its own infrastructure rather than on your computer, Desktop keeps the earlier layout, and updating doesn’t change the layout. If you don’t know where your sessions run, ask your administrator. In the earlier layout, choose the environment and project folder above the prompt box, and the permission mode and model in the row under it. The earlier layout lacks the [session details panel](#see-session-details) and [saved local and SSH environments](#create-a-saved-environment). [​](#403-or-authentication-errors-in-the-code-tab) 403 or authentication errors in the Code tab If you see `Error 403: Forbidden` or other authentication failures when using the Code tab: 1. Sign out and back in from the app menu. This is the most common fix. 2. Verify you have an active paid subscription: Pro, Max, Team, or Enterprise. 3. If the CLI works but Desktop does not, quit the desktop app completely, not just close the window, then reopen and sign in again. 4. Check your internet connection and proxy settings. [​](#blank-or-stuck-screen-on-launch) Blank or stuck screen on launch If the app opens but shows a blank or unresponsive screen: 1. Restart the app. 2. Check for pending updates. On macOS and Windows the app auto-updates on launch; on Linux, update through apt as described in [Claude Desktop on Linux](desktop-linux.md). 3. On a managed network, confirm your firewall allows the CDN hosts in [network access requirements](#network-access-requirements). 4. On Windows, check Event Viewer for crash logs under **Windows Logs → Application**. [​](#”failed-to-load-session”) ”Failed to load session” If you see `Failed to load session`, the selected folder may no longer exist, a Git repository may require Git LFS that isn’t installed, or file permissions may prevent access. Try selecting a different folder or restarting the app. [​](#session-not-finding-installed-tools) Session not finding installed tools If Claude can’t find tools like `npm`, `node`, or other CLI commands, verify the tools work in your regular terminal, check that your shell profile properly sets up PATH, and restart the desktop app to reload environment variables. [​](#git-and-git-lfs-errors) Git and Git LFS errors Sessions that run in their own worktree need Git. If you see “Git is required,” install [Git](https://git-scm.com/downloads), or [Git for Windows](https://git-scm.com/downloads/win) on Windows, and try again. On Windows, Claude Desktop versions before 1.49585.0 asked for Git before starting any local session; if you see that prompt and aren’t using worktrees, update the app. If you see “Git LFS is required by this repository but is not installed,” install Git LFS from [git-lfs.com](https://git-lfs.com/), run `git lfs install`, and restart the app. [​](#mcp-servers-not-working-on-windows) MCP servers not working on Windows If MCP server toggles don’t respond or servers fail to connect on Windows, check that the server is properly configured in your settings, restart the app, verify the server process is running in Task Manager, and review server logs for connection errors. [​](#ssh-connection-fails-after-you-log-in) SSH connection fails after you log in Find the card’s title, or the code that ends the error message, in this table, then do what the last column says. To see the message, select **View details** on the failure card. | Title on the card | Code | What to do | |-----------------------------------------------------|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | `'s SSH server has SFTP turned off` | `[SFTP_UNAVAILABLE]` | Turn on SFTP in the server’s `sshd_config`, as described under [remote machine requirements](#remote-machine-requirements-for-ssh-sessions) | | `SFTP doesn't start on ` | `[SFTP_NOT_STARTED]` | Connect to the same host with `sftp` in a terminal on your computer to see what stops it, then check the settings and files that Desktop’s message names | | ` allows too few SSH sessions per connection` | `[SESSION_LIMIT]` | Raise `MaxSessions` in the server’s `sshd_config`, for example to OpenSSH’s default of 10 | | ` is out of disk space` | `[ENOSPC]` or `[EDQUOT]` | Free space or quota on the remote machine, in your home directory or `/tmp` | | `Free up disk space on this computer` | `[ENOSPC]` or `[EDQUOT]`, in a message that starts with `Couldn't prepare the deploy locally` | Free space on your computer | | `Claude Code won't start on ` | `[CLI_UNRESPONSIVE]` | Wait a minute, then try again. If it keeps failing, run the command that the message names on the remote machine to see whether Claude Code answers there. | For any other message, check the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions). [​](#get-desktop’s-logs-for-an-ssh-problem) Get Desktop’s logs for an SSH problem You get `ssh.log`, Desktop’s record of its SSH connections, in a zip file of Desktop’s logs that you save from the **Help** menu. To save it, open **Help \> Troubleshooting** and select the item for your system: - **macOS**: **Show Logs in Finder** - **Windows**: **Show Logs in File Explorer** - **Linux**: **Show Logs in File Manager** Look through the files before you send them, because they can include names and other details from your environment. `` and `` stand for names that Desktop replaced. Desktop doesn’t replace every name, and an SSH host or user name can still appear as written. If you send the zip file to someone, tell them which host failed and when, because the logs may not name it. The zip file doesn’t hold the log of the helper program that Desktop installs on the remote machine. To get that log as well, copy `remote-server.log` from the helper’s folder under [`~/.claude/remote/run/`](#files-and-processes-on-the-remote-machine) in the home directory of the user who connected. Look through that file too before you send it. [​](#app-won’t-quit) App won’t quit - **macOS**: press Cmd+Q. If the app doesn’t respond, use Force Quit with Cmd+Option+Esc, select Claude, and click Force Quit. - **Windows**: use Task Manager with Ctrl+Shift+Esc to end the Claude process. [​](#windows-specific-issues) Windows-specific issues - **PATH not updated after install**: open a new terminal window. PATH updates only apply to new terminal sessions. - **Concurrent installation error**: if you see an error about another installation in progress but there isn’t one, try running the installer as Administrator. [​](#”branch-doesn’t-exist-yet”-when-opening-in-cli) ”Branch doesn’t exist yet” when opening in CLI Cloud sessions can create branches that don’t exist on your local machine. Click the branch name in the session and select **Copy branch name**, then fetch it locally: ```python git fetch origin git checkout ``` [​](#still-stuck) Still stuck? - Open Help → Get Support in the desktop app, or visit the [Claude support center](https://support.claude.com/) directly - For problems that also reproduce in the standalone `claude` CLI, search or file a bug on [GitHub Issues](https://github.com/anthropics/claude-code/issues) When reporting a problem, include your desktop app version, your operating system, the exact error message, and relevant logs. On macOS, check Console.app. On Windows, check Event Viewer → Windows Logs → Application. Review log excerpts before posting them to a public issue; they can include file paths and other details from your environment. --- ## Enabling and using the desktop extension allowlist | Claude Help Center Source: https://support.claude.com/en/articles/12592343-enabling-and-using-the-desktop-extension-allowlist Path: 16-Mobile-Desktop/enabling-and-using-the-desktop-extension-allowlist.md # Enabling and using the desktop extension allowlist March 16, 2026 The desktop extension allowlist is available for Owners and Primary Owners of Team and Enterprise plans. This article introduces a desktop extension allowlist that Team and Enterprise plan Owners can use to manage their organization’s access to extensions. ## How to enable the allowlist **Important:** If you’ve previously configured Enterprise policy controls at the user-machine level, these will override the in-app allowlist. Ensure both `isDesktopExtensionDirectoryEnabled` and `isDesktopExtensionEnabled` are not set to "false" so the allowlist can populate the available registry. Refer to our **[desktop enterprise configuration documentation](https://support.claude.com/en/articles/12622667-enterprise-configuration)** for more information. The desktop extension allowlist is disabled by default, so an organization Owner will need to switch it on manually. Note that **users will be able to access all desktop extensions in the registry until you enable the allowlist.** To prevent this, ensure you activate the allowlist to block all desktop extensions by default, then add only the extensions your team needs access to. **To turn on the allowlist:** 1. Open Claude Desktop 2. Click your initials or name in the lower left corner 3. Navigate to Organization settings \> Connectors 4. Switch to the "Desktop" tab: 5. Toggle **Allowlist** on: ## What happens after enabling the allowlist? Once the allowlist is enabled: - Any existing desktop extension installations will be force-deleted from Claude Desktop clients. - Users will no longer be able to install new desktop extensions that are not included within the allowlist. - Users can only download extensions from the sanctioned in-app registry; they can no longer drag or click to install MCPBs. Note that the allowlist does not guard against individuals tampering with local MCP file contents after installation. Consider completing the allowlist setup during off-hours to minimize disruption to existing users. If a user's installed extension is deleted while the allowlist is being configured, they will need to manually re-install the extension. **Important:** The allowlist requires Claude Desktop version 0.13.91 or higher, so users should update the desktop app by clicking “Claude”, then either “Check for updates” or “Restart to update to Claude 0.13.91”: ## Managing allowed extensions After enabling the allowlist, you can choose which extensions to allow: 1. Navigate to Organization settings \> Connectors and select the “Desktop” tab. 2. Click “Browse extensions” to view the list of available extensions. 3. Select the extension you want to add. 4. Click the “Add to your team” button. 5. The extension will appear in your allowlist. If you want to remove an extension from the allowlist, click the “...” button and “Remove from allowlist.” ## Uploading custom extensions You can also upload custom extensions to deploy across your organization via Organization settings \> Connectors \> Desktop. **Note:** Ensure the name field in the manifest.json does not overlap with any existing MCPBs. All names for unique MCPBs / desktop extensions must be unique. 1. Click “Add custom extension” 2. This will open a filepicker; select the .mcpb file. 3. The extension will appear under **Custom team extensions**. 4. Click "...” then “Add to team” to add it to your allowlist and enable it for your team. When you allowlist a custom extension, it's scoped to your specific organization and can't be used across other organizations. For more in-depth information about creating custom extensions with MCP Bundles (.mcpb), please refer to our **[desktop extension developer documentation](https://github.com/anthropics/mcpb)**. ## Updating custom extensions We’ve also introduced the ability to update previously-installed custom extensions to new versions without having to remove and reinstall them. You can update a new MCPB version by making changes to manifest.json, ensuring the version field for the update candidate is incremented from the current uploaded version, and that you leave the name value unchanged. Changing the name will create a new custom desktop extension rather than uploading a new version. Then navigate to the custom upload pane, select "Upload new version" via the kebab menu, and upload the new file. --- ## Getting Started with Local MCP Servers on Claude Desktop | Claude Help Center Source: https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop Path: 16-Mobile-Desktop/getting-started-with-local-mcp-servers-on-claude-desktop.md # Getting Started with Local MCP Servers on Claude Desktop The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. With the introduction of desktop extensions, installing and managing local MCP servers has become significantly easier. ## Desktop Extensions Desktop extensions provide a streamlined way to install and manage local MCP servers through single-click installable packages. Instead of manually configuring JSON files and managing dependencies, you can now install local MCP servers on your computer as easily as browser extensions. **Note:** If you’re a developer who wants to list a desktop extension (a local MCP server for Claude Desktop) in the directory, submit it through the **[desktop extension submission form](https://clau.de/desktop-extention-submission)**. To submit a plugin or a remote connector instead, use the **[developer portal](https://claude.ai/directory/manage)**. See **[Submitting your plugin](https://claude.com/docs/plugins/submit)** for what each route accepts. ## Installing desktop extensions from the directory 1. Navigate to Settings \> Extensions on Claude Desktop. 2. Click “Browse extensions” to view our directory and click on any Anthropic-reviewed tools you want to use. Click "Install" on your desired extension. 3. Configure any required settings (like API keys) through the user-friendly interface. 4. The extension will automatically be available in your conversations. ## Installing custom desktop extensions 1. Navigate to Settings \> Extensions on Claude Desktop. 2. Click “Advanced settings” and find the **Extension Developer** section. 3. Click “Install Extension…” 4. Select the .mcpb file and follow the prompts to install. ## Admin Controls for Desktop Extensions Owners and Primary Owners of Team and Enterprise plans can manage team access to desktop extensions using two controls: 1. Enable or disable public desktop extensions depending on your organization’s security standards. 2. Upload custom desktop extensions and make them available to your team for one-click install. These controls allow organizations to fully customize their registries by adding only the extensions the team needs to access, and removing any others. ### Enabling/disabling specific extensions on Team and Enterprise plans Owners and Primary Owners of Team and Enterprise organizations can manage which desktop extensions are enabled for your organization and accessible to other members via Claude Desktop. See [Enabling and using the desktop extension allowlist](enabling-and-using-the-desktop-extension-allowlist.md) for specific instructions. ### Create and upload custom extensions for your organization Custom desktop extensions uploads allow Team and Enterprise plans to leverage organization-specific workflows that aren’t available in the public directory. After creating a custom desktop extension, Owners and Primary Owners can navigate to Settings \> Extensions within Claude Desktop and click “Advanced settings” to access the **Extension Developer** section: Click “Install Extension…” and select the .mcpb file. Follow the prompts to install and configure your custom desktop extension. For more in-depth information, please refer to our [desktop extension developer documentation](https://github.com/anthropics/mcpb). ## Enterprise Policy Controls **Note:** Enterprise policy controls at the user-machine level will override any in-app controls (blocklist and allowlist). If you want to use an in-app control, ensure `isDesktopExtensionEnabled` and `isDesktopExtensionDirectoryEnabled` are not set to "false" so the allowlist can populate the available registry. For controlling desktop extensions through system policies, please refer to our [desktop enterprise configuration documentation](https://support.claude.com/en/articles/12622667-enterprise-configuration). ## Troubleshooting desktop extension installation issues ### Extension won't install - Ensure you're running the latest version of Claude Desktop. - Check that the extension file isn't corrupted by re-downloading it. - Verify you have sufficient disk space for the installation. ### Extension appears installed but tools aren't available - Restart Claude Desktop to refresh the extension registry. - Check the extension's configuration settings for missing required fields. - Verify any API keys or authentication credentials are entered correctly. ### Extension configuration issues - Navigate to Settings \> Extensions and click on the extension to review its settings. - Ensure all required configuration fields are completed. - Check that file paths (if applicable) point to existing directories you have access to. ### Permission or security errors - On macOS, check System Preferences \> Security & Privacy if you receive security warnings. - On Windows and Linux, ensure Claude Desktop has necessary permissions to access required directories. - For enterprise environments, verify that desktop extensions are enabled through your organization's policies. ## Developer FAQ ### How do I check if my MCP servers are properly connected in Claude Desktop? Click the "+" button on bottom the chat box within Claude Desktop, then select "Connectors." This will show you connected MCP servers and their tools. Alternatively, you can visit Developer settings (under **Desktop app**) to see connection status and look at the logs for any MCP servers. ### How do I convert my existing MCP server to a desktop extension? 1. Add a manifest.json file to your MCP server directory with the required metadata. 2. Package it using the `mcpb pack` command. 3. See the [MCPB documentation](https://github.com/anthropics/mcpb) for detailed instructions. ### What programming languages are supported for desktop extensions? Desktop extensions support Node.js, Python, and binary MCP servers. Claude Desktop includes a built-in Node.js environment, so Node.js installation isn't required. ### How do I handle sensitive configuration like API keys? Mark configuration fields as "sensitive": true in your manifest.json. Claude Desktop will automatically encrypt these values using the operating system's secure storage (Keychain on macOS, Credential Manager on Windows, and your distro’s keychain manager on Linux). ### Can I distribute my custom desktop extension privately? Yes, you can share .mcpb files directly with specific users or teams. For broader distribution, you can submit extensions to the official directory. ### How do I debug issues with my desktop extension? Enable debug logging in Claude Desktop settings, check the extension logs in the Extensions settings panel, and refer to the MCP debugging guide for protocol-specific troubleshooting. ### What happens when my extension needs updates? Extensions from the official directory update automatically by default. For privately distributed extensions, users will need to install updated .mcpb files manually. ## Interested in learning more about MCP? For more in-depth information on building your own MCP clients and servers, we recommend reviewing the following resources: - [MCP Quickstart Guide](../06-MCP-Tools/General/getting-started-intro.md) - A step-by-step tutorial perfect for getting started with basic MCP integration. - [Model Context Protocol Github](https://github.com/modelcontextprotocol) - Contains the complete technical documentation, code examples, and implementation guides. - [Guide to debugging MCP integrations](https://modelcontextprotocol.io/docs/tools/debugging) - Troubleshooting tips and solutions for common implementation challenges. If you need further guidance, visit our guide on [How to Get Support](../15-Claude-AI-Features/how-to-get-support.md) for additional support options. --- ## How can I uninstall Claude for Android? | Claude Help Center Source: https://support.claude.com/en/articles/9612889-how-can-i-uninstall-claude-for-android Path: 16-Mobile-Desktop/how-can-i-uninstall-claude-for-android.md 4. How can I uninstall Claude for Android? # How can I uninstall Claude for Android? To uninstall the Claude app from your Android device, hold down on the app from your screen until you see the menu options. Click on “App Info.” From the next series of options, select “Uninstall.” Note that if you have an active Claude Pro subscription and would like to uninstall the app, your subscription will not be automatically canceled. To cancel your subscription, follow the cancellation instructions [here](https://support.anthropic.com/en/articles/9612898-how-can-i-cancel-my-claude-pro-subscription-on-claude-for-android). --- ## Install Claude for Android | Claude Help Center Source: https://support.claude.com/en/articles/9612887-how-do-i-install-claude-for-android Path: 16-Mobile-Desktop/how-do-i-install-claude-for-android.md # Install Claude for Android July 9, 2026 ## Install the Claude for Android app You can install the Claude app onto your device by navigating to the Play Store and searching for "Claude by Anthropic," or by navigating directly to our **[Play Store listing](https://play.google.com/store/apps/details?id=com.anthropic.claude)**. Click on “Install” from the app listing to prompt your download. ## Why can’t I find Claude for Android in the Play Store? If you’re unable to locate Claude for Android in your Play Store, you may be located in an **[unsupported region](https://support.claude.com/en/articles/8461763)**, using an unsupported device, or using an unsupported version of Android. ## What versions of Android are supported? We currently support Android 8.0 Oreo and above. ## Uninstall the Claude for Android app To uninstall the Claude app from your Android device, hold down on the app from your screen until you see the menu options. Click on "App Info." From the next series of options, select "Uninstall." Note that if you have an active paid subscription and would like to uninstall the app, your subscription will not be automatically canceled. To cancel your subscription, follow the instructions here: **[Cancel your Pro or Max subscription on Claude for Android](https://support.claude.com/en/articles/8325617-cancel-your-pro-or-max-subscription#h_916bc20742)**. --- ## How to update Claude for Android | Claude Help Center Source: https://support.claude.com/en/articles/11825394-how-to-update-claude-for-android Path: 16-Mobile-Desktop/how-to-update-claude-for-android.md # How to update Claude for Android March 16, 2026 If you aren’t seeing the latest features on Claude for Android, you may need to [update your mobile app manually by following these instructions from Google](https://support.google.com/googleplay/answer/113412?hl=en): 1. Open the Google Play Store app . 2. At the top right, tap the profile icon. 3. Tap “Manage apps & device.” 4. Under **Updates available**, tap “See details.” 5. Tap “Update” next to Claude for Android. --- ## How to update Claude for iOS | Claude Help Center Source: https://support.claude.com/en/articles/11825384-how-to-update-claude-for-ios Path: 16-Mobile-Desktop/how-to-update-claude-for-ios.md # How to update Claude for iOS If you aren’t seeing the latest features on Claude for iOS, you may need to update your mobile app manually by following these **[instructions from Apple](https://support.apple.com/en-us/102629)**: 1. Open the App Store. 2. Tap the "My Account" button or your photo at the top of the screen. 3. Scroll down to see pending updates. 4. Tap "Update" next to Claude for iOS to update it to the newest version. **Note:** If you use Claude for Intune, the managed version of Claude for iOS for Enterprise plans, your IT team controls when it updates if your organization installed it through Intune. See **[Set up Claude for Intune](https://support.claude.com/en/articles/17203415)** for details. --- ## Install Claude for iOS | Claude Help Center Source: https://support.claude.com/en/articles/9266462-install-claude-for-ios Path: 16-Mobile-Desktop/install-claude-for-ios.md # Install Claude for iOS ## How do I install the Claude for iOS app? You can install the Claude app onto your iOS device by navigating to the App Store and searching for “Claude by Anthropic”, or by navigating directly to our **[App Store listing](https://apps.apple.com/us/app/claude/id6473753684)**. Click on “Get” from the app listing to prompt your download. ## Which Claude app should I install? Anthropic has two Claude apps on the App Store: - **[Claude by Anthropic](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684)** is the standard Claude app. - **[Claude for Intune](https://apps.apple.com/us/app/claude-intune/id6812855318)** is a managed version of Claude for iOS for Enterprise plans that use Microsoft Intune. If your organization hasn't asked you to use Claude for Intune, install Claude by Anthropic. **Note:** If your organization uses Microsoft Intune, it may require you to use Claude for Intune instead of the standard Claude app. Check with your IT team before you install. Admins can learn more in **[Set up Claude for Intune](https://support.claude.com/en/articles/17203415)**. ## Why can’t I find Claude for iOS in the App Store? If you’re unable to locate Claude for iOS or Claude for Intune in your App Store, you may be located in an **[unsupported region](../15-Claude-AI-Features/where-can-i-access-claude.md)**, using an unsupported device, or using an unsupported version of iOS. If your organization requires Claude for Intune and you can't find it, contact your IT administrator. ## What versions of iOS are supported? We currently support iOS version 18.0 and above, and iPadOS 18.0 and above. This applies to both the standard Claude app and Claude for Intune. ## How do I uninstall the Claude for iOS app? To uninstall the Claude for iOS from your device, hold down on the app from your home screen until you see the menu options. Click on “Remove App.” From the next series of options, select “Delete App.” Note that if you have an active paid Claude subscription and would like to uninstall the app, your subscription will not be automatically canceled. To cancel your subscription follow the instructions here: **[Cancel your Pro or Max subscription](https://support.claude.com/en/articles/8325617)**. --- ## Install Claude Desktop | Claude Help Center Source: https://support.claude.com/en/articles/10065433-installing-claude-desktop Path: 16-Mobile-Desktop/installing-claude-desktop.md # Install Claude Desktop The Claude desktop apps bring Claude's capabilities directly to your computer, allowing for seamless integration with your workflow. ## Availability Claude Desktop is available on macOS, Windows, and Linux (beta). What you can do depends on your plan: [TABLE] ## System Requirements - macOS: macOS 13 (Ventura) or higher - Windows: Windows 10 or higher - Linux: Ubuntu 22.04 LTS+ or Debian 12 (bookworm)+, on x64 or arm64 ## Installation steps for mac OS and Windows 1. Visit the **[Claude downloads page](https://claude.ai/download)**. 2. Select the appropriate version for your operating system: - For Mac users, find **macOS** and click "Download." - For Windows users, find **Windows** and click "Download." Once the download is completed: 1. Open the file to complete installation. 2. Launch Claude from your Applications folder (Mac) or Start menu (Windows). 3. Sign in with your account to get started. ## Installation steps for Linux ### Install using apt On Linux, you can install Claude Desktop from Anthropic’s apt repository rather than as a downloaded .deb file so that updates arrive through your system's normal package updates rather than in-app. 1\. On Ubuntu or Debian, open a terminal and run: ​ sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc https://downloads.claude.ai/claude-desktop/key.asc echo "deb [signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] https://downloads.claude.ai/claude-desktop/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list sudo apt update && sudo apt install claude-desktop 2. Launch Claude from your applications menu, or run `claude-desktop` from a terminal, and sign in. **Keeping Claude Desktop up to date on Linux** The app doesn't update itself. Updates arrive with your system's regular package updates (`sudo apt update && sudo apt upgrade`). ### Install using file download **Note:** Downloading the .deb will not opt you into regular package updates. We highly recommend that you install using apt, or set up the apt repo using the steps above. If you can’t install Claude Desktop using apt, you can install it by downloading a .deb file instead: 1. Visit the **[Claude downloads page](https://claude.ai/download)**. 2. Find the .deb for your architecture (x64 or arm64) and click "Download." 3. From the folder you downloaded the .deb file, run: `sudo apt install ~/Downloads/claude-desktop_amd64.deb` 4. Launch Claude from your applications menu (or run `claude-desktop`), then sign in. ### Verify the download on Linux (optional) Verify the signing key fingerprint before trusting it: 1. Run: `gpg --show-keys /usr/share/keyrings/claude-desktop-archive-keyring.asc` 2. Confirm the output matches: `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE` ### Current limitations when you use Claude Desktop on Linux - Computer use isn't available. - Dictation isn't available. - Quick Entry, the global hotkey, works on X11. On native Wayland, it relies on your desktop's GlobalShortcuts portal. ------------------------------------------------------------------------ ## Desktop extensions Desktop extensions transform how you connect Claude to your desktop applications and data. Similar to browser extensions, these secure, installable packages let you: - **Connect Claude to your desktop apps with one click**: Install extensions that integrate with your local files, calendars, emails, and messaging apps. - **Access a curated directory of extensions**: Browse verified extensions directly within Claude Desktop, including options like filesystem access and iMessage. - **Enjoy enterprise-ready security**: Extensions use code signing, encrypted storage for sensitive data like API keys, and enterprise policy controls. To explore desktop extensions, navigate to Settings \> Extensions within the Claude Desktop app after installation. **Note:** If you’re a developer who wants to list a desktop extension (a local MCP server for Claude Desktop) in the directory, submit it through the **[desktop extension submission form](https://clau.de/desktop-extention-submission)**. To submit a plugin or a remote connector instead, use the **[developer portal](https://claude.ai/directory/manage)**. See **[Submitting your plugin](https://claude.com/docs/plugins/submit)** for what each route accepts. Read more about desktop extensions in our **[Getting Started with Local MCP Servers on Claude Desktop](getting-started-with-local-mcp-servers-on-claude-desktop.md)** article. ------------------------------------------------------------------------ ## Claude Cowork Claude Cowork is available for all paid plans (Pro, Max, Team, Enterprise) using the Claude Desktop app on macOS, Windows, and Linux (beta). Users on paid Claude plans can access Cowork in Claude Desktop. Cowork brings Claude Code's agentic capabilities to a visual interface, allowing you to hand off complex, multi-step tasks without using a terminal. With Cowork, Claude can: - Access your local files directly without manual uploads. - Work on long-running tasks like research synthesis, file organization, and document generation. - Coordinate parallel workstreams for complex projects. - Deliver professional outputs like spreadsheets with working formulas and formatted presentations. Cowork runs code in an isolated virtual machine on your computer. File reads and writes are limited to folders you connect, and network access follows your egress settings. To learn more, see **[Get started with Cowork](https://support.claude.com/en/articles/13345190-get-started-with-cowork)**. **Setup requirements for Claude Cowork on Linux** Cowork on Linux has its own setup requirements. Cowork runs your tasks in a virtual machine on your computer. Before it can start, your machine needs: - **Hardware virtualization (KVM).** Most computers support this, but it's sometimes turned off in firmware. If Cowork says virtualization isn't available, enable it in your BIOS or UEFI settings and restart. - **Permission to use virtualization.** Add yourself to the KVM group, then log out and back in: `sudo usermod -aG kvm $USER` - **QEMU and supporting packages.** Installing Claude with `apt install` pulls these in automatically. - If you installed the .deb file directly on x64, run `sudo apt install qemu-system-x86 ovmf virtiofsd` - On arm64, run `qemu-system-arm qemu-efi-aarch64 virtiofsd` instead. - **About 25 GB of free disk space for the workspace image, and at least 8 GB of RAM.** The workspace uses 4 GB while it's running. --- ## Claude Code on mobile - Claude Code Docs Source: https://code.claude.com/docs/en/mobile Path: 16-Mobile-Desktop/mobile.md ## On this page - [Get the app](#get-the-app) - [Work from your phone](#work-from-your-phone) - [Start and monitor cloud sessions](#start-and-monitor-cloud-sessions) - [Continue a local session with Remote Control](#continue-a-local-session-with-remote-control) - [Get push notifications](#get-push-notifications) - [Limitations](#limitations) - [Related resources](#related-resources) Platforms and integrations # Claude Code on mobile Copy pageCopy page Start, monitor, and steer Claude Code tasks from your phone with the Claude app for iOS and Android. Copy pageCopy page The Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) and [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) is a client for Claude Code sessions rather than a place where code runs. From your phone you reach [cloud sessions](#start-and-monitor-cloud-sessions) and [projects](../02-Claude-Code-CLI/claude-projects.md) in the cloud, a session running on your own machine through [Remote Control](#continue-a-local-session-with-remote-control), or the Desktop app through [Dispatch](desktop.md#sessions-from-dispatch). Claude Code doesn’t have a separate mobile app: cloud sessions and Remote Control both live in the **Code** tab in the Claude app, and Dispatch is a task you message in the app. [​](#get-the-app) Get the app 1 Download the Claude app Install the Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) or [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude). On an iPad, install the same iOS app. Run `/mobile` in a Claude Code session to show a QR code for [claude.ai/mobile](https://claude.ai/mobile), which opens the right app store for your phone. `/ios` and `/android` do the same thing. 2 Sign in Sign in with the same claude.ai account and organization you use for Claude Code. Cloud sessions and Remote Control require a claude.ai account, so they aren’t reachable with an Anthropic Console API key or from a third-party provider such as Amazon Bedrock. 3 Open the Code tab Tap **Code** in the app’s navigation to reach your sessions, or open [claude.ai/code/new](https://claude.ai/code/new) on your phone to start a new Code session in the app. If you don’t see the Code tab, your plan or organization may not include these features; see [availability by subscription plan](../02-Claude-Code-CLI/feature-availability.md#availability-by-subscription-plan). [​](#work-from-your-phone) Work from your phone From the app you can start cloud sessions, open a project, drive a Claude Code session running on your computer, or message Dispatch a task. The app is the same for each; they differ in where the work happens. | Feature | What you connect to | When to use | |:----------------------------------------------------|:----------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Cloud sessions](../02-Claude-Code-CLI/claude-code-on-the-web.md) | A session on cloud infrastructure, Anthropic-managed by default | Your repository is on GitHub and the task should keep running after you put your phone away. See the [cloud quickstart](../02-Claude-Code-CLI/web-quickstart.md) to set up. | | [Projects](../02-Claude-Code-CLI/claude-projects.md) | A conversation where Claude coordinates parallel threads of work and reports back | You have a stream of related work rather than one task and want to see which threads finished or need you. | | [Remote Control](../02-Claude-Code-CLI/remote-control.md) | A Claude Code session running on your computer | The work needs your local filesystem, tools, or MCP servers. | | [Dispatch](desktop.md#sessions-from-dispatch) | The Desktop app on your computer | You want to message a task and let Dispatch decide how to run it. Requires a Pro or Max plan. | If your computer will be off, use cloud sessions or a project, which run in the cloud and continue with your laptop closed. Remote Control and Dispatch drive your own machine, so it needs to stay on with Claude Code or the Desktop app running. If your machine sleeps during a Remote Control session, Claude Code reconnects when the machine comes back online. For a fuller comparison, see [work when you are away from your terminal](../02-Claude-Code-CLI/platforms.md#work-when-you-are-away-from-your-terminal). Cloud sessions and Remote Control run from the **Code** tab. For Dispatch, which you message as a task in the app, see [sessions from Dispatch](desktop.md#sessions-from-dispatch). [​](#start-and-monitor-cloud-sessions) Start and monitor cloud sessions Cloud sessions run tasks on cloud infrastructure, Anthropic-managed by default, so a session continues after you put your phone away. From the Code tab, select a repository and branch, describe the task, and submit it. Sessions persist across devices: a task you start on your laptop is ready to review from your phone, and one you start from your phone is waiting when you’re back at your desk. Open a session in the app to check progress, answer Claude’s questions, or steer it in a new direction. You can also tell Claude to [watch a pull request](../02-Claude-Code-CLI/claude-code-on-the-web.md#auto-fix-pull-requests) and fix CI failures or review comments as they arrive. To connect GitHub and set up your environment, follow the [cloud quickstart](../02-Claude-Code-CLI/web-quickstart.md), and see [Use Claude Code in the cloud](../02-Claude-Code-CLI/claude-code-on-the-web.md) for everything cloud sessions can do. [​](#continue-a-local-session-with-remote-control) Continue a local session with Remote Control Remote Control connects the Claude app to a Claude Code session running on your machine, so code execution and filesystem access stay local while you drive the session from your phone. Start the session on your computer with `claude remote-control`, or run `/remote-control` in a session that’s already open. Then scan the QR code the terminal can display, or open the Claude app, tap **Code**, and pick the session from the list. See [connect from another device](../02-Claude-Code-CLI/remote-control.md#connect-from-another-device) for each option. When you add an attachment in the Claude app, it reaches the local session too: - **Photos**: Claude sees attached photos directly as part of your message. Claude Code also saves each photo under `~/.claude/uploads/` and tells Claude the saved file path, so Claude can copy the image into files it creates. - **Other files**: Claude Code downloads them to your machine and passes them to Claude as `@` file references. For requirements, invocation modes, and troubleshooting, see the [Remote Control overview](../02-Claude-Code-CLI/remote-control.md). [​](#get-push-notifications) Get push notifications When Remote Control is active, Claude can send push notifications to your phone, typically when a long-running task finishes or when it needs a decision from you. You can also ask for one in your prompt, such as `notify me when the tests finish`. See [mobile push notifications](../02-Claude-Code-CLI/remote-control.md#mobile-push-notifications) for the two `/config` toggles and delivery troubleshooting. Dispatch sends its own notification when a Code session it spawned finishes or needs your approval, described in [sessions from Dispatch](desktop.md#sessions-from-dispatch). [​](#limitations) Limitations The mobile client covers most of what a session needs, with a few limitations: - **Local-only commands**: commands that only run in the terminal interface, such as `/plugin` and `/resume`, don’t work from the app. The [Remote Control limitations](../02-Claude-Code-CLI/remote-control.md#limitations) list the commands that do work from mobile and how their behavior differs. - **Permission modes**: cloud sessions offer Accept edits, Plan, and Auto, and Remote Control sessions offer Manual, Accept edits, Plan, and Auto. You can’t select Bypass permissions from the app in either case. See [switch permission modes](../02-Claude-Code-CLI/permission-modes.md#switch-permission-modes) for when Auto is available. - **Dispatch plans**: Dispatch requires a Pro or Max plan and isn’t available on Team or Enterprise. [​](#related-resources) Related resources - [Platforms and integrations](../02-Claude-Code-CLI/platforms.md): compare every surface Claude Code runs on - [Use Claude Code in the cloud](../02-Claude-Code-CLI/claude-code-on-the-web.md): how cloud sessions run and how to move work to and from your terminal - [Configure cloud environments](../02-Claude-Code-CLI/cloud-environments.md): network access levels, environment variables, and setup scripts for cloud sessions - [Remote Control](../02-Claude-Code-CLI/remote-control.md): continue a local session from any device - [Sessions from Dispatch](desktop.md#sessions-from-dispatch): how Dispatch tasks become Code sessions in the Desktop app - [Channels](../02-Claude-Code-CLI/channels.md): ask Claude something from your phone via Telegram, Discord, or iMessage while the work runs on your machine - [Claude Code in Slack](../14-Connectors/slack.md): delegate coding tasks from your Slack workspace by mentioning `@Claude` --- ## Open Claude Desktop with a link | Claude Help Center Source: https://support.claude.com/en/articles/14729294-open-claude-desktop-with-a-link Path: 16-Mobile-Desktop/open-claude-desktop-with-a-link.md # Open Claude Desktop with a link June 30, 2026 Claude for macOS, Windows, and Linux respond to the `claude://` URL scheme, much like a browser responds to the `https://` scheme. You can use these links from a website, a script, or another app to open Claude Desktop and jump straight to a chat, a Cowork session, or a Code session. This article lists the link formats Claude Desktop supports and the parameters each one accepts. ## How deep links work When your operating system opens a `claude://` URL, it hands the URL to Claude. If the app isn't running, macOS, Windows, and Linux will launch it first. Claude then reads the path and query parameters and navigates to the right place inside the app. All parameter values must be URL-encoded. Prompt text passed in `q` is truncated to roughly 14,000 characters. ------------------------------------------------------------------------ ## Start a new chat claude://claude.ai/new claude://claude.ai/new?q=Summarize%20this%20week%27s%20release%20notes Opens a new chat in Claude Desktop. If you include `q`, the prompt field is prefilled with that text so you can review and send it. [TABLE] ------------------------------------------------------------------------ ## Open an existing chat or project claude://claude.ai/chat/{conversation-id} claude://claude.ai/project/{project-id} Opens a specific chat or project by its ID. The ID is the UUID you see at the end of the chat or project URL in Claude. If the ID is missing or invalid, Claude opens your recent chats or your projects list instead. ------------------------------------------------------------------------ ## Start a Claude Code session claude://code/new claude://code/new?q=Fix%20the%20failing%20test&folder=%2FUsers%2Fme%2Frepo Opens Claude Code in Claude Desktop with the composer prefilled. Use this for "Open in Claude Code" buttons in your own tools. [TABLE] **Note:** Any folder supplied through a link is treated as untrusted. Claude Desktop always shows a confirmation dialog before adopting it as the working directory, even if you've trusted that folder before. ------------------------------------------------------------------------ ## Start a Claude Cowork session claude://cowork/new claude://cowork/new?q=Draft%20the%20Q2%20update&folder=%2FUsers%2Fme%2Fdocs&file=%2FUsers%2Fme %2Fdocs%2Fnotes.md Opens a new Cowork session with the composer prefilled. Use this for "Open in Claude Cowork" buttons in your own tools. [TABLE] **Note:** Any folder supplied through a link is treated as untrusted. Claude Desktop always shows a confirmation dialog before adopting it as the working directory, even if you've trusted that folder before. ------------------------------------------------------------------------ ## Test a deep link ### On macOS Open Terminal and run: open "claude://claude.ai/new?q=Hello" ### On Windows Open Command Prompt and run: start "" "claude://claude.ai/new?q=Hello" ### On Linux Open a terminal and run: xdg-open "claude://claude.ai/new?q=Hello" --- ## Open the Claude mobile app with a link | Claude Help Center Source: https://support.claude.com/en/articles/14898120-open-the-claude-mobile-app-with-a-link Path: 16-Mobile-Desktop/open-the-claude-mobile-app-with-a-link.md # Open the Claude mobile app with a link May 6, 2026 The Claude mobile apps for iOS and Android respond to the `claude://` URL scheme. Third-party apps, shortcuts, and web pages can use these links to open the Code tab, jump to an existing session, or prefill the new-session composer. All parameter values must be URL-encoded. These links require Claude Code access on your account. If you don't have access to Claude Code, the links won't work. ## Open the Code tab `claude://code` Opens the Code tab on the session list. ## Open an existing Code session `claude://code/{session-id}` Opens an existing Claude Code session by ID. If the ID is unknown, you'll land on the session list. ## Open a new Code session `claude://code/new` With optional parameters: `claude://code/new?q=Fix%20the%20failing%20test&repo=anthropics%2Fclaude-code&branch=main` Opens the new-session composer, optionally prefilled. All parameters are optional. [TABLE] The **[desktop-only folder and file parameters](open-claude-desktop-with-a-link.md)** are ignored on mobile. ## Universal links The same Code routes are also reachable via **[https://claude.ai/code/](https://claude.ai/code/)...** universal links. If the app is installed, the operating system opens it; otherwise the link opens in the browser. [TABLE] --- ## Navigating the Claude desktop app · Claude Academy Source: https://www.claude.com/resources/tutorials/navigating-the-claude-desktop-app Path: 16-Mobile-Desktop/resources-tutorials-navigating-the-claude-desktop-app.md # Navigating the Claude desktop app Learn what changes when you use Claude in the desktop app, and what it can do across your computer and tools. 6 minClaude [Open Claude](https://claude.ai/new) The [Claude desktop app(opens in new tab)](https://claude.com/download) puts Claude on your computer. That lets Claude open from any app with a shortcut, work in more of your apps and websites, and directly read, edit, or save files in your folders to carry a task further from start to finish. Working in code? See the [Claude Code desktop docs(opens in new tab)](desktop.md). In this guide 1. [1. Claude is one shortcut awayYou want Claude without switching windows](#1-claude-is-one-shortcut-away) 2. [2. Claude can work in your files, apps, and websitesThe work is in your files, an app on your computer, or a website](#2-claude-can-work-in-your-files-apps-and-websites) 3. [3. Claude can keep going while you're awayA task takes a while and needs your computer](#3-claude-can-keep-going-while-youre-away) 4. [Get startedSet up Claude on a real piece of your work](#get-started) *Conversations, projects, memory, skills, uploads, voice, and your connectors (email, calendar, Slack, Drive) work the same on the web, your phone, and the desktop app.* ## 1. Claude is one shortcut away[](#1-claude-is-one-shortcut-away) In the [Claude desktop app(opens in new tab)](https://claude.com/download), quick entry is a small Claude window that opens on top of whatever app you're in and stays in front as you switch apps. Reach it a few ways: - **Type:** Double-tap Option on a Mac, or use the shortcut you set in [Settings(opens in new tab)](https://claude.ai/desktop/settings/desktop) on Windows or Linux (beta), then type your question. - **Speak (Mac):** Press Caps Lock, talk, then press it again (turn it on in Settings). - **Menu bar or system tray:** Click the Claude icon in the menu bar (Mac) or system tray (Windows). Turn it on or off with the **Menu bar** or **System tray** setting in [Settings(opens in new tab)](https://claude.ai/desktop/settings/desktop). On a Mac you can also show your screen. Hover over a window to send a screenshot of it, or drag to capture part of the screen (the first time, choose **Turn on screenshots**). To attach a file, drag it onto the app icon or open it with Claude. Voice, dictation, and uploads work on the web, your phone, and the desktop app (dictation isn't available on Linux yet); the desktop app lets you reach these features in Claude quickly, from whatever app you're in. Things to ask: - *What do these numbers mean, and which one should I keep an eye on?* - *Summarize what's on my screen right now.* - *Help me word a reply to this message.* Loading  Good to know - Screenshots from quick entry and speaking with Caps Lock are Mac-only. On Windows and Linux, a keyboard shortcut brings up Claude. - The Linux app is in beta. See [Use quick entry on Mac(opens in new tab)](use-quick-entry-with-claude-desktop-on-mac.md) and [Claude for Linux (beta)(opens in new tab)](desktop-linux.md). ## 2. Claude can work in your files, apps, and websites[](#2-claude-can-work-in-your-files-apps-and-websites) On the desktop app, Claude can work directly in the files, apps, and websites where your work already is. Instead of carrying material to Claude and results away, you let Claude handle the whole task in place. You choose what Claude can use, and Claude works only with what you share: folders, apps, websites, or your screen. ### Folders[](#folders) On the web you might upload or drag in files. On the desktop app, Claude can go directly to your folders to read and edit what it needs and save finished work back to them. To give access: 1. Under the message box, add a folder. 2. Allow Claude to edit the files in it. With that permission, Claude reads what it needs from the folder and saves finished work back to it. Once Claude can see a folder, you can ask Claude to: - *Pull the numbers from a folder of PDF invoices into one spreadsheet.* - *Sort a cluttered Downloads folder into clearly named subfolders.* - *Each month, add the new invoices to that same spreadsheet, building a running record.* A task like that can later [run on a schedule(opens in new tab)](https://support.claude.com/en/articles/13854387-schedule-recurring-tasks-in-cowork). ### Apps[](#apps) [Connectors(opens in new tab)](https://claude.ai/directory) are available wherever you use Claude and connect tools like your email, docs, and CRM. In addition to those, the desktop app lets you add extensions like Apple Notes or Messages on a Mac. Add them from [Extensions in the desktop app(opens in new tab)](https://claude.ai/desktop/settings/desktop/extensions). See the [extensions guide(opens in new tab)](https://support.claude.com/en/collections/17879657-desktop-extensions). Things to ask: - *Turn the action items from this thread into a new Apple note.* - *Text Sam that I'm running ten minutes late.* - *Pull my notes on the Rivera account into a summary I can send.* ### Websites[](#websites) The built-in browser is a browser panel inside the desktop app, next to your task. Claude can open sites, read pages, click, type, and fill forms in it, and you watch each step as it happens. It has its own tabs and history, separate from your own browser, so your Chrome stays free for you while Claude works in its own window. 1. In Settings, set the built-in browser as your preferred browser. 2. Ask Claude to use a website. 3. The first time Claude acts on that site, you choose to allow it once, allow it always for that site, or deny it. Things to ask: - *Find the opening hours and phone number on this restaurant's site.* - *Fill out this online form using the details in my folder.* - *Check whether this part is in stock on the supplier's site.* Loading A task in Claude, on the web or the desktop app, can also work in your own Chrome through the [Claude in Chrome(opens in new tab)](https://claude.com/chrome) browser extension. The same extension opens Claude in Chrome next to the page you're on.  Some pages carry hidden text meant to mislead an AI, and safety checks reduce that risk without removing it. Start with sites you trust, and handle anything sensitive yourself, like bank accounts or health records. See [Use Claude in Chrome safely(opens in new tab)](https://support.claude.com/en/articles/12902428-using-claude-for-chrome-safely) and [Use the built-in browser(opens in new tab)](https://support.claude.com/en/articles/16607400). ### Your screen, through computer use (beta)[](#your-screen-through-computer-use-beta) For work that isn't in your files, connected tools, or on the web, computer use lets Claude work in other apps and programs by using your screen, mouse, and keyboard. Claude usually tries a connector first, then the built-in browser, and turns to computer use when neither fits, because clicking through one step at a time is the slowest of the three. Computer use suits installed software with no connector, like an accounting program, a design tool, or an internal company app, and work that moves between apps, such as taking figures from one program into another. Once it's turned on in Settings, Claude uses computer use on its own when a task needs it, or when you ask for it directly. While it works, Claude is moving the cursor and typing. Things to ask: - *Enter the receipts in this folder into my accounting app.* - *Copy the figures from this spreadsheet into our internal ordering system.* - *Resize these images in my photo editor and export them to this folder.*  By default, Claude asks before using an app, and you can stop Claude at any time. Claude can see what's on your screen while it works, so close anything sensitive first. See [Let Claude use your computer(opens in new tab)](../15-Claude-AI-Features/let-claude-use-your-computer-in-cowork.md). ### Record a skill[](#record-a-skill) [Skills(opens in new tab)](../02-Claude-Code-CLI/what-are-skills.md) are saved instructions that let Claude repeat a workflow the way you do it, whenever that work comes up. Some workflows are easier to show than to write down, so you can record one instead. 1. Start it from the plus menu in the message box. 2. Do the task once, saying what you're doing as you go. 3. Choose **Done**, and Claude turns the recording into a skill. The skill is then available in Claude. While recording, don't type passwords or secrets, or show sensitive information or private conversations. Things to record: - *Pull each store's weekly sales from its dashboard into our shared sheet.* - *Copy new leads from the form into the CRM the way I do it.* - *File each week's reports into the right folders by client.* Loading  Good to know Working in your folders, the built-in browser, computer use, and Record a skill need a paid plan: - Folders come with every paid plan. - The built-in browser is on Pro, Max, Team, and Enterprise. On Team and Enterprise plans, your organization's owner controls whether it's available. - Computer use is in beta on Mac and Windows, for Pro and Max. - Record a skill is on Pro, Max, and Team, on Mac. On Team and Enterprise plans, your admin can limit which extensions are allowed. See [Install Claude Desktop(opens in new tab)](https://support.claude.com/en/articles/10065433-install-claude-desktop). ### All of it together[](#all-of-it-together) The desktop app lets a single task draw on your local files, your [connectors(opens in new tab)](https://support.claude.com/en/collections/15399129-connectors), and the web together. Uploading and connectors already work everywhere; here they combine with Claude's ability to view, edit, and save files directly on your computer. Try prompts like: - *Read my resume in my Downloads folder and my project files in Google Drive, then look through job sites for roles that fit and shortlist the best ones.* - *Compare the invoices in my Vendors folder against the bills in Gmail, then check each vendor's website for current pricing.* - *Read the deck in my Pitch folder, check my calendar for the client meeting, and look up their latest news on their website.* ## 3. Claude can keep going while you're away[](#3-claude-can-keep-going-while-youre-away) Start a big task and step away. It keeps going after you close the window, and you can check on it or answer its questions from the web or the mobile app. When the task is working in a folder, an app, or the browser on your computer, that computer is part of the task, so keep it on and awake with the desktop app open. **Keep computer awake** in Settings stops it from idle-sleeping while the app is open. The display can still turn off, and closing the laptop lid still puts it to sleep.  Working in code? If you write software, everything on this page applies to code work too, and the desktop app adds Claude Code, a visual coding workbench. See the [Claude Code desktop guide(opens in new tab)](desktop.md) to get started. ## Get started[](#get-started) Loading [Download the desktop app(opens in new tab)](https://claude.com/download) for Mac, Windows, or Linux (beta). - [1. Claude is one shortcut away](#1-claude-is-one-shortcut-away) - [2. Claude can work in your files, apps, and websites](#2-claude-can-work-in-your-files-apps-and-websites) - [3. Claude can keep going while you're away](#3-claude-can-keep-going-while-youre-away) --- ## Use Claude app intents, shortcuts, and widgets on iOS | Claude Help Center Source: https://support.claude.com/en/articles/10263469-use-claude-app-intents-shortcuts-and-widgets-on-ios Path: 16-Mobile-Desktop/use-claude-app-intents-shortcuts-and-widgets-on-ios.md # Use Claude app intents, shortcuts, and widgets on iOS July 9, 2026 The features described in this guide are available on iOS 18 and above. Claude for iOS supports multiple powerful features: the Claude widget, the "Analyze Photo with Claude" control, the "Ask Claude" App Intent, and the ability to use this intent within iOS Shortcuts. This guide will explain these features and show you how to make the most of them. ## Ask Claude intent The "Ask Claude" intent is a standalone feature that lets you interact with Claude directly from: - Spotlight search - Siri - The Share menu - Any app that supports iOS intents You can use this intent on its own to quickly ask Claude questions or give it tasks without opening the Claude app. For example, you can: - Select text and use the Share menu to send it directly to Claude - Ask Siri to "Ask Claude” and it will prompt you for a message - Type "Ask Claude" in Spotlight search to quickly send a query ## Use Ask Claude with shortcuts While the "Ask Claude" intent is powerful on its own, you can also use it as a building block within the Shortcuts app to create more complex workflows. Shortcuts allow you to: - Chain multiple "Ask Claude" actions together - Combine Claude's capabilities with other apps and actions - Create automated workflows - Process Claude's responses in various ways ## Create your first Claude shortcut There are many customizable workflows you can set up within the Shortcuts app. Let's look at an example of a brief but useful shortcut that helps you summarize text: 1. Open the Shortcuts app on your iOS device 2. Tap the "+" button to create a new shortcut 3. Add the "Share" action and select your preferred input type 4. Add the "Ask Claude" action 5. In the "Ask Claude" action, create a prompt like: "Please summarize the following text: \[Shortcut Input\]" 6. Name your shortcut (e.g., "Summarize with Claude") 7. Optional: Add the shortcut to your Share Sheet for easy access Now you can select text anywhere in iOS, tap the Share button, and choose your "Summarize with Claude" shortcut to get an instant summary. When using "Ask Claude" intent and in shortcuts, the default model you see when opening the Claude app will be used. More information on setting up shortcuts on your iOS device can be found [here](https://support.apple.com/guide/shortcuts/welcome/ios). **Note:** When using the "Ask Claude" intent, messages to Claude will count towards your overall usage limit. ## Add the Claude Widget The Claude widget provides quick access to chat and voice features directly from your Home Screen or Today View. The widget includes buttons for: - Starting a new chat - Instantly opening the app in dictation mode - Taking a photo to share with Claude ### Add the Claude widget to your Home Screen 1. From the Home Screen, touch and hold a widget or an empty area until the apps jiggle 2. Tap Edit in the upper-left corner 3. Tap Add Widget 4. Search for and select Claude 5. Tap Add Widget 6. Tap Done ### Add the Claude widget to your Today View Swipe right from the Home Screen or Lock Screen, then follow the same steps as adding to the Home Screen. ### Use the widget - Tap the chat button to start a new conversation with Claude. - Tap the microphone button to instantly open the app in dictation mode, allowing you to start speaking to Claude right away. - Tap the camera button to take a photo and share it with Claude for analysis. **Note:** Like the "Ask Claude" intent, interactions started through the widget will count toward your usage limit. ## The Analyze Photo with Claude control The "Analyze Photo with Claude" control lets you quickly send images to Claude for analysis directly from Control Center or your Lock Screen. ### Add to Control Center 1. Open Control Center (swipe down from the top-right corner on iPhones with Face ID, or swipe up from the bottom on iPhones with a Home button) 2. Tap the Add button (plus sign) at the top left of Control Center to begin editing 3. Tap "Add a Control" at the bottom of the screen to open the controls gallery 4. Find and tap "Analyze Photo with Claude" to add it to Control Center 5. You can rearrange its position by dragging it to your preferred location 6. When finished, close Control Center by swiping up from the bottom center of the screen Once added, you can quickly access it from Control Center by swiping down from the top-right corner of the screen. More information on using and setting up controls via Control Center can be found [here](https://support.apple.com/guide/iphone/use-and-customize-control-center-iph59095ec58/ios). ### Add to your lock screen 1. On your Lock Screen, touch and hold until the customization screen appears 2. Tap "Customize" 3. Select the lock screen you want to modify 4. Remove one of the controls at the bottom of the screen using the Remove button (minus sign), then tap the Add button (plus sign) to open the controls gallery 5. From the available controls menu, scroll or search for "Analyze Photo with Claude" 6. Tap to select it 7. Tap "Done" to save your changes You can now quickly access the "Analyze Photo with Claude" control without needing to unlock your device or open the Claude app first. --- ## Use Claude Cowork on web, desktop, and mobile | Claude Help Center Source: https://support.claude.com/en/articles/15520349-use-claude-cowork-on-web-desktop-and-mobile Path: 16-Mobile-Desktop/use-claude-cowork-on-web-desktop-and-mobile.md # Use Claude Cowork on web, desktop, and mobile Claude Cowork is available on desktop, web, mobile, and in the Claude in Chrome side panel. Your sessions and files live with your Claude account and go where you go, on any device. This article explains how to start a Cowork session and what's available on each surface. Claude Cowork runs in the cloud on Pro and Max plans. It’s in beta on web and mobile for Team plans, and on Enterprise plans where an admin has enabled it. Cowork is also available in the Claude in Chrome side panel on Max and Team plans, on Pro plans as it rolls out, and on Enterprise plans where an admin has enabled it. See **[Claude in Chrome admin controls](../13-Enterprise-Admin/claude-for-chrome-admin-controls.md#h_bdb63199e1)** for enablement steps. **Note:** Claude Cowork is now just Claude. Ask for what you need, and Claude decides whether that’s a quick answer or a task. This is rolling out gradually to Pro and Max plans, and it’s in beta for Enterprise plans, where an admin turns it on as **Chat and Cowork unified (beta)**. If your message box no longer shows “Chat” and “Cowork” options, you have the new experience, and some steps in this article may look different. Learn more in **[Claude Cowork and chat are one Claude](https://support.claude.com/en/articles/16761823)**, or read our **[blog post](https://claude.com/blog/cowork-is-now-claude)**. For Enterprise owners, see **[Set up and manage the new unified Claude experience for your Enterprise organization](../13-Enterprise-Admin/set-up-and-manage-the-new-unified-claude-experience-for-your-enterprise-organization.md)**. ------------------------------------------------------------------------ ## Start a Cowork session On desktop, web, and mobile, chat and Cowork share one home, so you start both from the same place. Find the message box, select "Cowork" in the bottom left corner, then describe your task. To go back to a regular conversation, select "Chat." If you have the new Claude experience, there's no "Cowork" option to select. Describe your task in any conversation, and Claude takes it from there. The Chrome side panel works differently. Opening the side panel starts a Cowork session directly, with no selector to switch between chat and Cowork. - **Web:** Go to **[claude.ai](https://claude.ai)** and find the “Home” tab. - **Mobile:** Open the latest version of Claude for iOS or Claude for Android. If you don't see the Cowork option in the message box, update the app. - **Desktop:** Open the latest version of the Claude Desktop app. If you don't see the Cowork option in the message box, update the app. Desktop is the full Cowork experience, where Claude can also use your local files and browser. - **Chrome:** Click the Claude icon in your Chrome toolbar to open the side panel. The side panel starts a Cowork session, so there's no need to select "Cowork" first. **Note:** To run a task without using or adding to your memory, turn off "Memory" in the "+" menu before you start the task. ------------------------------------------------------------------------ ## How Cowork in the cloud works When using Cowork in the cloud, Claude's work runs on Anthropic's servers instead of your computer, and your sessions and files are saved to your Claude account. This changes what Cowork can do: - Work continues in the background. Close your laptop and Claude keeps going. - Scheduled tasks run with no device online. - The same sessions and files are available on desktop, web, and mobile. - On Pro and Max plans, new sessions run in the cloud on every surface. Tasks you started on your computer before October 6 stay there so you can finish them. There’s no setting to choose where a task runs on Pro and Max plans. For details on how cloud and local sessions are isolated and what each can access, see **[Claude Cowork architecture overview](../15-Claude-AI-Features/claude-cowork-architecture-overview-claude-help-center.md)**. For safety guidance, see **[Use Claude Cowork safely](../15-Claude-AI-Features/use-claude-cowork-safely-claude-help-center.md)**. ------------------------------------------------------------------------ ## What changed for Pro and Max plans on October 6 On October 6, 2026, new Cowork tasks on Pro and Max plans run in the cloud. The **Only on your computer** option in **[Settings \> General](https://claude.ai/settings/general)** was removed. If you were still set to run Cowork only on your computer, you’re moved to the cloud the next time you open the desktop app, and you’ll see a notice. There’s nothing to set up, and you can’t switch back. Tasks you already started on your computer stay there, and you can keep working on them until they're done. Each one shows a banner saying it runs only on this computer. Your folders stay on your computer. Claude reaches only the folders you've connected, through the desktop app, and only while it's open. When a task needs a file in the cloud, Claude fetches a copy of just that file. When you delete a session, the copies Claude fetched are deleted too, per our **[data retention practices](https://privacy.claude.com/en/articles/10023548-how-long-do-you-store-my-data)**. Whether your conversations are used to improve Claude follows the **Help improve our AI models** setting in **[Settings \> Privacy](https://claude.ai/settings/data-privacy-controls)**. Scheduled tasks that already run on your computer keep running there. New scheduled tasks run in the cloud. See **[Schedule recurring tasks in Claude Cowork](https://support.claude.com/en/articles/13854387)**. ### If you want tasks to run on your computer For new tasks that run only on your computer, use Claude Code in the desktop app. It runs on your computer and keeps your folders and history there. **[Get Claude Code desktop](https://claude.com/download)**. To bring a Cowork task with you: 1. Open the task and select “Download task data.” 2. Unzip the download and open the folder in Claude Code. 3. Run /port-task-data to pick up with your context. To keep a copy of everything, select “Export your Cowork data” on the card on the desktop home. If you use Claude at work and at home and want them separate, use a separate account for each. Shared logins aren't supported. ------------------------------------------------------------------------ ## What's available on each surface Cowork in the cloud is in beta on Team and Enterprise plans, and some features aren’t available yet. Here's what you can use on each surface today: [TABLE] A few notes on the table: - \*Local file access, local connectors, browser use, and computer use from web and mobile work through the Claude Desktop app. A cloud session can read and write files in folders you've connected on your computer only while the desktop app is open on that computer and the session was started on desktop or is a scheduled task. If the app is closed, the session keeps running but can't reach your local files. - Projects are available on every surface. From a project you can start a chat or a Cowork session, and Claude uses the project's knowledge as context. Projects tied to a local folder support Cowork sessions on desktop only, and Cowork won't change a project's contents, so add anything you want to keep to the project yourself. For more information, see **[Organize your tasks with projects in Claude Cowork](https://support.claude.com/en/articles/14116274)** and **[Use live artifacts in Claude Cowork](https://support.claude.com/en/articles/14729249)**. - Artifacts created on or after August 19, 2026 are available on the desktop app and web. Live artifacts created before that date are available on the desktop app only. For more information, see **[Use artifacts in Claude Cowork](https://support.claude.com/en/articles/14729249)**. - Local connectors and plugins that include local MCP servers work through the desktop app only. - Scheduled tasks run in the cloud, so they no longer need your computer to be awake. For more information, see **[Schedule recurring tasks in Claude Cowork](https://support.claude.com/en/articles/13854387)**. - Computer use is in beta for Pro and Max plans. For more information, see **[Let Claude use your computer in Cowork](https://support.claude.com/en/articles/14128542)**. ## What requires the desktop app Some capabilities reach things on your computer, so they need the Claude Desktop app open on your machine, even when your session runs in the cloud: - **Local file access.** Claude reads and writes files in folders you've connected on your computer. A session in the cloud reaches these files only while the desktop app is open, only for folders you've connected, and with the permissions you've already set. - **Local connectors.** This includes plugins using those connectors. - **Browser use.** On desktop, Claude uses a browser built into the Claude Desktop app by default (rolling out gradually this week), or your own Chrome browser through Claude in Chrome if that's your preferred browser. When the desktop app is online, the built-in browser is also available in Cowork on web or mobile. A session started on desktop can be steered from web or mobile while the desktop app stays open. In the Chrome side panel, Claude can read the tab you're on without the desktop app. Claude driving a browser as part of a task still needs the desktop app open. Learn more in **[Use the built-in browser in Claude Cowork](https://support.claude.com/en/articles/16607400)**. - **Computer use.** Claude clicks, types, and navigates your screen directly. ## Move between surfaces When using Cowork in the cloud, sessions follow your account, so you can switch surfaces mid-task: 1. Start a task on any surface. 2. Open the same session from another surface to check progress, answer Claude's questions, or redirect the work. 3. Pick up the finished output wherever you are. For example, start a task in the Chrome side panel while you're looking at a dashboard, then pick it up on desktop to work with the downloaded files. When Claude finishes a task or needs your input, you'll get a notification on your phone. To get started, see **[Get started with Claude Cowork](../15-Claude-AI-Features/get-started-with-claude-cowork-claude-help-center.md)**. --- ## Use quick entry with Claude Desktop on Mac | Claude Help Center Source: https://support.claude.com/en/articles/12626668-use-quick-entry-with-claude-desktop-on-mac Path: 16-Mobile-Desktop/use-quick-entry-with-claude-desktop-on-mac.md # Use quick entry with Claude Desktop on Mac March 16, 2026 Quick entry is a redesigned experience for Claude Desktop on Mac that lets you access Claude instantly from anywhere on your computer. With quick entry, you can start chats, capture screenshots, share application windows, and use voice dictation to interact with Claude without navigating away from your current task. Quick entry is available to all Claude users (free, Pro, Max, Team, and Enterprise plans) using Claude Desktop on macOS. ## Key features Quick entry includes three main capabilities: - **Instant access**: Double-tap the Option key to open Claude from any app. - **Visual context**: Capture screenshots or click application windows to share what you're working on. - **Voice input**: Press Caps Lock to dictate your message to Claude with real-time transcription. ## System requirements To use quick entry, you need: - macOS 12 or later for quick entry features - macOS 14 or later for voice dictation - Claude Desktop installed and running (can be in the background) ## Setting up quick entry When you first open the updated version of Claude Desktop, you'll see a prompt to enable quick entry shortcuts. ### Enable the chat shortcut 1. Check the box for **Turn on shortcut** in the quick entry prompt. 2. Click "Continue." 3. Double-tap the Option key to test the shortcut. 4. Moving forward, manage this in Settings \> General (under **Desktop app**). Once enabled, double-tapping Option will open a text box where you can type your message and start a new chat. You can also click "New chat" to see your five most recent conversations. ### Enable the voice shortcut (optional) The voice dictation shortcut is disabled by default because it takes over your Caps Lock key. To enable voice dictation: 1. Check the box for **Turn on shortcut** in the voice dictation prompt. 2. Click "Continue." 3. Press Caps Lock once to start dictating. 4. Press Caps Lock again when you're finished speaking. 5. Click the arrow to send your transcribed message to Claude. 6. Moving forward, manage this in Settings \> General (under **Desktop app**). ## Using quick entry ### Start a quick conversation 1. Double-tap the Option key from any application. 2. Type your message in the text box that appears. 3. Click the arrow icon or press Enter to send your message to Claude. ### Capture a screenshot 1. Open quick entry by double-tapping the Option key. 2. A "Drag to take a screenshot" prompt will appear by your cursor. 3. Click and drag to select the area of your screen you want to screenshot. 4. The screenshot will be attached to your message to Claude. ### Share an application window 1. Open quick entry by double-tapping the Option key. 2. Click an application window to attach its contents to your message. 3. Add any additional context or questions. 4. Send your message to Claude. ### Use voice dictation 1. Press Caps Lock to start dictating (if enabled). 2. Speak your message—you'll see your words transcribed in real-time. 3. Press Caps Lock again to stop dictating. 4. Review your transcribed message. 5. Click the arrow to send it to Claude. ## Customizing shortcuts You can customize quick entry shortcuts in your Claude Desktop settings. 1. Open Claude Desktop. 2. Go to Settings \> General (under **Desktop app**). 3. Choose from the following next to **Quick access shortcut**: - Double-tap Option (default) - Option + Space - Custom keyboard shortcut 4. Click the dropdown next to **Voice shortcut** to: - Enable Caps Lock for voice input - Set a custom keyboard shortcut - Disable the shortcut entirely ## Permissions Quick entry requires certain macOS permissions to function: - **Screen recording**: Required to capture screenshots and share application windows. - **Accessibility**: Required for quick entry functionality. - **Speech recognition**: Required for voice dictation (macOS 14+ only). You can review or change these permissions in System Settings \> Privacy & Security. ## Common use cases Quick entry is designed for moments when you need Claude's help without breaking your flow: - **Code review**: Share error messages or application windows directly with Claude for debugging assistance. - **Quick answers**: Get instant assistance from Claude without switching away from your current task. - **Research and writing**: Capture screenshots while browsing and ask contextual questions. - **Brainstorming**: Use voice dictation for hands-free ideation while thinking or moving around. ## FAQ ### Do I need to keep Claude Desktop open to use quick entry? Yes. Claude Desktop needs to be running on your Mac, but it can run in the background. You don't need to have the Claude window visible. ### Can I use quick entry on Windows? No. Quick entry is currently only available for macOS users. Windows users can still access Claude Desktop, but without the quick entry features. ### Is my voice recorded when I use dictation? Voice dictation transcribes your speech to text in real-time. The transcribed text is sent to Claude as part of your message, just like any other text input. ### Can I disable quick entry after enabling it? Yes. You can disable quick entry shortcuts at any time in Settings \> General \> Desktop App. You can turn off the quick access shortcut, voice shortcut, or both. ### What if the shortcuts conflict with other apps? You can customize the quick access shortcut to use Option + Space or create a custom keyboard shortcut that doesn't conflict with your other applications. The voice shortcut can only use Caps Lock or be disabled. --- ## Use Claude with Android apps | Claude Help Center Source: https://support.claude.com/en/articles/11869629-using-claude-with-android-apps Path: 16-Mobile-Desktop/using-claude-with-android-apps.md # Use Claude with Android apps August 25, 2026 Claude can now connect with your Android device's system apps to help you take action directly from your conversations. When you chat with Claude, it can draft messages, emails, calendar events, set alarms and timers, find locations, and more—all through your everyday apps without copy-paste. This feature is supported on all Claude plans and works with your device's native and third-party apps, including messaging, email, calendar, alarms, timers, location services, maps, and Health Connect (in beta on Pro and Max plans only). ## What can Claude do with Android apps? Claude can help you: - **Draft and send messages** through your default messaging app or third-party apps (e.g. WhatsApp, Slack, Messenger). - **Compose emails** that open directly in your Android device's email app with content pre-filled. - **Access your location** to provide contextual suggestions for nearby places and services. - **Display locations on maps** and help you navigate to restaurants, stores, and other destinations. - **Read and manage your calendar** to check availability, create events, and schedule meetings. - **Set alarms** directly through your Clock app. - **Set timers** directly for cooking, workouts, or any activity. - **Read and analyze your health data** through Health Connect to help you understand fitness patterns, track progress toward goals, and visualize trends with native charts. ### Limitations - **Location:** Members of Team or Enterprise plans can’t access the location tool at this time. - **Calendar:** Ability to edit events depends on your ownership of the event. - **Reminders:** These are exclusively available on Claude for iOS, so Claude can’t create and manage reminders on Android. - **Contacts:** Claude does not have direct access to your contacts. - **Health:** Available on Pro and Max plans only. Requires Android 14 or later and Health Connect. Currently limited to users in the US. Claude can read health data but cannot write or modify entries in Health Connect. ------------------------------------------------------------------------ ## How Claude helps you take action When Claude determines that using one of these features would be helpful, it will automatically offer to help. You'll see a card or prompt within your conversation that lets you review and take action with Claude’s help. ### Send texts and emails with Messages and Mail 1. Ask Claude to help draft a message or email (for example: "Draft an email to my supervisor about the project update"). 2. Claude will prepare the content and show you a preview. 3. Tap the message card to open your messaging or email app. 4. Review the pre-filled content and make any changes if needed. 5. Send the message as you normally would. **Example:** "Draft a message to my study group about canceling tonight's session." ### Use location for contextual suggestions 1. Ask Claude for location-based recommendations (for example: "What restaurants are near me?"). 2. Claude will request access to your location if not already granted. 3. Based on your location, Claude provides relevant suggestions. 4. You can view locations on a map and get navigation directions. **Example:** "Find nearby parks for jogging." ### Display locations with Maps 1. When Claude suggests locations, they can be displayed on an interactive map. 2. Tap on any location to see more details. 3. Select a location to open it in Google Maps for navigation. 4. Get turn-by-turn directions directly from the map. **Example:** "Show me hardware stores within five miles on a map." ### Manage your calendar 1. Ask Claude to check your schedule or create events. 2. Claude will request calendar access if not already granted. 3. For checking availability: Claude reads your calendar and identifies free slots. 4. For creating events: Claude prepares event details and adds them to your calendar. 5. You can edit or delete events as needed. **Examples:** - "What meetings do I have tomorrow?" - "Schedule a team lunch for next Thursday at noon." - "Create a recurring workout session every Tuesday and Thursday at 6 AM." ### Set alarms and timers using Clock apps 1. Ask Claude to set an alarm or timer. 2. Claude will automatically create the alarm or start the timer. 3. Your device's Clock app will handle the alarm or timer. 4. You'll receive notifications as normal when the alarm goes off or timer ends. **Examples:** - "Set an alarm for 7 AM tomorrow." - "Start a 20-minute timer for my workout." ------------------------------------------------------------------------ ## Access and analyze your health data **Note:** Health features are available in beta on Pro and Max plans only, require Android 14 or later, and are limited to users in the US. Claude can read your health and fitness data from Health Connect to help you understand patterns, track progress, and make informed decisions about your wellbeing. When you ask Claude about your health data, it can display insights using native charts that feel integrated with Android. **Important:** We are not a medical device and cannot provide medical guidance. Always consult a licensed professional. ### What is Health Connect? Health Connect is Android's centralized platform for health and fitness data. It aggregates information from various fitness apps and wearables (like Fitbit, Samsung Health, and Google Fit) into a single, secure location. Claude accesses your health data through Health Connect, which means it can see data from any app you've connected to Health Connect. If you haven't set up Health Connect yet, you can find it in your device settings or download it from the Google Play Store. ### What health data can Claude access? With your permission, Claude can read the following types of data from Health Connect: - **Activity metrics:** Steps, distance, floors climbed, active calories, and exercise duration - **Workouts:** Type (running, cycling, strength training, etc.), duration, distance, heart rate data, and calories burned - **Vitals:** Heart rate, resting heart rate, heart rate variability (HRV), blood pressure, respiratory rate, and blood oxygen - **Body measurements:** Weight, height, body mass index, and body fat percentage - **Sleep:** Total sleep time, sleep stages, and time in bed - **Nutrition:** Calories consumed, macronutrients, hydration, and micronutrients (if tracked) **Note:** By default, Claude doesn't save health information to memory. If you turn on **Include sensitive topics in memory**, Claude may remember health-related context from your conversations. Learn more about **[sensitive topics in memory](https://support.claude.com/en/articles/11817273-use-claude-s-chat-search-and-memory-to-build-on-previous-context#h_6fe1d0e66f)**. ### How to use health features 1. Ask Claude a question about your health or fitness data (for example: "How active have I been this week?" or "Show me my sleep trends"). 2. Claude will request access to your health data through Health Connect if not already granted. 3. Review the permission prompt and select the data types you want to share. 4. Claude analyzes your data and provides insights, often with visual charts to help you understand trends. ### Example prompts - "Help me understand my workout patterns over the past month." - "I've been sleeping poorly—can you analyze my sleep data and look for patterns?" - "Show me how my daily step count compares week over week." - "What's my average resting heart rate, and how has it changed recently?" - "Create a summary of my fitness activity for the past 30 days." ### Understanding health visualizations Claude displays health insights using native Android charts that appear directly in your conversation. These charts can show: - **Bar charts** for comparing activity across days or weeks - **Line charts** for tracking trends over time (pace, heart rate, weight) - **Progress indicators** for goals and milestones Tap on chart elements to see more details about specific data points. ## Usage guidelines for optimal results Be specific about what type of action you want Claude to take and include all relevant details like recipients, dates, times, and durations in your request. For alarms, specify AM/PM and any recurring days you need. For timers, mention what the timer is for to help with labeling. Always review content in the destination app before sending or saving. ------------------------------------------------------------------------ ## What data can Claude access? Claude only accesses the data necessary for each specific request: - **Location:** Current location only when relevant to your request. - **Calendar:** Event details to check availability and create/modify events. - **Messages/Email:** Claude does not read existing messages or emails, only creates new content. - **Alarms and timers:** Created directly without accessing personal data. - **Health:** Activity, workout, vital signs, body measurements, sleep, and nutrition data from Health Connect — only when you ask a question that requires this information and have granted permission. Claude's connection to your Android apps works through your device's standard sharing system and intent system—the same secure methods used by all Android apps. ## Do I need to grant permissions to Claude for Android? Permission requirements vary by feature: - **Messages and Email:** No permissions required (uses Android's sharing system). - **Calendar Events:** Claude needs your permission to read your calendar and view events, but can write to your calendar or draft calendar events using just the system UI (no permissions required). - **Location and Maps:** Permission required when Claude needs to access your location. - **Alarms and Timers:** Uses your device's standard alarm and timer functions. - **Health Connect:** Permission required. Claude will request access to specific health data categories when needed. For features requiring permissions (like location or calendar access), Claude will request permission contextually with clear explanations of why the access is needed. You’ll be prompted to approve the action with three options: Allow once, Always allow, or Don't allow. These permissions can be managed at any time in your device settings by going to Settings \> Apps \> Claude \> Permissions. Click into each permission listed under **Allowed** and **Not allowed** to make changes. You can toggle between “Allow only while using the app” or “Ask every time” to change Claude’s access, or remove permissions by choosing “Don’t allow.” Claude will only request permissions if needed for specific features, and you can always choose to decline while still using other capabilities. Health Connect permissions are managed separately from other app permissions. When Claude requests health access, you'll see the Health Connect permissions screen where you can choose exactly which data types to share. You can modify these permissions at any time by going to Settings \> Apps \> Health Connect \> App permissions \> Claude. ------------------------------------------------------------------------ ## Troubleshooting ### Claude isn't offering to use my apps - Make sure you're using the latest version of Claude for Android. For instructions, see **[How to update Claude for Android](how-to-update-claude-for-android.md)**. - Try being more specific about wanting to send a message, create an event, or set a timer (see examples above). - Restart Claude for Android and try again. ### Permission prompts don't appear - Check that the app for which Claude needs permissions is installed and set up on your phone. - Navigate to Settings \> Apps \> Claude to verify that Claude for Android has the required permissions. - Ensure your Android OS is up to date. ### Sharing options don't appear for messages or emails - Check that you have messaging and email apps installed and set up. - Try clearing the Claude for Android cache in your device settings: - Navigate to your app settings and select "Claude" from the list. - Select "Storage & cache." - Tap "Clear cache." ### Calendar events aren't opening correctly - Verify you have a calendar app installed. - Check that your preferred calendar app is set as the default for calendar events. - Make sure the calendar app you’re trying to use is up to date. ### Alarms or timers aren't being created - Ensure your device's Clock app is enabled and up to date. - Check that "Do Not Disturb" settings aren't preventing alarms. ### Content appears different than expected - Your Android mobile apps may format content slightly differently than Claude. - You can always edit the content in the destination app before sending or saving. - Some features may vary depending on your specific Android version and device manufacturer. ### Health data isn't appearing or seems incomplete - Verify that you have a Pro or Max plan and are located in the US. - Ensure you're running Android 14 or later. - Check that Health Connect is installed and that your fitness apps are connected to it. - Verify that you've granted Claude access to the relevant health data types in Settings \> Apps \> Health Connect \> App permissions \> Claude. - If you recently started using Health Connect, there may not be enough historical data for trend analysis. - Some data types require a compatible wearable device (like a Fitbit or Samsung Galaxy Watch). - Health Connect isn’t supported when using work profiles on Android devices. **Need more help?** If you're experiencing issues with these features, try restarting Claude for Android or **[updating the app to the latest version from the Google Play Store](how-to-update-claude-for-android.md)**. --- ## Use Claude with iOS apps | Claude Help Center Source: https://support.claude.com/en/articles/11869619-using-claude-with-ios-apps Path: 16-Mobile-Desktop/using-claude-with-ios-apps.md # Use Claude with iOS apps August 25, 2026 Claude can now connect with your iOS device's system apps to help you take action directly from your conversations. When you chat with Claude, it can draft messages, emails, or calendar events, find locations, manage reminders, and analyze your health and fitness data — all seamlessly integrated with your mobile apps. This feature is supported on all Claude plans and works with iOS system apps (Messages, Mail, Calendar, Maps, Reminders, and Location Services), as well as compatible third-party apps. Health features are currently in beta, require a Pro or Max plan, and are available in the US only. ## What can Claude do with iOS apps? Claude can help you: - **Draft and send messages** through the Messages app or any messaging platform like WhatsApp, Slack, or Messenger. - **Compose emails** that open directly in the Mail app or any other email platform like Gmail or Outlook with the subject and content pre-filled. - **Access your location** to provide contextual suggestions for nearby places and services. - **Display locations on maps** and help you navigate to restaurants, stores, and other destinations. - **Read and manage your calendar** to check availability, create events, and schedule meetings. - **Create and manage reminders** to help you stay organized with tasks and lists. - **Read and analyze your health data** to help you understand fitness patterns, track progress toward goals, and visualize trends with native charts (Pro and Max plans only). ### Limitations - **Location:** Members of Team or Enterprise plans can’t access the location tool at this time. - **Calendar:** Ability to edit events depends on your ownership of the event. - **Reminders:** Claude cannot create or edit reminder lists themselves, only items within existing lists. - **Contacts:** Claude does not have direct access to your contacts. - **Health:** Available in beta on Pro and Max plans only. Currently limited to users in the US. Claude can read health data but cannot write or modify entries in Apple Health. ------------------------------------------------------------------------ ## How Claude helps you take action When Claude determines that using one of these features would be helpful, it will automatically suggest it. You'll see a card or prompt within your conversation that lets you review and take action with Claude’s help. ### Send texts and emails with Messages and Mail 1. Ask Claude to help draft a message or email (for example: "Help me write a text to my team about tomorrow's meeting"). 2. Claude will prepare the message and show you a preview. 3. Tap the message card to open your Messages app or Mail app. 1. Third-party apps (WhatsApp, Messenger, Signal) are also supported. 4. Review the pre-filled content and make any changes if needed. 5. Send the message as you normally would. **Example:** "Draft an email to my manager explaining that I'll be late to the morning meeting due to a doctor's appointment." ### Use location for contextual suggestions 1. Ask Claude for location-based recommendations (for example: "What's nearby for dinner?"). 2. Claude will request access to your location if not already granted. 3. Based on your location, Claude provides relevant suggestions. 4. You can view locations on a map and get navigation directions. **Example:** "Find good restaurants near me that are open now." ### Display locations with Maps 1. When Claude suggests locations, they can be displayed on an interactive map. 2. Tap on any location to see more details. 3. Select a location to open it in Apple Maps for navigation. 4. Get turn-by-turn directions directly from the map. **Example:** "Show me coffee shops within walking distance on a map." ### Manage your calendar 1. Ask Claude to check your schedule or create events. 2. Claude will request calendar access if not already granted. 3. For checking availability: Claude reads your calendar and identifies free slots. 4. For creating events: Claude prepares event details and adds them to your calendar. 5. You can edit or delete events as needed. **Examples:** - "When am I free this week for a 30-minute meeting?" - "Schedule a dentist appointment for next Friday at 10 AM." - "Add a weekly team standup every Monday at 9 AM." ### Create and manage reminders 1. Ask Claude to create reminders or add items to lists. 2. Claude will request Reminders access if not already granted. 3. Claude can add items to existing lists or create new reminders. 4. Set due dates, priorities, and notes for reminders. 5. Manage recurring reminders for regular tasks. **Examples:** - "Add milk and eggs to my grocery list." - "Remind me to call the dentist tomorrow at 2 PM." - "Create a packing list for my trip next week." Note that when Claude uses tools to take these actions, their use is preserved in the conversation history in the same way as any tool. ------------------------------------------------------------------------ ## Access and analyze your health data **Note:** Health features are available in beta on Pro and Max plans only, and currently limited to users in the US. Claude can read your health and fitness data from Apple Health to help you understand patterns, track progress, and make informed decisions about your wellbeing. When you ask Claude about your health data, it can display insights using native charts that feel integrated with iOS. **Important:** We are not a medical device and cannot provide medical guidance. Always consult a licensed professional. ### What health data can Claude access? With your permission, Claude can read the following types of data from Apple Health: - **Activity metrics:** Steps, distance, flights climbed, active calories, exercise minutes, move and stand hours. - **Workouts:** Type (running, cycling, strength, yoga, etc.), duration, distance, heart rate data, and calories burned. - **Vitals:** Heart rate, resting heart rate, heart rate variability (HRV), blood pressure, respiratory rate, and blood oxygen. - **Body measurements:** Weight, height, body mass index, and body fat percentage. - **Sleep:** Total sleep time, sleep stages, time in bed, and sleep efficiency. - **Nutrition:** Calories consumed, macronutrients, water intake, and micronutrients (if tracked). **Note:** By default, Claude doesn't save health information to memory. If you turn on **Include sensitive topics in memory**, Claude may remember health-related context from your conversations. Learn more about **[sensitive topics in memory](https://support.claude.com/en/articles/11817273-use-claude-s-chat-search-and-memory-to-build-on-previous-context#h_6fe1d0e66f)**. ### How to use health features 1. Ask Claude a question about your health or fitness data (for example: "How have my runs been trending this month?" or "Show me my sleep patterns over the past two weeks"). 2. Claude will request access to your health data if not already granted. 3. Review the permission prompt and select your preferred option. 4. Claude analyzes your data and provides insights, often with visual charts to help you understand trends. ### Example prompts - "Help me create a training plan for my upcoming half-marathon based on my recent running data." - "Why have I been feeling tired lately? Can you look at my sleep and activity data?" - "Show me how my resting heart rate has changed over the past three months." - "Compare my workout consistency this month versus last month." - "What patterns do you see in my step count throughout the week?" ### Understanding health visualizations Claude displays health insights using native iOS charts that appear directly in your conversation. These charts can show: - **Bar charts** for comparing activity across days or weeks. - **Line charts** for tracking trends over time (pace, heart rate, weight) - **Progress indicators** for goals and milestones Tap on chart elements to see more details about specific data points. ## Usage guidelines for optimal results To get the best results, be specific about what you want, include relevant details like dates, times, and locations in your requests, and review content before sending or saving. Claude understands natural language, so you can make requests conversationally. ------------------------------------------------------------------------ ## What data can Claude access? Claude only accesses the data necessary for each specific request: - **Location:** Current location only when relevant to your request. - **Calendar:** Event details to check availability and create/modify events. - **Messages/Email:** Claude does not read existing messages or emails, only creates new content. - **Reminders:** Existing lists and items to add/manage tasks. - **Health:** Activity, workout, vital signs, body measurements, sleep, and nutrition data — only when you ask a question that requires this information and have granted permission. Claude's connection to your iOS apps works through your device's built-in sharing and permission systems—the same secure methods you use with any iPhone app. ## Do I need to grant permission to Claude for iOS? Permission requirements vary by feature: - **Messages and Email:** No permissions required (uses your device’s built-in sharing system). - **Calendar Events:** Permission required for reading calendar; writing can use system UI without permission. - **Location and Maps:** Permission required when Claude needs to access your location. - **Reminders:** Prompted when Claude needs to access reminder lists. - **Health:** Permission required. Claude will request access to specific health data categories when needed. For features requiring permissions (like location or calendar access), Claude will request permission contextually with clear explanations of why the access is needed. You’ll be prompted to approve the action with three options: Allow once, Always allow, or Don't allow. These permissions can be managed at any time in your device settings by going to Settings \> Claude. You'll see all available permissions like Location, Calendar, and Reminders and can tap on each permission to adjust access levels. You can toggle between "While Using App” and “Ask next time” to change Claude’s access, or remove permissions by choosing “Never.” Health permissions work differently from other app permissions. When Claude requests health access, you'll see the standard iOS Health permissions screen where you can choose exactly which data types to share. You can modify these permissions at any time by going to Settings \> Health \> Data Access & Devices \> Claude. Claude will only request permissions if needed for specific features, and you can always choose to decline while still using other capabilities. ------------------------------------------------------------------------ ## Troubleshooting ### Claude isn't offering to use my apps - Make sure you're using the latest version of the Claude iOS app. For instructions, see **[How to update Claude for iOS](https://support.claude.com/en/articles/11825384-).** - Try being more specific in your request (refer to the examples listed above). - Restart Claude for iOS and try again. ### Permission prompts don't appear - Check that the app for which Claude needs permissions is installed and set up on your phone. - Verify iOS system permissions by navigating to Settings \> Privacy & Security. - Ensure Claude for iOS has the necessary permissions enabled. ### Features aren't working as expected - Your iOS mobile apps may format content slightly differently than Claude. - You can always edit the content in the destination app before sending or saving. - Some features may vary based on your iOS version. ### Calendar events aren't opening correctly - Verify you have a calendar app installed. - Check that your preferred calendar app is set as the default for calendar events. - Make sure the calendar app you’re trying to use is up to date. ### Health data isn't appearing or seems incomplete - Verify that you have a Pro or Max plan and are located in the US. - Check that you've granted Claude access to the relevant health data types in Settings \> Health \> Data Access & Devices \> Claude. - Ensure your health data is being recorded. Some data types require an Apple Watch or compatible device. - If you recently started tracking a metric, there may not be enough historical data for trend analysis. - Try asking about a specific data type to confirm which categories Claude can access. **Need more help?** If you're experiencing issues with these features, try restarting Claude for iOS or **[updating to the latest version from the App Store](https://support.claude.com/en/articles/11825384-)**. --- ## Use dictation on Claude Mobile | Claude Help Center Source: https://support.claude.com/en/articles/10065434-using-dictation-on-claude-mobile Path: 16-Mobile-Desktop/using-dictation-on-claude-mobile.md # Use dictation on Claude Mobile July 23, 2026 Dictation is available to all Claude users (Free, Pro, Max, Team, and Enterprise plans). Support for languages other than English is in beta. Dictation allows you to speak your prompts instead of typing them when using Claude for iOS or Android. **Note:** Dictation is different from voice mode. Dictation turns your speech into text so you can send a written prompt, and Claude replies in text. Voice mode is a full spoken conversation—you talk to Claude and Claude talks back, and it can use your connected tools. Learn more about **[voice mode](../15-Claude-AI-Features/use-voice-mode.md)**. ## Get started with dictation 1. Open Claude for iOS or Android. 2. Start a new chat with Claude. 3. Tap the microphone icon on the right side of the chat input field. - If this is your first time using dictation, you'll need to select your preferred language. You can change this later in Settings. 4. Dictate your prompt. 5. Tap the arrow icon to send your prompt. - To cancel without sending, tap the "X" icon. Your prompt will automatically appear as text in the chat window. Claude will respond to your prompt in text format. ## Supported languages Dictation is currently available in these languages: - English - French - German - Hindi - Italian - Japanese - Korean - Portuguese - Russian - Spanish - Turkish - Ukrainian ## Change your language settings To change your speech input language: 1. Tap your initials in the upper right corner. 2. Select “Speech Input Language.” 3. Choose your preferred language from the dropdown. ## Data privacy After converting your speech input to text, we will delete your audio recording. We will not retain a copy of your speech input or use it for training our generative models. Learn more about our privacy practices by visiting our **[Privacy Policy](https://www.anthropic.com/legal/privacy)** and **[Privacy Center](https://privacy.anthropic.com/en/)**. --- ## Use the Claude widget on Android | Claude Help Center Source: https://support.claude.com/en/articles/10534883-using-the-claude-widget-on-android Path: 16-Mobile-Desktop/using-the-claude-widget-on-android.md # Use the Claude widget on Android July 9, 2026 The Claude Android widget is available on Android 8.0 Oreo and above. The Claude Android widget provides quick and convenient access to core features directly from your home screen, allowing you to start new chats, capture images, and use voice dictation with a single tap. ## Add the Claude widget The Claude widget puts Claude's key features right on your home screen. To add it: 1. Touch and hold an empty area on your home screen 2. Tap "Widgets" 3. Find and tap "Claude" 4. Drag the widget to your desired location 5. Release to place it 6. Optional: Drag the edges of the widget to resize it ## Widget features The widget offers three quick-access buttons: - A primary chat button (with Claude's spark icon) to start a new conversation - A camera button for capturing and sharing images with Claude - A microphone button for voice dictation ## Use the widget ### Start a chat Tap the main chat button (with the spark icon) to instantly start a new conversation with Claude. ### Take photos Tap the camera button to start a new chat and immediately open your camera. You can capture an image and share it with Claude for analysis. ### Voice dictation Tap the microphone button to start a new chat and begin voice dictation. The first time you use this feature, you'll see a brief explanation about how automatic recording works. You may also need to grant voice permissions if you haven't already done so. **Note:** All interactions started through the widget will count toward your usage limit. --- ## What versions of Android are supported? | Claude Help Center Source: https://support.claude.com/en/articles/9612904-what-versions-of-android-are-supported Path: 16-Mobile-Desktop/what-versions-of-android-are-supported.md 4. What versions of Android are supported? # What versions of Android are supported? We currently support Android 8.0 Oreo and above. --- ## When to use desktop and web connectors | Claude Help Center Source: https://support.claude.com/en/articles/11725091-when-to-use-desktop-and-web-connectors Path: 16-Mobile-Desktop/when-to-use-desktop-and-web-connectors.md # When to use desktop and web connectors Claude can connect to your tools in two ways: through the web (remote connectors) or through the Claude Desktop app (desktop extensions). Most connectors are remote—they're the default choice and work everywhere you use Claude. ## Use a remote connector when - The tool is a cloud service you sign into (Slack, Notion, Linear, GitHub, your company's SaaS) - You want the connector available everywhere—web, mobile, Cowork, Desktop, and Claude Code - You're connecting something from the **[Connectors Directory](https://claude.ai/directory)** Remote connectors work across all Claude surfaces. Once connected, they're available everywhere without extra setup. ## Use a desktop extension when - The tool runs on your computer—local files, a database on localhost, a desktop application - The tool needs OS-level access (filesystem, clipboard, local processes) - There's no cloud version to connect to Desktop extensions run locally and are only available in Claude Desktop and Claude Code—not on web or mobile. ## Plugins work with both A plugin can bundle either remote or local MCP servers (or both). Adding a plugin that references a remote MCP makes it available everywhere. One that references a local MCP works in Cowork and Claude Code, not in chat. ## Quick guide [TABLE] ## Get started - Browse and add remote connectors: **[Settings → Connectors](https://claude.ai/settings/connectors)** or the **[Connectors Directory](https://claude.ai/directory)** - Install a desktop extension: Open Claude Desktop → Settings → Extensions - Building your own? See the **[connector building docs](https://claude.com/docs/connectors/building)** for remote connectors or the **[MCPB guide](https://claude.com/docs/connectors/building/mcpb)** for local ones. --- ## Why can’t I find Claude for Android in the Play Store? | Claude Help Center Source: https://support.claude.com/en/articles/9612901-why-can-t-i-find-claude-for-android-in-the-play-store Path: 16-Mobile-Desktop/why-can-t-i-find-claude-for-android-in-the-play-store.md 4. Why can’t I find Claude for Android in the Play Store? # Why can’t I find Claude for Android in the Play Store? If you’re unable to locate the Claude app in your Play Store, you may be located in an [unsupported region](https://support.anthropic.com/en/articles/8461763-where-can-i-access-claude-ai), using an unsupported device, or using an unsupported version of Android.