Use Claude Code Desktop - Claude Code Docs

The Code tab within the Claude Desktop app lets you use Claude Code through a graphical interface instead of the terminal. Desktop adds these capabilities on top of the standard Claude Code experience:

• Visual diff review with inline comments
• Live app preview with dev servers
• GitHub PR monitoring with auto-fix and auto-merge
• Parallel sessions with automatic Git worktree isolation
• Scheduled tasks that run Claude on a recurring schedule
• Connectors for GitHub, Slack, Linear, and more
• Local, SSH, and cloud environments

This page covers working with code, managing sessions, extending Claude Code, scheduled tasks, and configuration. It also includes a CLI comparison and troubleshooting.

Start a session

Before you send your first message, configure four things in the prompt area:

• Environment: choose where Claude runs. Select Local for your machine, Remote for Anthropic-hosted cloud sessions, or an SSH connection for a remote machine you manage. See environment configuration.
• Project folder: select the folder or repository Claude works in. For remote sessions, you can add multiple repositories.
• Model: pick a model from the dropdown next to the send button. The model is locked once the session starts.
• Permission mode: choose how much autonomy Claude has from the mode selector. You can change this during the session.

Type your task and press Enter to start. Each session tracks its own context and changes independently.

Work with code

Give Claude the right context, control how much it does on its own, and review what it changed.

Use the prompt box

Type what you want Claude to do and press Enter to send. Claude reads your project files, makes changes, and runs commands based on your permission mode. You can interrupt Claude at any point: click the stop button or type your correction and press Enter. Claude stops what it’s doing and adjusts based on your input. The + button next to the prompt box gives you access to file attachments, skills, connectors, and plugins.

Add files and context to prompts

The prompt box supports two ways to bring in external context:

• @mention files: type @ followed by a filename to add a file to the conversation context. Claude can then read and reference that file.
• Attach files: attach images, PDFs, and other files to your prompt using the attachment button, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.

Choose a permission mode

Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch modes at any time using the mode selector next to the send button. Start with Ask permissions to see exactly what Claude does, then move to Auto accept edits or Plan mode as you get comfortable.

The dontAsk permission mode is available only in the CLI.

Remote sessions support Auto accept edits and Plan mode. Ask permissions is not available because remote sessions auto-accept file edits by default, and Bypass permissions is not available because the remote environment is already sandboxed. Enterprise admins can restrict which permission modes are available. See enterprise configuration for details.

Preview your app

Claude can start a dev server and open an embedded browser to verify its changes. This works for frontend web apps as well as backend servers: Claude can test API endpoints, view server logs, and iterate on issues it finds. In most cases, Claude starts the server automatically after editing project files. You can also ask Claude to preview at any time. By default, Claude auto-verifies changes after every edit. From the preview panel, you can:

• Interact with your running app directly in the embedded browser
• Watch Claude verify its own changes automatically: it takes screenshots, inspects the DOM, clicks elements, fills forms, and fixes issues it finds
• Start or stop servers from the Preview dropdown in the session toolbar
• Persist cookies and local storage across server restarts by selecting Persist sessions in the dropdown, so you don’t have to re-login during development
• Edit the server configuration or stop all servers at once

Claude creates the initial server configuration based on your project. If your app uses a custom dev command, edit .claude/launch.json to match your setup. See Configure preview servers for the full reference. To clear saved session data, toggle Persist preview sessions off in Settings → Claude Code. To disable preview entirely, toggle off Preview in Settings → Claude Code.

Review changes with diff view

After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request. When Claude changes files, a diff stats indicator appears showing the number of lines added and removed, such as +12 -1. Click this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right. To comment on specific lines, click any line in the diff to open a comment box. Type your feedback and press Enter to add the comment. After adding comments to multiple lines, submit all comments at once:

• macOS: press Cmd+Enter
• Windows: press Ctrl+Enter

Claude reads your comments and makes the requested changes, which appear as a new diff you can review.

Review your code

In the diff view, click Review code in the top-right toolbar to ask Claude to evaluate the changes before you commit. Claude examines the current diffs and leaves comments directly in the diff view. You can respond to any comment or ask Claude to revise. The review focuses on high-signal issues: compile errors, definite logic errors, security vulnerabilities, and obvious bugs. It does not flag style, formatting, pre-existing issues, or anything a linter would catch.

Monitor pull request status

After you open a pull request, a CI status bar appears in the session. Claude Code uses the GitHub CLI to poll check results and surface failures.

• Auto-fix: when enabled, Claude automatically attempts to fix failing CI checks by reading the failure output and iterating.
• Auto-merge: when enabled, Claude merges the PR once all checks pass. The merge method is squash. Auto-merge must be enabled in your GitHub repository settings for this to work.

Use the Auto-fix and Auto-merge toggles in the CI status bar to enable either option. Claude Code also sends a desktop notification when CI finishes.

Manage sessions

Each session is an independent conversation with its own context and changes. You can run multiple sessions in parallel or send work to the cloud.

Work in parallel with sessions

Click + New session in the sidebar to work on multiple tasks in parallel. For Git repositories, each session gets its own isolated copy of your project using Git worktrees, so changes in one session don’t affect other sessions until you commit them. Worktrees are stored in <project-root>/.claude/worktrees/ by default. You can change this to a custom directory in Settings → Claude Code under “Worktree location”. You can also set a branch prefix that gets prepended to every worktree branch name, which is useful for keeping Claude-created branches organized. To remove a worktree when you’re done, hover over the session in the sidebar and click the archive icon.

Use the filter icon at the top of the sidebar to filter sessions by status (Active, Archived) and environment (Local, Cloud). To rename a session or check context usage, click the session title in the toolbar at the top of the active session. When context fills up, Claude automatically summarizes the conversation and continues working. You can also type /compact to trigger summarization earlier and free up context space. See the context window for details on how compaction works.

Run long-running tasks remotely

For large refactors, test suites, migrations, or other long-running tasks, select Remote instead of Local when starting a session. Remote sessions run on Anthropic’s cloud infrastructure and continue even if you close the app or shut down your computer. Check back anytime to see progress or steer Claude in a different direction. You can also monitor remote sessions from claude.ai/code or the Claude iOS app. Remote sessions also support multiple repositories. After selecting a cloud environment, click the + button next to the repo pill to add additional repositories to the session. Each repo gets its own branch selector. This is useful for tasks that span multiple codebases, such as updating a shared library and its consumers. See Claude Code on the web for more on how remote sessions work.

Continue in another surface

The Continue in menu, accessible from the VS Code icon in the bottom right of the session toolbar, lets you move your session to another surface:

• Claude Code on the Web: sends your local session to continue running remotely. Desktop pushes your branch, generates a summary of the conversation, and creates a new remote session with the full context. You can then choose to archive the local session or keep it. This requires a clean working tree, and is not available for SSH sessions.
• Your IDE: opens your project in a supported IDE at the current working directory.

Extend Claude Code

Connect external services, add reusable workflows, customize Claude’s behavior, and configure preview servers.

Connect external tools

For local and SSH sessions, click the + button next to the prompt box and select Connectors to add integrations like Google Calendar, Slack, GitHub, Linear, Notion, and more. You can add connectors before or during a session. Connectors are not available for remote sessions. To manage or disconnect connectors, go to Settings → Connectors in the desktop app, or select Manage connectors from the Connectors menu in the prompt box. Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session. Connectors are MCP servers with a graphical setup flow. Use them for quick integration with supported services. For integrations not listed in Connectors, add MCP servers manually via settings files. You can also create custom connectors.

Use skills

Skills extend what Claude can do. Claude loads them automatically when relevant, or you can invoke one directly: type / in the prompt box or click the + button and select Slash commands to browse what’s available. This includes built-in commands, your custom skills, project skills from your codebase, and skills from any installed plugins. Select one and it appears highlighted in the input field. Type your task after it and send as usual.

Install plugins

Plugins are reusable packages that add skills, agents, hooks, MCP servers, and LSP configurations to Claude Code. You can install plugins from the desktop app without using the terminal. For local and SSH sessions, click the + button next to the prompt box and select Plugins to see your installed plugins and their commands. To add a plugin, select Add plugin from the submenu to open the plugin browser, which shows available plugins from your configured marketplaces including the official Anthropic marketplace. Select Manage plugins to enable, disable, or uninstall plugins. Plugins can be scoped to your user account, a specific project, or local-only. Plugins are not available for remote sessions. For the full plugin reference including creating your own plugins, see plugins.

Configure preview servers

Claude automatically detects your dev server setup and stores the configuration in .claude/launch.json at the root of the folder you selected when starting the session. Preview uses this folder as its working directory, so if you selected a parent folder, subfolders with their own dev servers won’t be detected automatically. To work with a subfolder’s server, either start a session in that folder directly or add a configuration manually. To customize how your server starts, for example to use yarn dev instead of npm run dev or to change the port, edit the file manually or click Edit configuration in the Preview dropdown to open it in your code editor. The file supports JSON with comments.

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

You can define multiple configurations to run different servers from the same project, such as a frontend and an API. See the examples below.

Auto-verify changes

When autoVerify is enabled, Claude automatically verifies code changes after editing files. It takes screenshots, checks for errors, and confirms changes work before completing its response. Auto-verify is on by default. Disable it per-project by adding "autoVerify": false to .claude/launch.json, or toggle it from the Preview dropdown menu.

{
  "version": "0.0.1",
  "autoVerify": false,
  "configurations": [...]
}

When disabled, preview tools are still available and you can ask Claude to verify at any time. Auto-verify makes it automatic after every edit.

Configuration fields

Each entry in the configurations array accepts the following fields:

When to use program vs runtimeExecutable

Use runtimeExecutable with runtimeArgs to start a dev server through a package manager. For example, "runtimeExecutable": "npm" with "runtimeArgs": ["run", "dev"] runs npm run dev. Use program when you have a standalone script you want to run with node directly. For example, "program": "server.js" runs node server.js. Pass additional flags with args.

Port conflicts

The autoPort field controls what happens when your preferred port is already in use:

• true: Claude finds and uses a free port automatically. Suitable for most dev servers.
• false: Claude fails with an error. Use this when your server must use a specific port, such as for OAuth callbacks or CORS allowlists.
• Not set (default): Claude asks whether the server needs that exact port, then saves your answer.

When Claude picks a different port, it passes the assigned port to your server via the PORT environment variable.

Examples

These configurations show common setups for different project types:

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

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "frontend",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "apps/web",
      "port": 3000,
      "autoPort": true
    },
    {
      "name": "api",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start"],
      "cwd": "server",
      "port": 8080,
      "env": { "NODE_ENV": "development" },
      "autoPort": false
    }
  ]
}

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "server",
      "program": "server.js",
      "args": ["--verbose"],
      "port": 4000
    }
  ]
}

Schedule recurring tasks

Scheduled tasks start a new local session automatically at a time and frequency you choose. Use them for recurring work like daily code reviews, dependency update checks, or morning briefings that pull from your calendar and inbox. Tasks run on your machine, so the desktop app must be open and your computer awake for them to fire. See How scheduled tasks run for details on missed runs and catch-up behavior.

To create a scheduled task, click Schedule in the sidebar, then + New task. Configure these fields:

You can also create a task by describing what you want in any session. For example, “set up a daily code review that runs every morning at 9am.”

Frequency options

• Manual: no schedule, only runs when you click Run now. Useful for saving a prompt you trigger on demand
• Hourly: runs every hour. Each task gets a fixed offset of up to 10 minutes from the top of the hour to stagger API traffic
• Daily: shows a time picker, defaults to 9:00 AM local time
• Weekdays: same as Daily but skips Saturday and Sunday
• Weekly: shows a time picker and a day picker

For intervals the picker doesn’t offer (every 15 minutes, first of each month, etc.), ask Claude in any Desktop session to set the schedule. Use plain language; for example, “schedule a task to run all the tests every 6 hours.”

How scheduled tasks run

Scheduled tasks run locally on your machine. Desktop checks the schedule every minute while the app is open and starts a fresh session when a task is due, independent of any manual sessions you have open. Each task gets a fixed delay of up to 10 minutes after the scheduled time to stagger API traffic. The delay is deterministic: the same task always starts at the same offset. When a task fires, you get a desktop notification and a new session appears under a Scheduled section in the sidebar. Open it to see what Claude did, review changes, or respond to permission prompts. The session works like any other: Claude can edit files, run commands, create commits, and open pull requests. Tasks only run while the desktop app is running and your computer is awake. If your computer sleeps through a scheduled time, the run is skipped. To prevent idle-sleep, enable Keep computer awake in Settings under Desktop app → General. Closing the laptop lid still puts it to sleep.

Missed runs

When the app starts or your computer wakes, Desktop checks whether each task missed any runs in the last seven days. If it did, Desktop starts exactly one catch-up run for the most recently missed time and discards anything older. A daily task that missed six days runs once on wake. Desktop shows a notification when a catch-up run starts. Keep this in mind when writing prompts. A task scheduled for 9am might run at 11pm if your computer was asleep all day. If timing matters, add guardrails to the prompt itself, for example: “Only review today’s commits. If it’s after 5pm, skip the review and just post a summary of what was missed.”

Permissions for scheduled tasks

Each task has its own permission mode, which you set when creating or editing the task. Allow rules from ~/.claude/settings.json also apply to scheduled task sessions. If a task runs in Ask mode and needs to run a tool it doesn’t have permission for, the run stalls until you approve it. The session stays open in the sidebar so you can answer later. To avoid stalls, click Run now after creating a task, watch for permission prompts, and select “always allow” for each one. Future runs of that task auto-approve the same tools without prompting. You can review and revoke these approvals from the task’s detail page.

Manage scheduled tasks

Click a task in the Schedule list to open its detail page. From here you can:

• Run now: start the task immediately without waiting for the next scheduled time
• Toggle repeats: pause or resume scheduled runs without deleting the task
• Edit: change the prompt, frequency, folder, or other settings
• Review history: see every past run, including ones that were skipped because your computer was asleep
• Review allowed permissions: see and revoke saved tool approvals for this task from the Always allowed panel
• Delete: remove the task and archive all sessions it created

You can also manage tasks by asking Claude in any Desktop session. For example, “pause my dependency-audit task”, “delete the standup-prep task”, or “show me my scheduled tasks.” To edit a task’s prompt on disk, open ~/.claude/scheduled-tasks/<task-name>/SKILL.md (or under CLAUDE_CONFIG_DIR if set). The file uses YAML frontmatter for name and description, with the prompt as the body. Changes take effect on the next run. Schedule, folder, model, and enabled state are not in this file: change them through the Edit form or ask Claude.

Environment configuration

The environment you pick when starting a session determines where Claude executes and how you connect:

• Local: runs on your machine with direct access to your files
• Remote: runs on Anthropic’s cloud infrastructure. Sessions continue even if you close the app.
• SSH: runs on a remote machine you connect to over SSH, such as your own servers, cloud VMs, or dev containers

Local sessions

Local sessions inherit environment variables from your shell. If you need additional variables, set them in your shell profile, such as ~/.zshrc or ~/.bashrc, and restart the desktop app. See environment variables for the full list of supported variables. Extended thinking is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To disable thinking entirely, set MAX_THINKING_TOKENS=0 in your shell profile. On Opus, MAX_THINKING_TOKENS is ignored except for 0 because adaptive reasoning controls thinking depth instead.

Remote sessions

Remote sessions continue in the background even if you close the app. Usage counts toward your subscription plan limits with no separate compute charges. You can create custom cloud environments with different network access levels and environment variables. Select the environment dropdown when starting a remote session and choose Add environment. See cloud environments for details on configuring network access and environment variables.

SSH sessions

SSH sessions let you run Claude Code on a remote machine while using the desktop app as your interface. This is useful for working with codebases that live on cloud VMs, dev containers, or servers with specific hardware or dependencies. To add an SSH connection, click the environment dropdown before starting a session and select + Add SSH connection. The dialog asks for:

• Name: a friendly label for this connection
• SSH Host: user@hostname or a host defined in ~/.ssh/config
• SSH Port: defaults to 22 if left empty, or uses the port from your SSH config
• Identity File: path to your private key, such as ~/.ssh/id_rsa. Leave empty to use the default key or your SSH config.

Once added, the connection appears in the environment dropdown. Select it to start a session on that machine. Claude runs on the remote machine with access to its files and tools. Claude Code must be installed on the remote machine. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.

Enterprise configuration

Organizations on Teams or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies.

Admin console controls

These settings are configured through the admin settings console:

• Enable or disable the Code tab: control whether users in your organization can access Claude Code in the desktop app
• Disable Bypass permissions mode: prevent users in your organization from enabling bypass permissions mode
• Disable Claude Code on the web: enable or disable remote sessions for your organization

Managed settings

Managed settings override project and user settings and apply when Desktop spawns CLI sessions. You can set these keys in your organization’s managed settings file or push them remotely through the admin console.

For the complete list of managed-only settings including allowManagedPermissionRulesOnly and allowManagedHooksOnly, see managed-only settings. Remote managed settings uploaded through the admin console currently apply to CLI and IDE sessions only. For Desktop-specific restrictions, use the admin console controls above.

Device management policies

IT teams can manage the desktop app through MDM on macOS or group policy on Windows. Available policies include enabling or disabling the Claude Code feature, controlling auto-updates, and setting a custom deployment URL.

• macOS: configure via com.anthropic.Claude preference domain using tools like Jamf or Kandji
• Windows: configure via registry at SOFTWARE\Policies\Claude

Authentication and SSO

Enterprise organizations can require SSO for all users. See authentication for plan-level details and Setting up SSO for SAML and OIDC configuration.

Data handling

Claude Code processes your code locally in local sessions or on Anthropic’s cloud infrastructure in remote sessions. Conversations and code context are sent to Anthropic’s API for processing. See data handling for details on data retention, privacy, and compliance.

Deployment

Desktop can be distributed through enterprise deployment tools:

• macOS: distribute via MDM such as Jamf or Kandji using the .dmg installer
• Windows: deploy via MSIX package or .exe installer. See Deploy Claude Desktop for Windows for enterprise deployment options including silent installation

For network configuration such as proxy settings, firewall allowlisting, and LLM gateways, see network configuration. For the full enterprise configuration reference, see the enterprise configuration guide.

Coming from the CLI?

If you already use the Claude Code CLI, Desktop runs the same underlying engine with a graphical interface. You can run both simultaneously on the same machine, even on the same project. Each maintains separate session history, but they share configuration and project memory via CLAUDE.md files. To move a CLI session into Desktop, run /desktop in the terminal. Claude saves your session and opens it in the desktop app, then exits the CLI. This command is available on macOS and Windows only.

CLI flag equivalents

This table shows the desktop app equivalent for common CLI flags. Flags not listed have no desktop equivalent because they are designed for scripting or automation.

Shared configuration

Desktop and CLI read the same configuration files, so your setup carries over:

• CLAUDE.md files in your project are used by both
• MCP servers configured in ~/.claude.json or .mcp.json work in both
• Hooks and skills defined in settings apply to both
• Settings in ~/.claude.json and ~/.claude/settings.json are shared. Permission rules, allowed tools, and other settings in settings.json apply to Desktop sessions.
• Models: Sonnet, Opus, and Haiku are available in both. In Desktop, select the model from the dropdown next to the send button before starting a session. You cannot change the model during an active session.

Feature comparison

This table compares core capabilities between the CLI and Desktop. For a full list of CLI flags, see the CLI reference.

What’s not available in Desktop

The following features are only available in the CLI or VS Code extension:

• Third-party providers: Desktop connects to Anthropic’s API directly. Use the CLI with Bedrock, Vertex, or Foundry instead.
• Linux: the desktop app is available on macOS and Windows only.
• Inline code suggestions: Desktop does not provide autocomplete-style suggestions. It works through conversational prompts and explicit code changes.
• Agent teams: multi-agent orchestration is available via the CLI and Agent SDK, not in Desktop.

Troubleshooting

Check your version

To see which version of the desktop app you’re running:

• macOS: click Claude in the menu bar, then About Claude
• Windows: click Help, then About

Click the version number to copy it to your clipboard.

403 or authentication errors in the Code tab

If you see Error 403: Forbidden or other authentication failures when using the Code tab:

1. Sign out and back in from the app menu. This is the most common fix.
2. Verify you have an active paid subscription: Pro, Max, Teams, or Enterprise.
3. If the CLI works but Desktop does not, quit the desktop app completely, not just close the window, then reopen and sign in again.
4. Check your internet connection and proxy settings.

Blank or stuck screen on launch

If the app opens but shows a blank or unresponsive screen:

1. Restart the app.
2. Check for pending updates. The app auto-updates on launch.
3. On Windows, check Event Viewer for crash logs under Windows Logs → Application.

”Failed to load session”

If you see Failed to load session, the selected folder may no longer exist, a Git repository may require Git LFS that isn’t installed, or file permissions may prevent access. Try selecting a different folder or restarting the app.

Session not finding installed tools

If Claude can’t find tools like npm, node, or other CLI commands, verify the tools work in your regular terminal, check that your shell profile properly sets up PATH, and restart the desktop app to reload environment variables.

Git and Git LFS errors

On Windows, Git is required for the Code tab to start local sessions. If you see “Git is required,” install Git for Windows and restart the app. If you see “Git LFS is required by this repository but is not installed,” install Git LFS from git-lfs.com, run git lfs install, and restart the app.

MCP servers not working on Windows

If MCP server toggles don’t respond or servers fail to connect on Windows, check that the server is properly configured in your settings, restart the app, verify the server process is running in Task Manager, and review server logs for connection errors.

App won’t quit

• macOS: press Cmd+Q. If the app doesn’t respond, use Force Quit with Cmd+Option+Esc, select Claude, and click Force Quit.
• Windows: use Task Manager with Ctrl+Shift+Esc to end the Claude process.

Windows-specific issues

• PATH not updated after install: open a new terminal window. PATH updates only apply to new terminal sessions.
• Concurrent installation error: if you see an error about another installation in progress but there isn’t one, try running the installer as Administrator.
• ARM64: Windows ARM64 devices are fully supported.

Cowork tab unavailable on Intel Macs

The Cowork tab requires Apple Silicon (M1 or later) on macOS. On Windows, Cowork is available on all supported hardware. The Chat and Code tabs work normally on Intel Macs.

”Branch doesn’t exist yet” when opening in CLI

Remote sessions can create branches that don’t exist on your local machine. Click the branch name in the session toolbar to copy it, then fetch it locally:

git fetch origin <branch-name>
git checkout <branch-name>

Still stuck?

• Search or file a bug on GitHub Issues
• Visit the Claude support center

When filing a bug, include your desktop app version, your operating system, the exact error message, and relevant logs. On macOS, check Console.app. On Windows, check Event Viewer → Windows Logs → Application.