2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.
4 4
5# Claude Code on desktop5# Use Claude Code Desktop
6 6
7> Run Claude Code tasks locally or on secure cloud infrastructure with the Claude desktop app7> Get more out of Claude Code Desktop: parallel sessions with Git isolation, visual diff review, permission modes, connectors, and enterprise configuration.
8 8
9<Note>9The Code tab in the Desktop app lets you use Claude Code through a graphical interface instead of the terminal. You get visual diff review with inline comments, permission modes that control how much Claude does on its own, parallel sessions with automatic Git isolation, and connectors that integrate tools like GitHub, Slack, and Linear. Sessions can run locally, on a remote machine over [SSH](#ssh-sessions), or in [the cloud](#run-long-running-tasks-remotely).
10 Claude Code on desktop is currently in preview.
11</Note>
12 10
13Claude Code is an AI coding assistant that works directly with your codebase. Unlike Claude.ai chat, it can read your project files, edit code, run terminal commands, and understand how different parts of your code connect. You watch changes happen in real time.11<Tip>
12 New to Desktop? Start with [Get started](/en/desktop-quickstart) to install the app and make your first edit.
13</Tip>
14 14
15You can use Claude Code through the terminal ([CLI](/en/quickstart)) or through the desktop app described here. Both provide the same core capabilities. The desktop app adds a graphical interface and visual session management.15This page covers [working with code](#work-with-code), [managing sessions](#manage-sessions), [extending Claude Code](#extend-claude-code), and [configuration](#environment-configuration). It also includes a [CLI comparison](#coming-from-the-cli) and [troubleshooting](#troubleshooting).
16 16
17<CardGroup cols={2}>17## Start a session
18 <Card title="New to Claude Code?" icon="rocket" href="#installation-and-setup">
19 Start here to install and make your first edit
20 </Card>
21 18
22 <Card title="Coming from the CLI?" icon="terminal" href="#how-desktop-relates-to-cli">19Before you send your first message, configure four things in the prompt area:
23 See what's shared and what's different
24 </Card>
25</CardGroup>
26 20
27The desktop app has three tabs:21* **Environment**: choose where Claude runs. Select **Local** for your machine, a **cloud environment** for Anthropic-hosted sessions, or an [**SSH connection**](#ssh-sessions) for a remote machine you manage. See [environment configuration](#environment-configuration).
22* **Project folder**: select the folder or repository Claude works in. For remote sessions, you can add [multiple repositories](#run-long-running-tasks-remotely).
23* **Model**: pick a [model](/en/overview#models) from the dropdown next to the send button. The model is locked once the session starts.
24* **Permission mode**: choose how much autonomy Claude has from the [mode selector](#choose-a-permission-mode). You can change this during the session.
28 25
29* **Chat**: A conversational interface for general questions and tasks (like Claude.ai)26Type your task and press **Enter** to start. Each session tracks its own context and changes independently.
30* **Cowork**: An autonomous agent that works on tasks in the background
31* **Code**: An AI coding assistant that reads and edits your project files directly
32 27
33This documentation covers the **Code** tab. For the chat interface, see the [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop).28## Work with code
34 29
35## Installation and setup30Give Claude the right context, control how much it does on its own, and review what it changed.
36 31
37<Steps>32### Use the prompt box
38 <Step title="Download the app">
39 Download Claude for your platform. You'll need an Anthropic account ([sign up at claude.ai](https://claude.ai) if you don't have one).
40 33
41 <CardGroup cols={2}>34Type 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 interrupt Claude at any point: click the stop button or type your correction and press **Enter**. Claude stops what it's doing and adjusts based on your input.
42 <Card title="macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">
43 Universal build for Intel and Apple Silicon
44 </Card>
45 35
46 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code&utm_medium=docs">36The **+** button next to the prompt box gives you access to file attachments, [skills](#use-skills), [connectors](#connect-external-tools), and [plugins](#install-plugins).
47 For x64 processors
48 </Card>
49 </CardGroup>
50 37
51 For Windows ARM64, [download here](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs). Local sessions are not available on ARM64 devices, so use remote sessions instead.38### Add files and context to prompts
52 39
53 Linux is not currently supported.40The prompt box supports two ways to bring in external context:
54 </Step>
55 41
56 <Step title="Open the app and sign in">42* **@mention files**: type `@` followed by a filename to add a file to the conversation context. Claude can then read and reference that file.
57 Launch Claude from your Applications folder (macOS) or Start menu (Windows). Sign in with your Anthropic account.43* **Attach files**: attach images, PDFs, and other files to your prompt using the attachment button, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.
58 </Step>
59 44
60 <Step title="Select the Code tab">45### Choose a permission mode
61 Click the **Code** tab in the top left. If clicking Code prompts you to sign in online, complete the sign-in and restart the app.
62 </Step>
63</Steps>
64 46
65## Getting started47Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch modes at any time using the mode selector next to the send button. Start with Ask mode to see exactly what Claude does, then move to Code or Plan as you get comfortable.
66 48
67If you already use the CLI, you can skip to [How Desktop relates to CLI](#how-desktop-relates-to-cli) for a quick overview of differences.49| Mode | Settings key | Behavior |
50| -------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
51| **Ask** | `default` | Claude asks for your approval before each file edit or command. You see a diff view and can accept or reject each change. Recommended for new users. |
52| **Code** | `acceptEdits` | Claude auto-accepts file edits but still asks before running terminal commands. Use this when you trust file changes and want faster iteration. |
53| **Plan** | `plan` | Claude analyzes your code and creates a plan without modifying files or running commands. Good for complex tasks where you want to review the approach first. |
54| **Act** | `bypassPermissions` | Claude runs without any permission prompts, equivalent to `--dangerously-skip-permissions` in the CLI. Enable in your Settings → Claude Code under "Allow bypass permissions mode". Only use this in sandboxed containers or VMs. Enterprise admins can disable this option. |
68 55
69<Steps>56The `dontAsk` permission mode is available only in the [CLI](/en/permissions#permission-modes).
70 <Step title="Choose a folder and environment">
71 Select **Local** to run Claude on your machine using your files directly. This is the best choice for getting started. Click **Select folder** and choose your project directory.
72 57
73 You can also run [remote sessions](/en/claude-code-on-the-web) that continue in the cloud even if you close the app.58<Tip title="Best practice">
74 </Step>59 Start complex tasks in Plan mode so Claude maps out an approach before making changes. Once you approve the plan, switch to Code or Ask mode to execute it. See [explore first, then plan, then code](/en/best-practices#explore-first-then-plan-then-code) for more on this workflow.
60</Tip>
75 61
76 <Step title="Start a session">62Remote sessions support Code mode and Plan mode. Ask mode is not available because remote sessions auto-accept file edits by default, and Act mode is not available because the remote environment is already sandboxed.
77 Type what you want Claude to do:
78 63
79 * "Find a TODO comment and fix it"64Enterprise admins can restrict which permission modes are available. See [enterprise configuration](#enterprise-configuration) for details.
80 * "Add tests for the main function"
81 * "Create a CLAUDE.md with instructions for this codebase"
82 65
83 A **session** is a conversation with Claude about your code. Each session tracks its own context and changes, so you can work on multiple tasks without them interfering with each other.66### Review changes with diff view
84 </Step>
85 67
86 <Step title="Review and accept changes">68After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.
87 By default, Code is in **Ask** mode, where Claude proposes changes and waits for your approval before applying them. You'll see:
88 69
89 1. **A diff view** showing exactly what will change in each file70When Claude changes files, a diff stats indicator appears showing the number of lines added and removed, such as `+12 -1`. Click this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right.
90 2. **Accept/Reject buttons** to approve or decline each change
91 3. **Real-time updates** as Claude works through your request
92 71
93 If you reject a change, Claude will ask how you'd like to proceed differently. Your files aren't modified until you accept.72To 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:
94 </Step>
95</Steps>
96 73
97The sections below cover commands, permission modes, parallel sessions, and ways to extend Claude Code with custom workflows and integrations.74* **macOS**: press **Cmd+Enter**
75* **Windows**: press **Ctrl+Enter**
98 76
99## What you can do77Claude reads your comments and makes the requested changes, which appear as a new diff you can review.
100 78
101Claude Code can edit files, run terminal commands, and understand how your code connects. Try prompts like:79## Manage sessions
102 80
103* `Fix the bug in the login function`81Each session is an independent conversation with its own context and changes. You can run multiple sessions in parallel or send work to the cloud.
104* `Run the tests and fix any failures`
105* `How does the authentication flow work?`
106 82
107You can rename, resume, and archive sessions through the sidebar.83### Work in parallel with sessions
108 84
109### Choose a permission mode85Click **+ New session** in the sidebar to work on multiple tasks in parallel. For Git repositories, each session gets its own isolated copy of your project using [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), so changes in one session don't affect other sessions until you commit them.
110 86
111Control how Claude works using the mode selector next to the send button:87Worktrees are stored in `<project-root>/.claude/worktrees/` by default. You can change this to a custom directory in Settings → Claude Code under "Worktree location". You can also set a branch prefix that gets prepended to every worktree branch name, which is useful for keeping Claude-created branches organized. To remove a worktree when you're done, hover over the session in the sidebar and click the archive icon.
112 88
113* **Ask** (recommended for new users): Claude asks for your approval before each file edit or command. You see a diff view and can accept or reject each change.89<Note>
114* **Code**: Claude auto-accepts file edits but still asks before running terminal commands. Use this when you trust file changes and want faster iteration.90 Session isolation requires [Git](https://git-scm.com/downloads). Most Macs include Git by default. Run `git --version` in Terminal to check. On Windows, [download Git](https://git-scm.com/downloads) if you don't have it.
115* **Plan**: Claude creates a detailed plan for your approval before making any changes. Good for complex tasks where you want to review the approach first.
116* **Act**: Claude runs without permission checks, automatically executing file edits and terminal commands. Only use this mode in trusted environments.
117 91
118<Warning title="Act mode">92 Without Git, sessions share the same files and changes in one session are immediately visible in others.
119 Act runs in `bypassPermissions` mode, which disables all permission checks and should only be used in isolated environments like containers or VMs where Claude Code cannot cause damage. This mode is disabled by default. For personal accounts, enable it in [Claude Code personal settings](https://claude.ai/settings/claude-code). For Team and Enterprise plans, admins must enable it in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code). Act mode does not persist across sessions.93</Note>
120</Warning>
121 94
122To stop Claude mid-task, click the stop button.95Use the filter icon at the top of the sidebar to filter sessions by status (Active, Archived) and environment (Local, Cloud). To rename a session or check context usage, click the session title in the toolbar at the top of the active session. When context fills up, Claude automatically summarizes the conversation and continues working. You can also type "compact this conversation" to trigger summarization earlier and free up context space. See [the context window](/en/how-claude-code-works#the-context-window) for details on how compaction works.
123 96
124Remote sessions only support **Code** and **Plan** modes because they continue running in the background without requiring your active participation. See [permission modes](/en/permissions#permission-modes) for details on how these work internally.97### Run long-running tasks remotely
125 98
126### Work in parallel with sessions99For large refactors, test suites, migrations, or other long-running tasks, select **Remote** instead of **Local** when starting a session. Remote sessions run on Anthropic's cloud infrastructure 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 remote sessions from [claude.ai/code](https://claude.ai/code) or the Claude iOS app.
127 100
128Click **+ New session** in the sidebar to work on multiple tasks in parallel. For Git repositories, each session gets its own isolated copy of your project using worktrees, so changes in one session don't affect another until you commit them. Worktrees are stored in `~/.claude-worktrees/` by default.101Remote sessions also support multiple repositories. After selecting a cloud environment, click the **+** button next to the repo pill to add additional repositories to the session. Each repo gets its own branch selector. This is useful for tasks that span multiple codebases, such as updating a shared library and its consumers.
129 102
130<Note>103See [Claude Code on the web](/en/claude-code-on-the-web) for more on how remote sessions work.
131 Session isolation requires [Git](https://git-scm.com/downloads). Without Git, sessions in the same directory edit the same files, so changes in one session are immediately visible in others.
132</Note>
133 104
134To include files listed in your `.gitignore` (like `.env`) in new worktrees, create a `.worktreeinclude` file in your project root listing the file patterns to copy.105### Continue in another surface
135 106
136To manage a session, click its dropdown in the sidebar to rename it, archive it, or check context usage. When context fills up, Claude automatically summarizes the conversation. You can also ask Claude to compact if you want to free up space earlier.107The **Continue in** menu, accessible from the VS Code icon in the bottom right of the session toolbar, lets you move your session to another surface:
137 108
138### Run long-running tasks remotely109* **Claude Code on the Web**: sends your local session to continue running remotely. Desktop pushes your branch, generates a summary of the conversation, and creates a new remote session with the full context. You can then choose to archive the local session or keep it. This requires a clean working tree, and is not available for SSH sessions.
110* **Your IDE**: opens your project in a supported IDE at the current working directory.
139 111
140For large refactors, test suites, migrations, or other long-running tasks, select **Remote** instead of **Local** when starting a session. Remote sessions run on Anthropic's cloud infrastructure 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.112## Extend Claude Code
141 113
142Remote sessions support **Code** and **Plan** modes. See [Claude Code on the web](/en/claude-code-on-the-web) for details on configuring remote environments.114Connect external services, add reusable workflows, and customize Claude's behavior for your project.
143 115
144### Review changes with diff view116### Connect external tools
145 117
146After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.118For local and [SSH](#ssh-sessions) sessions, click the **+** button next to the prompt box and select **Connectors** to add integrations like Google Calendar, Slack, GitHub, Linear, Notion, and more. You can add connectors before or during a session. Connectors are not available for remote sessions.
147 119
148When Claude changes files, a diff stats indicator appears showing the number of lines added and removed (for example, `+12 -1`). Click this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right.120To manage or disconnect connectors, go to Settings → Connectors in the desktop app, or select **Manage connectors** from the Connectors menu in the prompt box.
149 121
150To comment on specific lines, click any line in the diff to open a comment box. Type your feedback and press **Enter** to send. In the full diff view, press **Enter** to accept each comment, then **Cmd+Enter** to send them all. Claude reads your comments and makes the requested changes, which appear as a new diff you can review.122Once 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.
151 123
152## Extend Claude Code124Connectors are [MCP servers](/en/mcp) with a graphical setup flow. Use them for quick integration with supported services. For integrations not listed in Connectors, add MCP servers manually via [settings files](/en/mcp#installing-mcp-servers). You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).
153 125
154You can extend Claude Code with custom commands, automated workflows, and external integrations.126### Use skills
155 127
156### Connect external tools128[Skills](/en/skills) 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](/en/interactive-mode#built-in-commands), your [custom skills](/en/skills#create-custom-skills), project skills from your codebase, and skills from any [installed plugins](/en/plugins). Select one and it appears highlighted in the input field. Type your task after it and send as usual.
157 129
158For local sessions, click the **...** button before starting and select **Connectors** to add integrations like Google Calendar, Slack, GitHub, Linear, Notion, and more. Connectors must be configured before the session starts and are only available for local sessions. 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.130### Install plugins
159 131
160Connectors are [MCP (Model Context Protocol) servers](/en/mcp) with built-in setup. You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) or add MCP servers manually via [configuration files](/en/mcp#configure-mcp-servers).132[Plugins](/en/plugins) 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.
161 133
162### Create custom skills134For local and [SSH](#ssh-sessions) sessions, click the **+** button next to the prompt box and select **Plugins** to see your installed plugins and their commands. To add a plugin, select **Add plugin** from the submenu to open the plugin browser, which shows available plugins from your configured [marketplaces](/en/plugin-marketplaces) including the official Anthropic marketplace. Select **Manage plugins** to enable, disable, or uninstall plugins.
163 135
164[Skills](/en/skills) are reusable prompts that extend Claude's capabilities. For example, you could create a `review` skill that runs your standard code review checklist, or a `deploy` skill that walks through your deployment steps. Skills are defined as markdown files in `.claude/skills/` and can include instructions, context, and even call other tools. Ask Claude what skills are available or to run a specific skill. Claude can also help you create a skill if you describe what you want, or see [skills](/en/skills) to learn how to write them yourself.136Plugins can be scoped to your user account, a specific project, or local-only. Plugins are not available for remote sessions. For the full plugin reference including creating your own plugins, see [plugins](/en/plugins).
165 137
166### Automate workflows with hooks138## Environment configuration
167 139
168[Hooks](/en/hooks) run shell commands automatically in response to Claude Code events. For example, you could run a linter after every file edit, auto-format code, or send notifications when tasks complete. Hooks are configured in your [settings files](/en/settings). See [hooks](/en/hooks) for available events and configuration examples.140When starting a session, you choose between three environments:
169 141
170## Environment configuration142* **Local**: runs on your machine with direct access to your files
143* **Remote**: runs on Anthropic's cloud infrastructure. Sessions continue even if you close the app.
144* **SSH**: runs on a remote machine you connect to over SSH, such as your own servers, cloud VMs, or dev containers
145
146### Local sessions
147
148Local sessions inherit environment variables from your shell. If you need additional variables, set them in your shell profile, such as `~/.zshrc` or `~/.bashrc`, and restart the desktop app. See [environment variables](/en/settings#environment-variables) for the full list of supported variables.
149
150[Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To disable it or adjust the budget, set `MAX_THINKING_TOKENS` in your shell profile. Use `0` to disable.
151
152### Remote sessions
153
154Remote sessions continue in the background even if you close the app. Usage counts toward your [subscription plan limits](/en/costs) with no separate compute charges.
155
156You can create custom cloud environments with different network access levels and environment variables. Select the environment dropdown when starting a remote session and choose **Add environment**. See [cloud environments](/en/claude-code-on-the-web#cloud-environments) for details on configuring network access and environment variables.
157
158### SSH sessions
159
160SSH 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.
161
162To add an SSH connection, click the environment dropdown before starting a session and select **+ Add SSH connection**. The dialog asks for:
163
164* **Name**: a friendly label for this connection
165* **SSH Host**: `user@hostname` or a host defined in `~/.ssh/config`
166* **SSH Port**: defaults to 22 if left empty, or uses the port from your SSH config
167* **Identity File**: path to your private key, such as `~/.ssh/id_rsa`. Leave empty to use the default key or your SSH config.
168
169Once added, the connection appears in the environment dropdown. Select it to start a session on that machine. Claude runs on the remote machine with access to its files and tools.
170
171SSH sessions support permission modes, connectors, plugins, and MCP servers. Claude Code must be installed on the remote machine.
172
173## Enterprise configuration
174
175Organizations on Teams or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies.
171 176
172When starting a session, you choose between **Local** (runs on your machine) or **Remote** (runs on Anthropic's cloud).177### Admin console controls
173 178
174**Local sessions** inherit environment variables from your shell. If you need additional variables, set them in your shell profile (`~/.zshrc`, `~/.bashrc`) and restart the desktop app. See [environment variables](/en/settings#environment-variables) for the full list of supported variables.179These settings are configured through the [admin settings console](https://claude.ai/admin-settings/claude-code):
175 180
176[Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. The thinking process runs in the background but isn't displayed in the Desktop interface. To disable it or adjust the budget, set `MAX_THINKING_TOKENS` in your shell profile (use `0` to disable).181* **Enable or disable the Code tab**: control whether users in your organization can access Claude Code in the desktop app
182* **Disable Act mode**: prevent users in your organization from enabling bypass permissions mode
183* **Disable Claude Code on the web**: enable or disable remote sessions for your organization
177 184
178**Remote sessions** run on Anthropic's cloud infrastructure and continue even if you close the app. Usage counts toward your subscription plan limits with no separate compute charges. See [Claude Code on the web](/en/claude-code-on-the-web) for details on configuring remote environments.185### Managed settings
179 186
180## How Desktop relates to CLI187Managed settings override project and user settings and apply when Desktop spawns CLI sessions. You can set these keys in your organization's [managed settings](/en/settings#settings-precedence) file or push them remotely through the admin console.
181 188
182If 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 maintains separate session history, but they share configuration and project memory (CLAUDE.md files).189| Key | Description |
190| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
191| `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Act mode. See [permissions](/en/permissions#managed-settings). |
192
193Remote managed settings uploaded through the admin console currently apply to CLI and IDE sessions only. For Desktop-specific restrictions, use the admin console controls above.
194
195### Device management policies
196
197IT teams can manage the desktop app through MDM on macOS or group policy on Windows. Available policies include enabling or disabling the Claude Code feature, controlling auto-updates, and setting a custom deployment URL.
198
199* **macOS**: configure via `com.anthropic.Claude` preference domain using tools like Jamf or Kandji
200* **Windows**: configure via registry at `SOFTWARE\Policies\Claude`
201
202### Authentication and SSO
203
204Enterprise organizations can require SSO for all users. See [authentication](/en/authentication) for plan-level details and [Setting up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso) for SAML and OIDC configuration.
205
206### Data handling
207
208Claude Code processes your code locally in local sessions or on Anthropic's cloud infrastructure in remote sessions. Conversations and code context are sent to Anthropic's API for processing. See [data handling](/en/data-usage) for details on data retention, privacy, and compliance.
209
210### Deployment
211
212Desktop can be distributed through enterprise deployment tools:
213
214* **macOS**: distribute via MDM such as Jamf or Kandji using the `.dmg` installer
215* **Windows**: deploy via MSIX package or `.exe` installer. See [Deploy Claude Desktop for Windows](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows) for enterprise deployment options including silent installation
216
217For network configuration such as proxy settings, firewall allowlisting, and LLM gateways, see [network configuration](/en/network-config).
218
219For the full enterprise configuration reference, see the [enterprise configuration guide](https://support.claude.com/en/articles/12622667-enterprise-configuration).
220
221## Coming from the CLI?
222
223If 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 maintains separate session history, but they share configuration and project memory via CLAUDE.md files.
224
225To 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 Windows only.
226
227<Tip>
228 When to use Desktop vs CLI: use Desktop when you want visual diff review, file attachments, or session management in a sidebar. Use the CLI when you need scripting, automation, third-party providers, or prefer a terminal workflow.
229</Tip>
183 230
184### CLI flag equivalents231### CLI flag equivalents
185 232
186If you're used to CLI flags, the table below shows the Desktop equivalent for each. Some flags have no Desktop equivalent because they're designed for scripting or automation.233This 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.
187 234
188| CLI | Desktop equivalent |235| CLI | Desktop equivalent |
189| ------------------------------------- | ---------------------------------------------- |236| ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
190| `--model sonnet` | **...** menu > Model (before starting session) |237| `--model sonnet` | model dropdown next to the send button, before starting a session |
191| `--resume`, `--continue` | Click a session in the sidebar |238| `--resume`, `--continue` | click a session in the sidebar |
192| `--allowedTools`, `--disallowedTools` | Not available in Desktop |239| `--permission-mode` | mode selector next to the send button |
193| `--dangerously-skip-permissions` | Not available in Desktop |240| `--dangerously-skip-permissions` | Settings → Claude Code → "Allow bypass permissions mode". Enterprise admins can disable this setting. |
194| `--print` | Not available (Desktop is interactive) |241| `--add-dir` | add multiple repos with the **+** button in remote sessions |
242| `--allowedTools`, `--disallowedTools` | not available in Desktop |
243| `--verbose` | not available. Check system logs: Console.app on macOS, Event Viewer → Application on Windows |
244| `--print`, `--output-format` | not available. Desktop is interactive only. |
245| `ANTHROPIC_MODEL` env var | model dropdown next to the send button |
246| `MAX_THINKING_TOKENS` env var | set in shell profile; applies to local sessions. See [environment configuration](#environment-configuration). |
195 247
196### Shared configuration248### Shared configuration
197 249
200* **[CLAUDE.md](/en/memory)** and **CLAUDE.local.md** files in your project are used by both252* **[CLAUDE.md](/en/memory)** and **CLAUDE.local.md** files in your project are used by both
201* **[MCP servers](/en/mcp)** configured in `~/.claude.json` or `.mcp.json` work in both253* **[MCP servers](/en/mcp)** configured in `~/.claude.json` or `.mcp.json` work in both
202* **[Hooks](/en/hooks)** and **[skills](/en/skills)** defined in settings apply to both254* **[Hooks](/en/hooks)** and **[skills](/en/skills)** defined in settings apply to both
203* **[Settings](/en/settings)** in `~/.claude.json` and `~/.claude/settings.json` are shared255* **[Settings](/en/settings)** in `~/.claude.json` and `~/.claude/settings.json` are shared. Permission rules, allowed tools, and other settings in `settings.json` apply to Desktop sessions.
204* **Models** (Sonnet, Opus, Haiku) are available in both (Desktop requires selecting before starting a session)256* **Models**: Sonnet, Opus, and Haiku are available in both. In Desktop, select the model from the dropdown next to the send button before starting a session. You cannot change the model during an active session.
205 257
206<Note>258<Note>
207 MCP servers configured for the **Claude Desktop chat app** (in `claude_desktop_config.json`) are separate from Claude Code. To use MCP servers in Claude Code, configure them in `~/.claude.json` or your project's `.mcp.json` file. See [MCP configuration](/en/mcp#configure-mcp-servers) for details.259 **MCP servers: desktop chat app vs Claude Code**: MCP servers configured for the Claude Desktop chat app in `claude_desktop_config.json` are separate from Claude Code and will not appear in the Code tab. To use MCP servers in Claude Code, configure them in `~/.claude.json` or your project's `.mcp.json` file. See [MCP configuration](/en/mcp#installing-mcp-servers) for details.
208</Note>260</Note>
209 261
210### What's different262### Feature comparison
211 263
212**Desktop adds:**264This table compares core capabilities between the CLI and Desktop. For a full list of CLI flags, see the [CLI reference](/en/cli-reference).
213 265
214* Graphical interface with visual session management266| Feature | CLI | Desktop |
215* Built-in connectors for common integrations267| ----------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
216* Automatic session isolation for Git repositories (each session gets its own worktree)268| Permission modes | all modes including `dontAsk` | Ask, Code, Plan, and Act via Settings |
269| `--dangerously-skip-permissions` | CLI flag | Settings → Claude Code → "Allow bypass permissions mode" |
270| [Third-party providers](/en/third-party-integrations) | Bedrock, Vertex, Foundry | not available. Desktop connects to Anthropic's API directly. |
271| [MCP servers](/en/mcp) | configure in settings files | Connectors UI for local and SSH sessions, or settings files |
272| [Plugins](/en/plugins) | `/plugin` command | plugin manager UI |
273| @mention files | text-based | with autocomplete |
274| File attachments | not available | images, PDFs |
275| Session isolation | [`--worktree`](/en/cli-reference) flag | automatic worktrees |
276| Multiple sessions | separate terminals | sidebar tabs |
277| Scripting and automation | [`--print`](/en/cli-reference), [Agent SDK](/en/headless) | not available |
217 278
218**CLI adds:**279### What's not available in Desktop
219 280
220* [Third-party API providers](/en/third-party-integrations) (Bedrock, Vertex, Foundry). If you use these, continue using CLI for those projects.281* **Third-party providers**: Desktop connects to Anthropic's API directly. Use the [CLI](/en/quickstart) with Bedrock, Vertex, or Foundry instead.
221* [CLI flags](/en/cli-reference) for scripting (`--print`, `--resume`, `--continue`)282* **Linux**: the desktop app is available on macOS and Windows only.
222* [Programmatic usage](/en/headless) via the Agent SDK283* **Inline code suggestions**: Desktop does not provide autocomplete-style suggestions. It works through conversational prompts and explicit code changes.
284* **Agent teams**: multi-agent orchestration is available via the [CLI](/en/agent-teams) and [Agent SDK](/en/headless), not in Desktop.
223 285
224## Troubleshooting286## Troubleshooting
225 287
226Solutions to common issues with the Claude desktop app. For CLI issues, see [CLI troubleshooting](/en/troubleshooting).
227
228### Check your version288### Check your version
229 289
230To see which version of the desktop app you're running:290To see which version of the desktop app you're running:
231 291
232* **macOS**: Click **Claude** in the menu bar, then **About Claude**292* **macOS**: click **Claude** in the menu bar, then **About Claude**
233* **Windows**: Click **Help**, then **About**293* **Windows**: click **Help**, then **About**
234 294
235Click the version number to copy it to your clipboard.295Click the version number to copy it to your clipboard.
236 296
237### "Branch doesn't exist yet" when opening in CLI297### 403 or authentication errors in the Code tab
238 298
239Remote sessions can create branches that don't exist on your local machine. Click the branch name in the session toolbar to copy it, then fetch it locally:299If you see `Error 403: Forbidden` or other authentication failures when using the Code tab:
240 300
241```bash theme={null}3011. Sign out and back in from the app menu. This is the most common fix.
242git fetch origin <branch-name>3022. Verify you have an active paid subscription: Pro, Max, Teams, or Enterprise.
243git checkout <branch-name>3033. If the CLI works but Desktop does not, quit the desktop app completely, not just close the window, then reopen and sign in again.
244```3044. Check your internet connection and proxy settings.
245 305
246### "Failed to load session" error306### Blank or stuck screen on launch
247 307
248This error can occur for several reasons:308If the app opens but shows a blank or unresponsive screen:
249 309
250* The selected folder no longer exists or is inaccessible3101. Restart the app.
251* A Git repository requires Git LFS but it's not installed (see [Git LFS errors](#git-lfs-errors))3112. Check for pending updates. The app auto-updates on launch.
252* File permissions prevent access to the project directory3123. On Windows, check Event Viewer for crash logs under **Windows Logs → Application**.
253 313
254Try selecting a different folder or restarting the desktop app.314### "Failed to load session"
255 315
256### App won't quit316If 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.
257 317
258If the desktop app doesn't close properly:318### Session not finding installed tools
259 319
260* **macOS**: Press Cmd+Q. If the app doesn't respond, use Force Quit (Cmd+Option+Esc, select Claude, click Force Quit).320If 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.
261* **Windows**: Use Task Manager (Ctrl+Shift+Esc) to end the Claude process.
262 321
263### Windows installation issues322### Git and Git LFS errors
264 323
265If the installer fails silently or doesn't complete properly:324Git is required for session isolation and worktrees. If you see "Git is required," install Git from [git-scm.com](https://git-scm.com/downloads) and restart the app.
266 325
2671. **PATH not updated**: After installation, open a new terminal window. The PATH updates only apply to new terminal sessions.326If 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.
2682. **Concurrent installation error**: If you see an error about another installation in progress but there isn't one, try running the installer as Administrator.
269 327
270### Session not finding installed tools328### MCP servers not working on Windows
271 329
272If Claude can't find tools like `npm`, `node`, or other CLI commands:330If 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.
273 331
2741. Verify the tools work in your regular terminal332### App won't quit
2752. Check that your shell profile (`~/.zshrc`, `~/.bashrc`) properly sets up PATH
2763. Restart the desktop app to reload environment variables
277 333
278### MCP servers not working (Windows)334* **macOS**: press Cmd+Q. If the app doesn't respond, use Force Quit with Cmd+Option+Esc, select Claude, and click Force Quit.
335* **Windows**: use Task Manager with Ctrl+Shift+Esc to end the Claude process.
279 336
280If MCP server toggles don't respond or servers fail to connect on Windows:337### Windows-specific issues
281 338
2821. Check that the MCP server is properly configured in your settings339* **PATH not updated after install**: open a new terminal window. PATH updates only apply to new terminal sessions.
2832. Restart the desktop app after making changes340* **Concurrent installation error**: if you see an error about another installation in progress but there isn't one, try running the installer as Administrator.
2843. Verify the MCP server process is running (check Task Manager)341* **ARM64 limitations**: Windows ARM64 devices can run the desktop app but do not support local sessions. Use **Remote** sessions instead.
2854. Review the server logs for connection errors
286 342
287### Git LFS errors343### Cowork tab unavailable on Intel Macs
288 344
289If you see "Git LFS is required by this repository but is not installed," your repository uses Git Large File Storage for large binary files. Install Git LFS before opening this repository:345The Cowork tab requires Apple Silicon, M1 or later. The Chat and Code tabs work normally on Intel Macs.
290 346
2911. Install Git LFS from [git-lfs.com](https://git-lfs.com/)347### "Branch doesn't exist yet" when opening in CLI
2922. Run `git lfs install` in your terminal
2933. Restart the desktop app
294 348
295## Enterprise configuration349Remote sessions can create branches that don't exist on your local machine. Click the branch name in the session toolbar to copy it, then fetch it locally:
350
351```bash theme={null}
352git fetch origin <branch-name>
353git checkout <branch-name>
354```
296 355
297Organizations can disable local Claude Code use in the desktop application with the `isClaudeCodeForDesktopEnabled` [enterprise policy option](https://support.claude.com/en/articles/12622667-enterprise-configuration#h_003283c7cb). Additionally, Claude Code on the web can be disabled in your [admin settings](https://claude.ai/admin-settings/claude-code).356### Still stuck?
298 357
299## Related resources358* Search or file a bug on [GitHub Issues](https://github.com/anthropics/claude-code/issues)
359* Visit the [Claude support center](https://support.claude.com/)
300 360
301* [Claude Code on the web](/en/claude-code-on-the-web): Run remote sessions that continue in the cloud361When filing a bug, 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 → Application.
302* [CLI reference](/en/cli-reference): Use Claude Code in your terminal with flags and scripting
303* [Common workflows](/en/common-workflows): Tutorials for debugging, refactoring, testing, and more
304* [Settings reference](/en/settings): Configure Claude Code behavior with settings files
305* [Claude Desktop support](https://support.claude.com/en/collections/16163169-claude-desktop): Help articles for the Chat tab and general desktop app usage
306* [Enterprise configuration](https://support.claude.com/en/articles/12622667-enterprise-configuration): Admin policies for organizational deployments
