The Claude Code desktop app is the Code tab in the Claude desktop app for macOS and Windows (Linux is in beta). It runs the same engine as the claude CLI behind a graphical interface: you pick a project folder, describe a task, and review Claude's changes in a visual diff, with parallel sessions in a sidebar and no terminal required.
This guide covers installing it, starting a session, the features that matter day to day and how it fits with the CLI. It is based on the official desktop quickstart and the full Claude Code Desktop reference.
How do you install the Claude Code desktop app?
Download the Claude desktop app for macOS (a universal build for Intel and Apple Silicon) or Windows (x64, with a separate ARM64 installer) from the quickstart page. On Linux, install with apt or a .deb package on Ubuntu and Debian, following Claude Desktop on Linux.
Then:
- Launch Claude and sign in with your Anthropic account.
- Click the Code tab at the top of the sidebar.
The Code tab requires a Pro, Max, Team or Enterprise plan. If you see a prompt to upgrade, you need a paid plan first; a 403 error usually clears after you sign out and back in.
You don't need Node.js or the CLI. The app ships its own copy of Claude Code and keeps it updated. That copy has its own version number, so it can differ from the claude in your terminal; type /status in a local Code tab session to see which version it runs.
How do you start a session in the Code tab?
A session is one conversation about your code, with its own history and project folder. Before you send the first message, set four things in the row under the prompt box:
- Environment: where Claude runs. Local works on your computer, Cloud runs on Anthropic-managed infrastructure and keeps going if you close the app, SSH connects to a remote machine, and WSL runs inside a WSL 2 distribution on Windows.
- Project folder: choose Open folder… and pick your project. Cloud sessions pick repositories instead.
- Permission mode: how much Claude can do without asking (see below).
- Model: pick from the model picker; you can change it mid-session.
Type the task and press Enter. The quickstart suggests starting with something small, such as "Find a TODO comment and fix it" or "Create a CLAUDE.md with instructions for this codebase". You can interrupt with the stop button, or type a correction and press Enter to steer Claude without stopping it.
To pull in context, type @ and a filename, or attach images, PDFs and other files from the + button or by dragging them into the prompt box. Attachments are handy for screenshots of a bug or a design mockup.
Which permission modes does the desktop app have?
The mode selector offers the same core modes as the CLI, with friendlier names:
| Desktop mode | Settings key | What it does |
|---|---|---|
| Manual | default |
Asks before editing files or running commands, showing a diff to accept or reject |
| Accept edits | acceptEdits |
Auto-accepts file edits and common filesystem commands, still asks before other commands |
| Plan | plan |
Explores and proposes a plan without editing your source code |
| Auto | auto |
Runs without routine prompts while a background classifier checks actions |
| Bypass permissions | bypassPermissions |
No permission prompts; only for sandboxed containers or VMs |
Bypass permissions is hidden until you enable it: on Pro and Max under Settings > Claude Code, and on Team and Enterprise through organization policy. The app reads the same settings files as the CLI, so permissions.defaultMode sets the default for new local sessions. A mode you pick is remembered per folder, except Plan. One difference from the terminal: Shift+Tab does not cycle modes in Desktop. Use Cmd+Shift+M (or Ctrl+Shift+M) to open the mode menu. The permissions guide explains the modes in depth.
What can you do in the desktop app?
The Code tab is built around panes you can drag, resize and pop out into their own windows: chat, diff, browser, terminal, file editor, plan, tasks and subagent panes. The features you will use most:
- Diff view with comments. Click the line count, such as
+12 -1, to review changes file by file. Click any line to leave a comment, then submit them all withCmd+Enter(Ctrl+Enteron Windows). Claude reads the comments and revises. - Code review. Enter
/code-reviewand findings arrive as a card grouped by file, with Walk through in diff and Apply fixes buttons. - App preview. Claude can start your dev server and open it in the Browser pane, then take screenshots, click elements and fill forms to check its own work. Custom dev commands go in
.claude/launch.json. - Integrated terminal. Press
Ctrl+`to open a terminal in the session's working directory that sees the same files Claude is editing. - PR monitoring. After you open a pull request, its CI status appears in the session. Turn on Auto-fix to have Claude address failing checks, or Merge when ready to turn on GitHub auto-merge. This needs the GitHub CLI installed and signed in.
- Side chats. Press
Cmd+;to ask a question that uses the session's context without derailing the main thread.
Press Cmd+/ (or Ctrl+/) to see every shortcut in the Code tab.
How do parallel sessions work?
Click + New in the sidebar, or press Cmd+N (Ctrl+N on Windows), to start another session. Ctrl+Tab cycles between them. Option-click (Alt-click on Windows) a session to open it side by side in a split view.
Two sessions editing the same folder can collide. To avoid that in a Git repository, turn on Worktree in the project folder control before starting. Each session then gets its own isolated copy under <project-root>/.claude/worktrees/ by default. A .worktreeinclude file copies gitignored files such as .env into new worktrees. See Claude Code worktrees for how this works in the CLI too.
For long jobs, start a Cloud session instead. It keeps running after you close the app or shut down your computer, and you can check on it from claude.ai/code or the Claude mobile app. You can also move a session you already started to the cloud from the session menu with Open in > Cloud. The Claude Code on the web guide covers cloud sessions.
How does the desktop app compare with the CLI?
They run the same engine and can run at the same time, even on the same project. They share configuration: CLAUDE.md, MCP servers in ~/.claude.json or .mcp.json, hooks, skills and ~/.claude/settings.json.
| Feature | CLI | Desktop |
|---|---|---|
| Permission modes | All, including dontAsk |
Manual, Accept edits, Plan, Auto, plus Bypass once enabled |
| File attachments | Not available | Images and PDFs |
| Session isolation | --worktree flag |
Worktree toggle |
| Multiple sessions | Separate terminals | Sidebar and split view |
| Computer use | macOS, via /mcp |
macOS and Windows, via Settings |
| Scripting | --print, Agent SDK |
Not available |
| Agent teams | Available | Not available |
| Third-party providers | Bedrock, Agent Platform, Foundry | Anthropic API by default; gateway and third-party setups documented separately |
To move a terminal session into the app, run /desktop. Claude saves the session, opens it in Desktop and exits the CLI. From your shell, claude --desktop --continue opens your most recent conversation in this directory (Claude Code v2.1.285 or later). Both need a Claude subscription sign-in on macOS or x64 Windows, and don't work with API key authentication or cloud providers. You can also close the terminal session and type /resume in a local Desktop session to pick it up with its full context.
The docs' rule of thumb: use Desktop to manage parallel sessions, arrange panes and review changes visually; use the CLI for scripting, automation or a terminal workflow. Desktop also offers computer use on macOS and Windows.
What if the Code tab does not work?
The fixes the docs list most often:
- 403 or authentication errors: sign out and back in. If the CLI works but Desktop does not, quit the app completely and reopen it. Confirm you have an active paid plan.
- No environment selector under the prompt box: you have the earlier layout. Update from Claude > Check for Updates… on macOS or Help > Check for Updates… on Windows.
- Terminal-style commands reply "isn't available in this environment": commands that open a terminal panel, such as
/permissions, don't work in the Code tab. Edit the settings files directly, or run them from the CLI./configopens Settings > Claude Code instead.
Bring your prompts and skills with you
Because Desktop reads the same skills folders as the CLI, anything you install for Claude Code shows up in the Code tab's slash command list. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own and installs every skill into Claude Code with one command: npx skills add https://github.com/<you>/<repo>.git --all -g.