Documentation 2025-11-21 00:04 UTC to 2025-11-24 21:01 UTC

1# Claude Code on desktop

2 

3> Run Claude Code tasks locally or on secure cloud infrastructure with the Claude desktop app

4 

5<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" />

6 

7## Claude Code on desktop (Preview)

8 

9The 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.

10 

11## Features

12 

13Claude Code on desktop provides:

14 

15* **Parallel local sessions with `git` worktrees**: Run multiple Claude Code sessions simultaneously in the same repository, each with its own isolated `git` worktree

16* **Include `.gitignored` files in your worktrees**: Automatically copy gitignored files like `.env` to new worktrees using `.worktreeinclude`

17* **Launch Claude Code on the web**: Kick off secure cloud sessions directly from the desktop app

18 

19## Installation

20 

21Download and install the Claude Desktop app from [claude.ai/download](https://claude.ai/download)

22 

23<Note>

24 Local sessions are not available on Windows arm64 architectures.

25</Note>

26 

27## Using Git worktrees

28 

29Claude 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.

30 

31<Note>

32 If you start a local session in a folder that does not have Git initialized, the desktop app will not create a new worktree.

33</Note>

34 

35### Copying files ignored with `.gitignore`

36 

37When 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.

38 

39Create a `.worktreeinclude` file in your repository root:

40 

41```

42.env

43.env.local

44.env.*

45**/.claude/settings.local.json

46```

47 

48The 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.

49 

50<Tip>

51 Only files that are both matched by `.worktreeinclude` AND listed in `.gitignore` are copied. This prevents accidentally duplicating tracked files.

52</Tip>

53 

54### Launch Claude Code on the web

55 

56From the desktop app, you can kick off Claude Code sessions that run on Anthropic's secure cloud infrastructure. This is useful for:

57 

58To start a web session from desktop, select a remote environment when creating a new session.

59 

60For more details, see [Claude Code on the web](/en/claude-code-on-the-web).

61 

62## Bundled Claude Code version

63 

64Claude 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.

65 

66<Note>

67 The bundled Claude Code version in Desktop may differ from the latest CLI version. Desktop prioritizes stability while the CLI may have newer features.

68</Note>

69 

70## Related resources

71 

72* [Claude Code on the web](/en/claude-code-on-the-web)

73* [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop)

74* [Common workflows](/en/common-workflows)

75* [Settings reference](/en/settings)

11 automation workflows beyond GitHub Actions.11 automation workflows beyond GitHub Actions.

12</Note>12</Note>

13 13 

14<Info>

15 **Claude Opus 4.5 is now available.** Claude Code GitHub Actions default to Sonnet. To use Opus 4.5, configure the [model parameter](#breaking-changes-reference) to use `claude-opus-4-5-20251101`.

16</Info>

17 

14## Why use Claude Code GitHub Actions?18## Why use Claude Code GitHub Actions?

15 19 

16* **Instant PR creation**: Describe what you need, and Claude creates a complete PR with all necessary changes20* **Instant PR creation**: Describe what you need, and Claude creates a complete PR with all necessary changes

186 with:190 with:

187 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}191 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

188 prompt: "Generate a summary of yesterday's commits and open issues"192 prompt: "Generate a summary of yesterday's commits and open issues"

189 claude_args: "--model claude-opus-4-1-20250805"193 claude_args: "--model claude-opus-4-5-20251101"

190```194```

191 195 

192### Common use cases196### Common use cases

22| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |22| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

23| **`default`** | Recommended model setting, depending on your account type |23| **`default`** | Recommended model setting, depending on your account type |

24| **`sonnet`** | Uses the latest Sonnet model (currently Sonnet 4.5) for daily coding tasks |24| **`sonnet`** | Uses the latest Sonnet model (currently Sonnet 4.5) for daily coding tasks |

25| **`opus`** | Uses Opus model (currently Opus 4.1) for specialized complex reasoning tasks |25| **`opus`** | Uses Opus model (currently Opus 4.5) for specialized complex reasoning tasks |

26| **`haiku`** | Uses the fast and efficient Haiku model for simple tasks |26| **`haiku`** | Uses the fast and efficient Haiku model for simple tasks |

27| **`sonnet[1m]`** | Uses Sonnet with a [1 million token context window](https://docs.claude.com/en/docs/build-with-claude/context-windows#1m-token-context-window) window for long sessions |27| **`sonnet[1m]`** | Uses Sonnet with a [1 million token context window](https://docs.claude.com/en/docs/build-with-claude/context-windows#1m-token-context-window) window for long sessions |

28| **`opusplan`** | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution |28| **`opusplan`** | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution |

377Claude Code has access to a set of powerful tools that help it understand and modify your codebase:377Claude Code has access to a set of powerful tools that help it understand and modify your codebase:

378 378 

379| Tool | Description | Permission Required |379| Tool | Description | Permission Required |

380| :--------------- | :------------------------------------------------------------------ | :------------------ |380| :------------------ | :--------------------------------------------------------------------------------- | :------------------ |

381| **AskUserQuestion** | Asks the user multiple choice questions to gather information or clarify ambiguity | No |

381| **Bash** | Executes shell commands in your environment | Yes |382| **Bash** | Executes shell commands in your environment | Yes |

383| **BashOutput** | Retrieves output from a background bash shell | No |

382| **Edit** | Makes targeted edits to specific files | Yes |384| **Edit** | Makes targeted edits to specific files | Yes |

385| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |

383| **Glob** | Finds files based on pattern matching | No |386| **Glob** | Finds files based on pattern matching | No |

384| **Grep** | Searches for patterns in file contents | No |387| **Grep** | Searches for patterns in file contents | No |

388| **KillShell** | Kills a running background bash shell by its ID | No |

385| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |389| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |

386| **NotebookRead** | Reads and displays Jupyter notebook contents | No |

387| **Read** | Reads the contents of files | No |390| **Read** | Reads the contents of files | No |

391| **Skill** | Executes a skill within the main conversation | Yes |

388| **SlashCommand** | Runs a [custom slash command](/en/slash-commands#slashcommand-tool) | Yes |392| **SlashCommand** | Runs a [custom slash command](/en/slash-commands#slashcommand-tool) | Yes |

389| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |393| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |

390| **TodoWrite** | Creates and manages structured task lists | No |394| **TodoWrite** | Creates and manages structured task lists | No |

20| `/export [filename]` | Export the current conversation to a file or clipboard |20| `/export [filename]` | Export the current conversation to a file or clipboard |

21| `/help` | Get usage help |21| `/help` | Get usage help |

22| `/hooks` | Manage hook configurations for tool events |22| `/hooks` | Manage hook configurations for tool events |

23| `/ide` | Manage IDE integrations and show status |

23| `/init` | Initialize project with CLAUDE.md guide |24| `/init` | Initialize project with CLAUDE.md guide |

25| `/install-github-app` | Set up Claude GitHub Actions for a repository |

24| `/login` | Switch Anthropic accounts |26| `/login` | Switch Anthropic accounts |

25| `/logout` | Sign out from your Anthropic account |27| `/logout` | Sign out from your Anthropic account |

26| `/mcp` | Manage MCP server connections and OAuth authentication |28| `/mcp` | Manage MCP server connections and OAuth authentication |

28| `/model` | Select or change the AI model |30| `/model` | Select or change the AI model |

29| `/output-style [style]` | Set the output style directly or from a selection menu |31| `/output-style [style]` | Set the output style directly or from a selection menu |

30| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |32| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |

31| `/pr_comments` | View pull request comments |33| `/plugin` | Manage Claude Code plugins |

34| `/pr-comments` | View pull request comments |

32| `/privacy-settings` | View and update your privacy settings |35| `/privacy-settings` | View and update your privacy settings |

36| `/release-notes` | View release notes |

37| `/resume` | Resume a conversation |

33| `/review` | Request code review |38| `/review` | Request code review |

34| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation for safer, more autonomous execution |

35| `/rewind` | Rewind the conversation and/or code |39| `/rewind` | Rewind the conversation and/or code |

40| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation for safer, more autonomous execution |

41| `/security-review` | Complete a security review of pending changes on the current branch |

36| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |42| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |

37| `/statusline` | Set up Claude Code's status line UI |43| `/statusline` | Set up Claude Code's status line UI |

38| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |44| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |

249 249 

250Claude Code includes built-in subagents that are available out of the box:250Claude Code includes built-in subagents that are available out of the box:

251 251 

252### General-purpose subagent

253 

254The general-purpose subagent is a capable agent for complex, multi-step tasks that require both exploration and action. Unlike the Explore subagent, it can modify files and execute a wider range of operations.

255 

256**Key characteristics:**

257 

258* **Model**: Uses Sonnet for more capable reasoning

259* **Tools**: Has access to all tools

260* **Mode**: Can read and write files, execute commands, make changes

261* **Purpose**: Complex research tasks, multi-step operations, code modifications

262 

263**When Claude uses it:**

264 

265Claude delegates to the general-purpose subagent when:

266 

267* The task requires both exploration and modification

268* Complex reasoning is needed to interpret search results

269* Multiple strategies may be needed if initial searches fail

270* The task has multiple steps that depend on each other

271 

272**Example scenario:**

273 

274```

275User: Find all the places where we handle authentication and update them to use the new token format

276 

277Claude: [Invokes general-purpose subagent]

278[Agent searches for auth-related code across codebase]

279[Agent reads and analyzes multiple files]

280[Agent makes necessary edits]

281[Returns detailed writeup of changes made]

282```

283 

252### Plan subagent284### Plan subagent

253 285 

254The Plan subagent is a specialized built-in agent designed for use during plan mode. When Claude is operating in plan mode (non-execution mode), it uses the Plan subagent to conduct research and gather information about your codebase before presenting a plan.286The Plan subagent is a specialized built-in agent designed for use during plan mode. When Claude is operating in plan mode (non-execution mode), it uses the Plan subagent to conduct research and gather information about your codebase before presenting a plan.

278 The Plan subagent is only used in plan mode. In normal execution mode, Claude uses the general-purpose agent or other custom subagents you've created.310 The Plan subagent is only used in plan mode. In normal execution mode, Claude uses the general-purpose agent or other custom subagents you've created.

279</Tip>311</Tip>

280 312 

313### Explore subagent

314 

315The Explore subagent is a fast, lightweight agent optimized for searching and analyzing codebases. It operates in strict read-only mode and is designed for rapid file discovery and code exploration.

316 

317**Key characteristics:**

318 

319* **Model**: Uses Haiku for fast, low-latency searches

320* **Mode**: Strictly read-only - cannot create, modify, or delete files

321* **Tools available**:

322 * Glob - File pattern matching

323 * Grep - Content searching with regex

324 * Read - Reading file contents

325 * Bash - Read-only commands only (ls, git status, git log, git diff, find, cat, head, tail)

326 

327**When Claude uses it:**

328 

329Claude will delegate to the Explore subagent when it needs to search or understand a codebase but doesn't need to make changes. This is more efficient than the main agent running multiple search commands directly, as content found during the exploration process doesn't bloat the main conversation.

330 

331**Thoroughness levels:**

332 

333When invoking the Explore subagent, Claude specifies a thoroughness level:

334 

335* **Quick** - Basic searches, fastest results. Good for simple lookups.

336* **Medium** - Moderate exploration. Balances speed and thoroughness.

337* **Very thorough** - Comprehensive analysis across multiple locations and naming conventions. Used when the target might be in unexpected places.

338 

339**Example scenarios:**

340 

341```

342User: Where are errors from the client handled?

343 

344Claude: [Invokes Explore subagent with "medium" thoroughness]

345[Explore uses Grep to search for error handling patterns]

346[Explore uses Read to examine promising files]

347[Returns findings with absolute file paths]

348Claude: Client errors are handled in src/services/process.ts:712...

349```

350 

351```

352User: What's the codebase structure?

353 

354Claude: [Invokes Explore subagent with "quick" thoroughness]

355[Explore uses Glob and ls to map directory structure]

356[Returns overview of key directories and their purposes]

357```

358 

281## Example subagents359## Example subagents

282 360 

283### Code reviewer361### Code reviewer