6 6
7> Run Claude Code tasks locally or on secure cloud infrastructure with the Claude desktop app7> Run Claude Code tasks locally or on secure cloud infrastructure with the Claude desktop app
8 8
9<img src="https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=c4e9dc9737b437d36ab253b75a1cc595" alt="Claude Code on desktop interface" data-og-width="4132" width="4132" data-og-height="2620" height="2620" data-path="images/desktop-interface.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=280&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=b1a8421a544c3e8c78679fa1a7b56190 280w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=560&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=79cf4ea0923098cc429198678ea50903 560w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=840&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=14bcbcd569d179770fe656686ffbf6bf 840w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=1100&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=b873274db1e9ff8585ba545032aa24a5 1100w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=1650&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=25553dced783c3a8c2a1134a53295f7e 1650w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=2500&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=9ad49e6468c2f87b1895093deeea7bb2 2500w" />9<Note>
10 Claude Code on desktop is currently in preview.
11</Note>
12
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.
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.
16
17<CardGroup cols={2}>
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>
10 21
11## Claude Code on desktop (Preview)22 <Card title="Coming from the CLI?" icon="terminal" href="#how-desktop-relates-to-cli">
23 See what's shared and what's different
24 </Card>
25</CardGroup>
12 26
13The Claude desktop app provides a native interface for running multiple Claude Code sessions on your local machine and seamless integration with Claude Code on the web.27The desktop app has three tabs:
14 28
15## Installation29* **Chat**: A conversational interface for general questions and tasks (like Claude.ai)
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
16 32
17Download the Claude desktop app for your platform: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).
18 34
19<CardGroup cols={2}>35## Installation and setup
36
37<Steps>
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
41 <CardGroup cols={2}>
20 <Card title="macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">42 <Card title="macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">
21 Universal build for Intel and Apple Silicon43 Universal build for Intel and Apple Silicon
22 </Card>44 </Card>
24 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code&utm_medium=docs">46 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code&utm_medium=docs">
25 For x64 processors47 For x64 processors
26 </Card>48 </Card>
27</CardGroup>49 </CardGroup>
50
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.
52
53 Linux is not currently supported.
54 </Step>
55
56 <Step title="Open the app and sign in">
57 Launch Claude from your Applications folder (macOS) or Start menu (Windows). Sign in with your Anthropic account.
58 </Step>
59
60 <Step title="Select the Code tab">
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
65## Getting started
66
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.
68
69<Steps>
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.
28 72
29For Windows ARM64, [download here](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs).73 You can also run [remote sessions](/en/claude-code-on-the-web) that continue in the cloud even if you close the app.
74 </Step>
75
76 <Step title="Start a session">
77 Type what you want Claude to do:
78
79 * "Find a TODO comment and fix it"
80 * "Add tests for the main function"
81 * "Create a CLAUDE.md with instructions for this codebase"
82
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.
84 </Step>
85
86 <Step title="Review and accept changes">
87 By default, Code is in **Ask** mode, where Claude proposes changes and waits for your approval before applying them. You'll see:
88
89 1. **A diff view** showing exactly what will change in each file
90 2. **Accept/Reject buttons** to approve or decline each change
91 3. **Real-time updates** as Claude works through your request
92
93 If you reject a change, Claude will ask how you'd like to proceed differently. Your files aren't modified until you accept.
94 </Step>
95</Steps>
96
97The sections below cover commands, permission modes, parallel sessions, and ways to extend Claude Code with custom workflows and integrations.
98
99## What you can do
100
101Claude Code can edit files, run terminal commands, and understand how your code connects. Try prompts like:
102
103* `Fix the bug in the login function`
104* `Run the tests and fix any failures`
105* `How does the authentication flow work?`
106
107You can rename, resume, and archive sessions through the sidebar.
108
109### Choose a permission mode
110
111Control how Claude works using the mode selector next to the send button:
112
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.
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.
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
117To stop Claude mid-task, click the stop button.
118
119Remote sessions only support **Code** and **Plan** modes because they continue running in the background without requiring your active participation. See [permission modes](/en/iam#permission-modes) for details on how these work internally.
120
121### Work in parallel with sessions
122
123Click **+ 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.
30 124
31<Note>125<Note>
32 Local sessions are not available on Windows ARM64.126 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.
33</Note>127</Note>
34 128
35## Features129To 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.
130
131To 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.
132
133### Run long-running tasks remotely
36 134
37Claude Code on desktop provides:135For 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.
38 136
39* **Diff view**: Review Claude's changes file by file before creating a pull request, and comment on specific lines to iterate further137Remote sessions support **Code** and **Plan** modes. See [Claude Code on the web](/en/claude-code-on-the-web) for details on configuring remote environments.
40* **Parallel local sessions with `git` worktrees**: Run multiple Claude Code sessions simultaneously in the same repository, each with its own isolated `git` worktree
41* **Include files listed in your `.gitignore` in your worktrees**: Automatically copy files in your `.gitignore`, like `.env`, to new worktrees using `.worktreeinclude`
42* **Launch Claude Code on the web**: Kick off secure cloud sessions directly from the desktop app
43 138
44## Review changes with diff view139### Review changes with diff view
45 140
46After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.141After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.
47 142
48When Claude makes changes to 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.143When 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.
49 144
50### Comment on specific lines145To 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.
51 146
52Click on 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.147## Extend Claude Code
53 148
54## Using Git worktrees149You can extend Claude Code with custom commands, automated workflows, and external integrations.
55 150
56Claude Code on desktop enables running multiple Claude Code sessions in the same repository using Git worktrees. Each session gets its own isolated worktree, allowing Claude to work on different tasks without conflicts. The default location for worktrees is `~/.claude-worktrees` but this can be configured in your settings on the Claude desktop app.151### Connect external tools
152
153For 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.
154
155Connectors 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).
156
157### Create custom skills
158
159[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.
160
161### Automate workflows with hooks
162
163[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.
164
165## Environment configuration
166
167When starting a session, you choose between **Local** (runs on your machine) or **Remote** (runs on Anthropic's cloud).
168
169**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.
170
171[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).
172
173**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.
174
175## How Desktop relates to CLI
176
177If 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).
178
179### CLI flag equivalents
180
181If 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.
182
183| CLI | Desktop equivalent |
184| ------------------------------------- | ---------------------------------------------- |
185| `--model sonnet` | **...** menu > Model (before starting session) |
186| `--resume`, `--continue` | Click a session in the sidebar |
187| `--allowedTools`, `--disallowedTools` | Not available in Desktop |
188| `--dangerously-skip-permissions` | Not available in Desktop |
189| `--print` | Not available (Desktop is interactive) |
190
191### Shared configuration
192
193Desktop and CLI read the same configuration files, so your setup carries over:
194
195* **[CLAUDE.md](/en/memory)** and **CLAUDE.local.md** files in your project are used by both
196* **[MCP servers](/en/mcp)** configured in `~/.claude.json` or `.mcp.json` work in both
197* **[Hooks](/en/hooks)** and **[skills](/en/skills)** defined in settings apply to both
198* **[Settings](/en/settings)** in `~/.claude.json` and `~/.claude/settings.json` are shared
199* **Models** (Sonnet, Opus, Haiku) are available in both (Desktop requires selecting before starting a session)
57 200
58<Note>201<Note>
59 If you start a local session in a folder that does not have Git initialized, the desktop app will not create a new worktree.202 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.
60</Note>203</Note>
61 204
62### Copying files ignored with `.gitignore`205### What's different
63 206
64When Claude Code creates a worktree, files ignored via `.gitignore` aren't automatically available. Including a `.worktreeinclude` file solves this by specifying which ignored files should be copied to new worktrees.207**Desktop adds:**
65 208
66Create a `.worktreeinclude` file in your repository root:209* Graphical interface with visual session management
210* Built-in connectors for common integrations
211* Automatic session isolation for Git repositories (each session gets its own worktree)
67 212
68```213**CLI adds:**
69.env214
70.env.local215* [Third-party API providers](/en/third-party-integrations) (Bedrock, Vertex, Foundry). If you use these, continue using CLI for those projects.
71.env.*216* [CLI flags](/en/cli-reference) for scripting (`--print`, `--resume`, `--continue`)
72**/.claude/settings.local.json217* [Programmatic usage](/en/headless) via the Agent SDK
218
219## Troubleshooting
220
221Solutions to common issues with the Claude desktop app. For CLI issues, see [CLI troubleshooting](/en/troubleshooting).
222
223### Check your version
224
225To see which version of the desktop app you're running:
226
227* **macOS**: Click **Claude** in the menu bar, then **About Claude**
228* **Windows**: Click **Help**, then **About**
229
230Click the version number to copy it to your clipboard.
231
232### "Branch doesn't exist yet" when opening in CLI
233
234Remote 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:
235
236```bash theme={null}
237git fetch origin <branch-name>
238git checkout <branch-name>
73```239```
74 240
75The file uses `.gitignore`-style patterns. When a worktree is created, files matching these patterns that are also in your `.gitignore` will be copied from your main repository to the worktree.241### "Failed to load session" error
76 242
77<Tip>243This error can occur for several reasons:
78 Only files that are both matched by `.worktreeinclude` AND listed in `.gitignore` are copied. This prevents accidentally duplicating tracked files.
79</Tip>
80 244
81### Launch Claude Code on the web245* The selected folder no longer exists or is inaccessible
246* A Git repository requires Git LFS but it's not installed (see [Git LFS errors](#git-lfs-errors))
247* File permissions prevent access to the project directory
82 248
83From the desktop app, you can kick off Claude Code sessions that run on Anthropic's secure cloud infrastructure.249Try selecting a different folder or restarting the desktop app.
84 250
85To start a web session from desktop, select a remote environment when creating a new session.251### App won't quit
86 252
87For more details, see [Claude Code on the web](/en/claude-code-on-the-web).253If the desktop app doesn't close properly:
88 254
89## Bundled Claude Code version255* **macOS**: Press Cmd+Q. If the app doesn't respond, use Force Quit (Cmd+Option+Esc, select Claude, click Force Quit).
256* **Windows**: Use Task Manager (Ctrl+Shift+Esc) to end the Claude process.
90 257
91Claude Code on desktop includes a bundled, stable version of Claude Code to ensure a consistent experience for all desktop users. The bundled version is required and downloaded on first launch even if a version of Claude Code exists on the computer. Desktop automatically manages version updates and cleans up old versions.258### Windows installation issues
92 259
93<Note>260If the installer fails silently or doesn't complete properly:
94 The bundled Claude Code version in Desktop may differ from the latest CLI version. Desktop prioritizes stability while the CLI may have newer features.
95</Note>
96 261
97## Environment configuration2621. **PATH not updated**: After installation, open a new terminal window. The PATH updates only apply to new terminal sessions.
2632. **Concurrent installation error**: If you see an error about another installation in progress but there isn't one, try running the installer as Administrator.
98 264
99For local environments, Claude Code on desktop automatically extracts your `$PATH` environment variable from your shell configuration. This allows local sessions to access development tools like `yarn`, `npm`, `node`, and other commands available in your terminal without additional setup.265### Session not finding installed tools
100 266
101### Custom environment variables267If Claude can't find tools like `npm`, `node`, or other CLI commands:
102 268
103Select "Local" environment, then to the right, select the settings button. This will open a dialog where you can update local environment variables. This is useful for setting project-specific variables or API keys that your development workflows require. Environment variable values are masked in the UI for security reasons.2691. Verify the tools work in your regular terminal
2702. Check that your shell profile (`~/.zshrc`, `~/.bashrc`) properly sets up PATH
2713. Restart the desktop app to reload environment variables
104 272
105<Note>273### MCP servers not working (Windows)
106 Environment variables must be specified as key-value pairs, in [`.env` format](https://www.dotenv.org/). For example:
107 274
108 ```275If MCP server toggles don't respond or servers fail to connect on Windows:
109 API_KEY=your_api_key
110 DEBUG=true
111 276
112 # Multiline values - wrap in quotes2771. Check that the MCP server is properly configured in your settings
113 CERT="-----BEGIN CERT-----2782. Restart the desktop app after making changes
114 MIIE...2793. Verify the MCP server process is running (check Task Manager)
115 -----END CERT-----"2804. Review the server logs for connection errors
116 ```281
117</Note>282### Git LFS errors
283
284If 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:
285
2861. Install Git LFS from [git-lfs.com](https://git-lfs.com/)
2872. Run `git lfs install` in your terminal
2883. Restart the desktop app
118 289
119## Enterprise configuration290## Enterprise configuration
120 291
122 293
123## Related resources294## Related resources
124 295
125* [Claude Code on the web](/en/claude-code-on-the-web)296* [Claude Code on the web](/en/claude-code-on-the-web): Run remote sessions that continue in the cloud
126* [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop)297* [CLI reference](/en/cli-reference): Use Claude Code in your terminal with flags and scripting
127* [Enterprise Configuration](https://support.claude.com/en/articles/12622667-enterprise-configuration)298* [Common workflows](/en/common-workflows): Tutorials for debugging, refactoring, testing, and more
128* [Common workflows](/en/common-workflows)299* [Settings reference](/en/settings): Configure Claude Code behavior with settings files
129* [Settings reference](/en/settings)300* [Claude Desktop support](https://support.claude.com/en/collections/16163169-claude-desktop): Help articles for the Chat tab and general desktop app usage
301* [Enterprise configuration](https://support.claude.com/en/articles/12622667-enterprise-configuration): Admin policies for organizational deployments
