Desktop App

If you're not comfortable with the CLI or prefer a visual working environment, you can use the Claude Code Desktop app. It wraps the same engine as the CLI in a GUI and adds extra features like visual diffs, app preview, and parallel sessions.

CLI vs Desktop

Feature	CLI	Desktop
File edits / command execution	O	O
CLAUDE.md, MCP, Hooks, Skills	O	O (shared)
Visual diff review	-	O
App preview (built-in browser)	-	O
Image/PDF attachments	-	O
Parallel sessions (automatic Worktrees)	Manual	O (automatic)
Scheduled Tasks	cron/CI	O (GUI)
Connectors (Slack, Linear, etc.)	-	O
@file autocomplete	-	O
Cowork + Dispatch (mobile→desktop)	-	O
Headless/automation	O	-
Agent Teams	O (CLI/SDK)	-
Bedrock/Vertex/Foundry	O	-
Linux	O	O (beta, apt install)

Shared Settings

Desktop and CLI share CLAUDE.md, MCP servers (~/.claude.json, .mcp.json), Hooks, Skills, and settings. Configure on either side and it applies to both. Note that claude_desktop_config.json (for the Chat app) is separate.

Getting Started

1. Installation

Access Claude Code through the Code tab in the Claude Desktop app:

• macOS: Download from claude.ai/download (both Intel and Apple Silicon supported, but the Cowork tab is Apple Silicon only)
• Windows: Download from the same link (full x64 support; ARM64 supports Remote sessions only)
• Linux (beta): Register the Anthropic apt repository, then sudo apt update && sudo apt install claude-desktop (Ubuntu 22.04+/Debian 12+, x86_64 and arm64). The Chat, Cowork, and Code tabs are all available, but Computer Use and voice input are not yet supported. Direct .deb installation also works, but automatic updates are only provided when you register the apt repository

A Pro, Max, Team, or Enterprise plan is required.

2. Pre-Session Setup

Configure four things before starting a session:

Setting	Description
Environment	Local (your PC), Remote (cloud), SSH (remote server), WSL (a WSL 2 distro on Windows)
Project folder	The directory or repository Claude will work in
Model	Choose from Sonnet, Opus, or Haiku (cannot be changed after the session starts)
Permission mode	Claude's level of autonomy (can be changed during the session)

3. Entering Prompts

• Type your task in the prompt box and press Enter
• Add files to context with @filename (autocomplete supported)
• Add images and PDFs via drag & drop or the attach button
• At any point during a task, use the stop button or type a correction to change direction

The Desktop App's 3 Tabs

Tab	Role
Chat	Regular conversation (same as claude.ai, no file access)
Cowork	An agent that works autonomously in the background. The Dispatch feature lets you assign tasks from mobile
Code	Directly accesses local files and modifies code in real time. Review and approve changes

Cowork Dispatch

Send a task from the mobile app and let Claude on your desktop PC handle it:

• Setup: Cowork tab → Dispatch in the left panel → Get started → configure file access permissions and sleep settings
• Example uses: extracting data from a local spreadsheet, searching Slack/email and writing a briefing, generating a presentation from Google Drive files
• Limitations: the desktop must be powered on, only a single thread is used, no task-completion notifications

Cowork Tab Limitations

• macOS: Available only on Apple Silicon (M1 or later). Intel Macs support Chat/Code only
• Windows: Available on all hardware
• Requires a Pro or Max plan

Computer Use (Research Preview)

A feature where Claude directly controls the mouse, keyboard, and screen to open apps, click, and type. Use it for GUI-only tasks that can't be handled by a Connector or Bash.

macOS Only

Computer Use is currently available on macOS only. Windows support is planned. Requires a Pro or Max plan.

Enable in Desktop: Settings > Desktop app > General > Computer use toggle → grant two macOS permissions (Accessibility + Screen Recording)

Enable in CLI (v2.1.85+): /mcp → select the computer-use server → Enable. You get the same screen control from the terminal, without the Desktop app.

	Desktop	CLI
Platform	macOS, Windows	macOS only
Enable via	Settings toggle	Enable in /mcp
Denied apps	Configurable	Not supported
Dispatch integration	Yes	No

Tool priority — Claude tries the most precise tool first:

1. Connector (dedicated integrations like Slack, Calendar)
2. Bash (shell commands)
3. Claude in Chrome (browser tasks)
4. Computer Use (last resort when none of the above apply)

Per-app permission tiers:

Tier	Allowed actions	Targets
View only	Screenshots only	Browsers, trading platforms
Click only	Click, scroll (no typing)	Terminals, IDEs
Full control	Click, type, drag, shortcuts	All other apps

• An approval prompt appears the first time each app is accessed
• App approvals in Dispatch-created sessions expire after 30 minutes
• You can pre-block specific apps in Settings > Desktop app > General > Denied apps

This playbook focuses mainly on the Code tab.

Key Features (Code Tab)

App Preview

Desktop automatically starts your dev server and shows the result in a built-in browser:

• Auto-verify (on by default): when Claude modifies code, it automatically verifies the change (screenshots, DOM inspection, clicks, form input). Disable with "autoVerify": false in .claude/launch.json
• Cookies and localStorage persist across restarts (the Persist sessions option)
• Edit server settings from the Preview dropdown

Preview server settings are stored in .claude/launch.json:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "web",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

In-App Browser (Browsing External Sites)

The Browser panel used for app preview is also a tabbed browser. You can open external sites — docs, issue trackers — side by side with your running app:

• Open: Cmd+Shift+B (macOS) / Ctrl+Shift+B (Windows), or the Views menu
• When you click an external link in chat, you can choose Open in app (Browser panel) / Default browser (your own browser)
• Claude can read and interact with external pages — but write actions like clicks and typing are reviewed by a safety classifier regardless of permission mode, and each site shows an approval prompt on first interaction (Allow once / Always allow / Deny)
• The Browser panel uses a clean profile separate from your personal browser. To work with your logged-in accounts, use the Claude in Chrome extension

Visual Diff Review

Review code changes visually, file by file:

• Click a specific line to add an inline comment
• Submit comments in bulk with Cmd+Enter (macOS) / Ctrl+Enter (Windows)
• Use the Review code button to ask Claude to evaluate the changes (focused on compile errors, logic errors, security vulnerabilities, and obvious bugs)

PR Monitoring

When you open a PR, a CI status bar appears:

• Auto-fix: Claude automatically fixes failing CI checks
• Auto-merge: automatically merges when all checks pass

The GitHub CLI (gh) must be installed and authenticated.

Parallel Sessions

Run multiple tasks at once with + New session. In a Git repository, each session is automatically isolated in its own Worktree so they don't interfere with each other.

Scheduled Tasks

Set up recurring tasks under Schedule in the sidebar:

• Manual: run manually only (saves the prompt)
• Hourly / Daily / Weekdays / Weekly: choose the time and frequency
• The app must be open and the computer awake for tasks to run
• A missed run is made up once at app startup, as long as it's within 7 days
• Each task can have its own independent permission mode

Useful for daily code reviews, dependency update checks, morning briefings, and more.

Environment Characteristics

Environment	Characteristics
Local	Inherits shell environment variables, Extended Thinking on by default
Remote	Keeps running in the background even when the app is closed, included in your subscription (no extra cost). Multi-repository support
SSH	Runs on a remote machine; Claude Code must be installed on the remote. Set up a connection: environment dropdown → + Add SSH connection
WSL	Runs the session inside a WSL 2 distro on Windows (see below)

WSL Sessions (Windows)

On Windows, you can start a session by selecting an installed WSL 2 distro from the WSL section of the environment picker. The Claude Code process, tools, and git all run inside the distro using Linux paths (/home/you/project). If your repository lives in the distro's filesystem, use a WSL session — accessing it from the Windows side goes through a network filesystem, which is slow and breaks file watching.

• Requirements: Windows 10/11 + WSL 2 (WSL 1 not supported), at least one installed distro, git installed inside the distro
• Folder trust is granted separately per distro and per folder — the same path is not trusted across a different distro or the Windows side
• Parallel sessions, side chat, visual diff review, branch/PR status, and Worktrees all work off git inside the distro

Features Not Supported in WSL Sessions

The integrated terminal, Connectors and plugins, session forking, the file browser panel, and @ file autocomplete are not yet available in WSL sessions.

Connectors

Connect external tools via + → Connectors in the prompt box:

• GitHub, Slack, Linear, Notion, Google Calendar, and more
• Not available in Remote sessions

Slash Commands and Plugins

• Type / to see built-in commands, custom Skills, and plugin Skills
• Install and manage plugins via + → Plugins

Switching to Another Environment

From the Continue in menu at the bottom right of the toolbar:

• Move to Claude Code on the Web
• Open in a supported IDE