Claude Code Desktop: sessions, worktrees and review in the app

Claude Code Desktop is the Code tab of the Claude desktop app: the same engine as the Claude Code CLI with a graphical interface for parallel sessions, each in its own git worktree, line-level diff review, a live app preview, and pull request monitoring through CI. It reads the same CLAUDE.md, settings, hooks, skills and MCP files as the CLI.

You have a feature half-built in one terminal, a bug report in Slack, and a reviewer asking for changes on yesterday’s pull request. In the CLI that means three terminals, three --worktree sessions to keep apart, a browser tab per dev server, and a diff you read with git diff | less. This page is for developers who already use Claude Code in the terminal, or are about to, and want to know when the desktop app is the better cockpit and what they must set up so both surfaces behave the same.

Checked against Claude Code 2.1.283

Everything on this page was checked on 2026-09-26 against Claude Code v2.1.283 and the vendor’s desktop reference. The pane layout, terminal, file editor and view modes need Claude Desktop v1.2581.0 or later. The app changes weekly; check Claude → About Claude (macOS) or Help → About (Windows) before you rely on a detail.

What you get from the desktop app workflow

• A decision table for when to work in Desktop and when to stay in the terminal.
• A setup that makes every Desktop session start in its own worktree with the right .env files and dev server.
• Four copy-paste prompts: a preview configuration, a parallel feature session that ends in evidence, a cross-session check, and a review map of the diff.
• A review loop that uses the diff view, Review code and the CI status bar, with tests as the gate instead of your eyes.
• The configuration traps: environment variables, MCP precedence and permission modes that behave differently from the CLI.

What does the desktop app add over the terminal?

Desktop runs the same engine, so the model, the tools and the agent loop are identical. What changes is how you supervise several sessions and how you look at the result. Before you install, you need a paid Pro, Max, Team or Enterprise subscription; without one the Code tab fails with an authentication error (see the troubleshooting table).

Capability	CLI	Desktop
Parallel sessions	One terminal per session, or agent view	Sidebar list; Cmd+click (macOS) or Ctrl+click (Windows) opens two sessions side by side
Session isolation	claude --worktree [name] (-w; the name is optional)	worktree option next to the branch name when you start a session
Diff review	/diff, git diff, your IDE	Diff view with line comments that Claude acts on, plus a Review code button
App preview	Your own browser	Browser pane that starts the dev server from .claude/launch.json and lets Claude screenshot, click and inspect the DOM
Pull request follow-up	gh, your CI page	CI status bar with Auto-fix and Auto-merge toggles (needs an authenticated gh)
Where it runs	Your machine, cloud (--cloud), a devcontainer	Local, Cloud, SSH host, or a WSL distribution on Windows
Scripting	claude -p, --output-format, the Agent SDK	Not available; Desktop is interactive only
Multi-agent	Agent teams (experimental), subagents, dynamic workflows	Subagents and dynamic workflows; agent teams are CLI-only (checked 2026-09-26)
Permission modes	All, including dontAsk	Manual, Accept edits, Plan, Auto; Bypass permissions only once enabled; no dontAsk (checked 2026-09-26)

The app runs on macOS, Windows (x64 and ARM64) and Linux (beta, installed with apt on Ubuntu and Debian). Computer use, where Claude controls other apps on your screen, is a research preview on macOS and Windows for Pro and Max plans only, and is not in the Linux build.

When should you use Desktop instead of the CLI?

Pick the surface by the shape of the work, not by habit. Both can run on the same project at the same time, and each keeps its own session list.

Your work looks like…	Use	Why
A few independent tasks you steer by hand during the day	Desktop	Sidebar, split view and OS notifications show which session needs you
UI or API work you want to see running	Desktop	The Browser pane and auto-verify put the running app next to the diff
Reviewing a change before it becomes a pull request	Desktop	Line comments go straight back to Claude as a new turn
A script, a CI job, a pre-commit hook, anything with -p	CLI	Desktop has no non-interactive mode
Many background sessions dispatched from one place	CLI (agent view)	Built for dispatch and peek; Desktop’s cross-session tools do not see CLI sessions
Amazon Bedrock, Google Cloud’s Agent Platform or Microsoft Foundry	CLI, unless IT has set up Claude Desktop for that provider	Desktop connects to Anthropic’s API by default
Coordinated agent teams	CLI	Not in Desktop
A long migration that must keep running after you close the laptop	Desktop Cloud session, or claude --cloud in the CLI	Cloud sessions run on Anthropic-managed infrastructure and count toward your plan limits

The two surfaces hand off in both directions. In a terminal session, run /desktop (alias /app) to save the session and reopen it in the app; this works on macOS and x64 Windows with a Claude subscription, not with an API key or a third-party provider. In the app, type /resume in the prompt box to pick up any session you started from the CLI, searchable by title, folder or branch.

Set up Desktop so every session is isolated and verifiable

The defaults work for a first session. For daily parallel work, do the setup below once per repository; it is what keeps sessions from colliding and gives Claude a way to check its own work. Install the app first, from the installation guide or the vendor’s download page, and sign in.

1. Open the Code tab and pick four things before the first message. In the prompt area choose the environment (Local for your machine), the project folder, the model and the permission mode. Start with the default model; the models hub explains when to change it. Start with Plan for anything larger than a bug fix, then switch to Accept edits once you approve the plan.

2. Turn on the worktree option for every session in a git repository. Select worktree next to the branch name. Each session then gets its own checkout under <project-root>/.claude/worktrees/, so edits in one session never touch another until you commit. In Settings → Claude Code you can move the worktree location and set a branch prefix such as claude/ so agent branches are easy to spot and clean up.

3. Copy gitignored files into new worktrees. A worktree is a fresh checkout, so your .env is missing and the dev server fails to start. Add a .worktreeinclude file to the project root. It uses .gitignore syntax, and only files that are also gitignored are copied:

   .env
   .env.local
   config/local.json

   The same file applies to CLI --worktree sessions and subagent worktrees, so you write it once.

4. Give the preview a server configuration. Claude detects your dev server and writes .claude/launch.json in the folder you opened. Check it into the repository and correct it; for a monorepo with a web app and an API it looks like this:

   {
     "version": "0.0.1",
     "configurations": [
       {
         "name": "web",
         "runtimeExecutable": "pnpm",
         "runtimeArgs": ["--filter", "web", "dev"],
         "port": 3000,
         "autoPort": true
       },
       {
         "name": "api",
         "runtimeExecutable": "pnpm",
         "runtimeArgs": ["--filter", "api", "start"],
         "port": 8080,
         "autoPort": false
       }
     ]
   }

   Set autoPort: true for servers that can move when two worktrees run at once; Claude passes the new port in PORT. Set autoPort: false for a server whose port is fixed by an OAuth callback or a CORS allowlist. Never put secrets in env here: the file is committed. Auto-verify is on by default, so Claude screenshots and checks the page after each edit; turn it off per project with "autoVerify": false.

5. Set local environment variables in the app, not only in your shell. When you launch the app from the Dock or Finder on macOS, it reads PATH and a fixed set of Claude Code variables from your shell profile and ignores everything else you export there. On Windows it ignores PowerShell profiles. Open the environment dropdown, hover over Local, click the gear icon, and add the variables your dev server needs. The env key in ~/.claude/settings.json reaches Claude’s sessions but not the preview servers.

6. Authenticate gh if you want pull request monitoring. The CI status bar polls checks through the GitHub CLI. Run gh auth status in the integrated terminal (Ctrl+`); if it fails, run gh auth login.

Copy-paste prompt: write the preview config for this repository

Inspect package.json files, Procfile, docker-compose.yml and any README run
instructions in this repository. Write .claude/launch.json with one
configuration per server a developer runs locally. Use the exact commands the
repo documents, not guesses. Set autoPort to false for any server whose port
appears in an OAuth redirect URI, a CORS allowlist or another service's config,
and cite the file and line that pins it. Put no secrets in env. Then start each
server from the preview, load its root URL, and report which ones came up and
which failed, with the error output for any failure.

Run parallel sessions that end in evidence

The desktop app makes starting a session cheap. The limit on your day is how many results you can check, so make each session produce the proof you will check. Press Cmd+N (macOS) or Ctrl+N (Windows) for a new session, pick the worktree option, and start from a prompt that names the acceptance check and the deliverable. Acceptance criteria covers how to write checks an agent cannot argue its way around.

Copy-paste prompt: a feature session that proves itself

Add CSV export to the invoices table on /billing/invoices. Acceptance: the
Export button downloads a file with the same columns and row order as the
table, respects the current filters, and escapes commas and quotes correctly.
Work only in this worktree. Write the tests first: a unit test for the CSV
serializer with a row containing a comma, a quote and a newline, and an
end-to-end test that applies a filter and checks the downloaded file. Show me
the failing tests, then implement. Run the full test suite, the type checker
and the linter. Open the preview, apply a filter, export, and attach a
screenshot. Finish with a summary listing each acceptance point, the test that
covers it, and the command output that shows it passing. Do not commit.

Ctrl+Tab and Ctrl+Shift+Tab cycle through sessions. The app sends an OS notification when a session finishes and you are not looking at it, so you can leave a session running and switch to another. To ask a question without steering the session off course, open a side chat with Cmd+; (macOS), Ctrl+; (Windows) or /btw. It can read the session up to that point, and you close it to return to the main thread.

Claude can also inspect and message your other Desktop sessions. Ask in plain language in any session:

Copy-paste prompt: check what the other sessions are doing

List my other sessions in this project. For each one, tell me its branch, what
it changed, whether its tests last passed, and whether it is waiting on me.
Flag any two sessions that edited the same file. If the payments session has
not seen the schema change in migrations/0042_invoice_currency.sql, send it a
message describing the new column and ask it to rerun its tests.

This surface sees only local, SSH and WSL sessions that the app runs itself, the 20 most recently active by default. It does not see cloud sessions or sessions started from the CLI or the VS Code extension, even in worktrees of the same repository. Claude always asks before archiving a session, in every permission mode.

Review the diff without reading every line

Your job at this point is to decide whether the evidence holds, not to proofread. Evidence, not diffs explains the shift; the desktop app gives you the tools for it in this order:

1. Read the session’s summary first. Every acceptance point needs a named test and passing output. A point with no test is a gap, not a pass. Ask for the test before you look at code.
2. Open the diff view with the +12 -1 indicator (or Cmd+Shift+D). The file list on the left tells you where the risk is. Ask for a review map if the change touches more than a handful of files (prompt below).
3. Click Review code. Claude examines the current diff and leaves comments in it. It targets compile errors, definite logic errors, security vulnerabilities and obvious bugs, and skips style and anything a linter catches. Treat it as a second pass, not a sign-off: it is the same model family that wrote the code.
4. Comment on the lines that worry you. Click a line, type the comment, and submit all comments with Cmd+Enter (Ctrl+Enter on Windows). Claude answers with a new diff. Comment on behaviour (“what happens when the filter matches no rows?”), not on naming.
5. Check that the tests were not weakened. Look at the test files in the diff before the source files. A deleted assertion or a new skip is the most common way an agent “passes”. Protect the oracle shows how to make that impossible with hooks and file permissions.
6. Open the pull request and let CI decide. The CI status bar appears in the session. Auto-fix lets Claude read failing checks and push fixes. Auto-merge makes Claude squash-merge the pull request once all checks pass, and needs auto-merge enabled in the GitHub repository settings. Turn it on only in repositories where branch protection requires your review and every check you rely on, because a green check list is all it waits for.

Copy-paste prompt: a review map before you read the diff

Before I review this diff, produce a review map. Group every changed file into
one of: behaviour change, test, config or migration, generated or mechanical.
For each behaviour change, name the test that exercises it and quote the
assertion. List every test file where an assertion was removed, loosened or
skipped. List anything that touches authentication, payments, data deletion
or a migration. End with the three hunks you think are most likely to be
wrong and why. Do not change any code.

For tech leads: the diff view is a personal review aid, not a team gate. Required checks in CI and code owners on the pull request stay the gate, as described in review automation and reviewing an agent’s pull request.

How are settings shared between Desktop and the CLI?

Desktop and the CLI read the same files, so most of your setup carries over without work:

• Memory: CLAUDE.md and CLAUDE.local.md in the project; see the memory system.
• Settings: ~/.claude/settings.json, project .claude/settings.json and ~/.claude.json. Permission rules and allowed tools apply to Desktop sessions.
• Hooks and skills defined in settings, and personal skills in ~/.claude/skills/. An SSH session reads ~/.claude/skills/ on the remote host, not your laptop.
• MCP servers from ~/.claude.json and .mcp.json; see MCP setup.
• Plugins at user, project or local scope, including plugins your organization manages.

Set the default permission mode once, for both surfaces, in ~/.claude/settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

In Desktop, a mode you pick in the selector is remembered per folder and overrides defaultMode for that folder, except Plan, which lasts one session. That is the most common reason a teammate’s Desktop session asks for fewer approvals than yours in the same repository.

Three things are not shared the way you would expect:

What	Desktop behaviour	What to do
MCP servers in claude_desktop_config.json (the Chat tab’s config)	Loaded into local Code sessions; on a name clash with ~/.claude.json or .mcp.json, the claude_desktop_config.json definition wins	Keep one definition per server name. To copy those servers into the CLI, run claude mcp add-from-claude-desktop (macOS and WSL)
A stdio server defined both in user-scope ~/.claude.json and project .mcp.json	The Code tab uses the ~/.claude.json one, the reverse of the CLI’s scope order	Remove the personal copy when the project one is the source of truth
Session lists	Separate per surface	Move sessions with /desktop from the CLI or /resume in Desktop

Connectors, the servers you add with the + button, are MCP servers with a graphical setup. Use them for supported services like GitHub, Linear or Slack; keep anything the team shares in the project’s .mcp.json so the CLI and CI see it too.

What breaks when you move to Desktop?

Symptom	Cause	Recovery
Claude cannot find node, pnpm or python	The app did not inherit the PATH your shell builds (version managers, custom profiles)	Check the tool works in a terminal, fix PATH in your shell profile, restart the app; add missing variables in the local environment editor
The preview server starts but cannot reach the database	The variable lives in your shell or in settings.json env, which never reaches preview servers	Add it in the local environment editor (gear icon on Local)
“Git is required” or a Git LFS error when a session starts	Worktree sessions need Git, and some repositories need Git LFS	Install Git (Git for Windows on Windows); for LFS, install it, run git lfs install, restart the app
Second session’s dev server fails with a port in use	Two worktrees start the same server on the same port	Set autoPort: true for that configuration, or false with one session running it at a time
An MCP server behaves differently than in the terminal	Same name defined in claude_desktop_config.json or user scope, which win in the Code tab	Rename or remove the duplicate definition
/permissions replies isn't available in this environment	Commands that open a terminal dialog do not run in Desktop	Edit the settings file directly, or run the command in the CLI
Error 403: Forbidden in the Code tab	Stale sign-in or no paid plan	Sign out and in; if the CLI works but Desktop does not, quit the app fully and reopen
“Branch doesn’t exist yet” when opening a cloud session in the CLI	The cloud session created a branch you have not fetched	Copy the branch name from the toolbar, then git fetch origin <branch> and git checkout <branch>
Continue in → Claude Code on the Web is greyed out or refuses	The hand-off pushes your branch and needs a clean working tree; it is not available for SSH sessions	Commit or stash first, then retry; for an SSH session, push the branch and start a cloud session from it
A worktree you still needed is gone	Archiving a session, by hand or by auto-archive after the pull request merges or closes, removes its worktree	Commit and push before you archive; leave auto-archive off if you reuse branches after a pull request closes

Two settings need care beyond troubleshooting. Bypass permissions is the Desktop equivalent of --dangerously-skip-permissions; use it only in a disposable, network-restricted container or VM, never on your laptop with production credentials in reach. Permissions and sandboxing covers the safe setups. And on managed devices, administrators can turn off local sessions (disableDesktopLocalSessions), restrict permission modes, pre-configure SSH hosts and block external browsing; see enterprise integration before you promise the team a feature.

The same ideas exist in the other tools, with different surfaces: the Codex desktop app is covered in Codex app mastery and Codex worktrees, and Cursor’s parallel agents in the Cursor Agents window.

Where to go next with Claude Code Desktop

Agent view Dispatch and supervise many background sessions from the terminal when Desktop's sidebar is not enough.

IDE integration Connect Claude Code to VS Code or JetBrains when you want edits beside your editor instead of a separate app.

Reviewing an agent's pull request The triage protocol for the pull requests your Desktop sessions open.

Channels and Remote Control Steer a running session from your phone or chat when you are away from the desk.