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

URL: https://developertoolkit.ai/en/claude-code/build/desktop-app/
Description: What the Claude Code Desktop app adds over the CLI: parallel worktree sessions, diff review, app preview and CI monitoring, and which settings both share.

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](https://code.claude.com/docs/en/desktop). 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](/en/claude-code/automate/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](/en/claude-code/automate/agent-sdk/) | Not available; Desktop is interactive only |
| Multi-agent | Agent teams (experimental), subagents, [dynamic workflows](/en/claude-code/automate/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](/en/claude-code/automate/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](/en/claude-code/quick-start/installation/) 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](/en/ecosystem/models/) 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:

   ```text
   .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:

   ```json
   {
     "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**

```text
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](/en/workflows/plan/acceptance-criteria/) covers how to write checks an agent cannot argue its way around.

**Copy-paste prompt: a feature session that proves itself**

```text
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**

```text
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](/en/ladder/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](/en/workflows/test/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**

```text
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](/en/claude-code/ship/review-automation/) and [reviewing an agent's pull request](/en/workflows/ship/agent-pr-review/).

## 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](/en/claude-code/build/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](/en/claude-code/quick-start/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`:

```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](/en/workflows/harness/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](/en/claude-code/team/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](/en/codex/build/app-mastery/) and [Codex worktrees](/en/codex/automate/worktrees/), and Cursor's parallel agents in the [Cursor Agents window](/en/cursor-ide/build/agents-window/).

## Where to go next with Claude Code Desktop

- [Agent view](/en/claude-code/automate/agent-view/) — Dispatch and supervise many background sessions from the terminal when Desktop's sidebar is not enough.
- [IDE integration](/en/claude-code/quick-start/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](/en/workflows/ship/agent-pr-review/) — The triage protocol for the pull requests your Desktop sessions open.
- [Channels and Remote Control](/en/claude-code/automate/channels-and-remote-control/) — Steer a running session from your phone or chat when you are away from the desk.
