Claude Code Desktop is a native app for macOS and Windows. The CLI runs underneath it, but the app adds a graphical interface, session persistence across restarts, and desktop push notifications without requiring a phone.
Download from claude.ai/download.
Three tabs
Chat is conversations with Claude without a code session. Good for quick questions, prompt drafting, or anything that does not need file access.
Cowork is a shared session for pair-programming style work. The model and your cursor movements are visible in the same view. Designed for screen-sharing scenarios.
Code is the main coding interface. This is what you get when you run claude in a terminal, wrapped in a desktop app.
Session lifecycle in the Code tab
Each Code tab session starts a git worktree. Your main working tree is unchanged. The session branch is created from origin/HEAD of the repository you open.
When you close a Code tab, the session is paused (not ended). Reopen the app and the session is restored with its full conversation history and context. The worktree persists.
When you explicitly end a session (button or /exit), the worktree is cleaned up if the session produced no commits. If commits were made, the branch stays for you to merge or create a PR from.
Settings GUI
Desktop exposes a settings panel rather than requiring you to hand-edit settings.json. Changes in the GUI write to ~/.claude/settings.json.
For settings that require JSON (custom hooks, complex permission rules), you can still open the file directly. The GUI and file are in sync.
Push notifications without a phone
Desktop registers with the OS notification system. When a long task finishes or Claude needs a decision, a notification appears on your desktop even if you have switched to another app.
This is the same notification system as the mobile app. If you have both installed on the same account, notifications go to whichever is currently active.
To enable:
- Allow notifications when macOS or Windows prompts you on first launch
- In Settings, turn on Notify when Claude decides or Notify on completion
Desktop vs CLI
| Aspect | Desktop | CLI |
|---|---|---|
| Platform | macOS, Windows | macOS, Linux, Windows |
| Session persistence | App restart | --resume flag |
| Settings editing | GUI + file | File only |
| Worktree per session | Default | Opt-in (--worktree) |
| Push notifications | Desktop OS | Mobile app only |
| Tab completion | No | Yes |
! bash shortcut | No | Yes |
/mcp, /plugin | No | Yes |
The CLI still supports every command. Desktop is an alternative entry point, not a replacement.
Footguns
Linux is not supported. Claude Code Desktop only runs on macOS and Windows.
Each Code tab creates its own branch. If you open three Code tabs on the same repository, you get three branches. Merging them back is your responsibility. Do not open multiple Code tabs on the same feature unless you intend to manage the resulting branches.
Session restoration puts you back on the session branch, not main. If you created a commit on the session branch and then closed the app, reopening restores the session on that branch. This is correct behavior but surprising if you expected to see your latest main commits.
Notification permissions need to be granted per OS. On macOS, allow notifications in System Settings > Notifications > Claude Code. On Windows, it’s Settings > System > Notifications. The first-launch prompt is easy to dismiss accidentally.
When NOT to use Desktop
- You work on Linux. Use the CLI.
- You need shell integration: tab completion,
!shortcuts, piping output to other tools. These require a terminal. - You use
/mcpor/pluginto interactively configure MCP servers or install plugins. These open terminal-based pickers. - You want a minimal footprint. The Desktop app is a full native application; the CLI is a single binary.