Omniscio

OmniscioGuidesClaude Code desktop app

Claude Code desktop app: install and first session

The desktop app gives you Claude Code with a graphical interface: you ask Claude to change code in a folder on your computer, then review the changes yourself, without using a terminal.

Last checked against Anthropic's desktop documentation on November 18, 2026. By the Omniscio team. Updated .

What the desktop app is

The Claude desktop app is Anthropic's own application for macOS, Windows and Linux, and Claude Code lives inside it as one tab. Anthropic calls it Claude Code with a graphical interface: the same engine, with panes, buttons and a diff view instead of a terminal.

It is not a replacement for the CLI. Desktop and the command-line tool can run on the same machine at the same time, even on the same project. Each keeps its own session list, and both read the same CLAUDE.md files and settings.

If you already have the CLI and only want a window to review diffs in, you can open a session you started in the terminal inside the app. That route is further down this page.

Sources: Get started with the desktop app and the "Coming from the CLI?" section of Desktop application, read November 18, 2026.

Install it and open the Code tab

Download the installer for your machine, run it, then launch Claude from the Applications folder on macOS, the Start menu on Windows, or your application launcher on Linux. Sign in with your Anthropic account.

Windows users on ARM processors need the separate ARM64 installer; the default Windows download is for x64. Linux is a beta with apt and .deb packages, covered on Anthropic's Claude Desktop on Linux page.

Then click Code at the top of the app's sidebar. If the tabs show only icons, hover over one to see its name. Anthropic names three things that can appear at this point and what each means:

  • A prompt to upgrade. Claude Code in the app requires Pro, Max, Ultra, Team or Enterprise. The free plan does not include it.
  • A prompt to sign in online. Finish that sign-in, then restart the app.
  • A 403 error. That is an authentication problem rather than an install problem, and Anthropic's desktop page has a section for it.

Nothing else is needed. Anthropic states plainly that the desktop app includes Claude Code, so you do not install Node.js or the CLI to use the Code tab.

Sources: the Install and Open-the-Code-tab steps of Get started with the desktop app, read November 18, 2026.

Start your first session

With the Code tab open, the row under the prompt box holds the controls that decide where Claude works and which model answers. Set them left to right.

  1. Environment. Click the first control and pick the top entry in the Local group. The other choices are Cloud, SSH and, on Windows, WSL.
  2. Folder. Click the folder control beside it, choose Open folder…, and pick the project directory.
  3. Model. Choose one from the model picker toward the right end of the row. You can change it later in the session.
  4. Ask. Type what you want and press Enter: Find a TODO comment and fix it, or Create a CLAUDE.md with instructions for this codebase.

Claude then edits files according to your permission mode. When it changes something, an indicator such as +12 -1 appears; click it to open the diff view, read each file, and comment on a line to have Claude revise it.

If a new session shows no environment control under the prompt box, you have an earlier layout of the app. Anthropic's desktop page has a "Check which layout you have" section that maps the controls for both.

Source: the Start your first session steps of Get started with the desktop app, read November 18, 2026.

Permission modes, and how much Claude does alone

The permission mode is shown in the row under the prompt box, and it is the single biggest difference between a session that asks constantly and one that does not.

  • Manual. Claude proposes each change and waits. You see a diff with approve and decline buttons.
  • Accept edits. Claude applies file edits without asking, for faster iteration.
  • Auto. A classifier reviews actions in the background and blocks the risky ones instead of asking you.
  • Plan. Claude proposes an approach and edits nothing, which is useful before a large refactor.

Auto is a judgement call by a model, not a rule you wrote. If your team needs something that cannot be skipped, it belongs in a deny rule or a hook in .claude/settings.json, not in a habit. The permission modes guide covers the CLI side of the same switch.

Sources: the permission-mode list in Get started with the desktop app, and Anthropic's best-practices page on auto mode being a classifier, read November 18, 2026.

Run several sessions at once

Click + New in the sidebar, or press Cmd+N on macOS or Ctrl+N on Windows, to start another session. Ctrl+Tab and Ctrl+Shift+Tab move between them.

Two sessions can share the window: hold Option on macOS or Alt on Windows and click a session in the sidebar for a split view. Hold Cmd or Ctrl and click for a new window.

This is the part worth setting up properly. By default Worktree is off, and every session works in the project folder itself, so two sessions editing the same files will overwrite each other. Turn Worktree on before you start a session in a git repository and that session gets its own copy of the project on its own branch.

Worktrees land in <project-root>/.claude/worktrees/ unless you set Worktree location in Settings. Files that git ignores, such as .env, are missing from each new worktree unless a .worktreeinclude file in the project root lists them. If many parallel sessions are your normal way of working, the multiple sessions guide covers the options across surfaces.

Sources: the parallel-sessions and worktree sections of Desktop application, read November 18, 2026.

Move a session between Desktop and the CLI

From a terminal, /desktop saves the current session, opens it in the desktop app and exits the CLI. Anthropic limits it to macOS and x64 Windows, signed in with a Claude subscription; it is not available with API-key authentication or on Bedrock, Google Cloud's Agent Platform or Microsoft Foundry.

From your shell, claude --desktop opens the app directly without starting a terminal session, and it needs Claude Code v2.1.285 or later. Add --continue for the latest conversation in the current directory, or --resume with the session ID that /status prints:

claude --desktop --resume <session-id>

Going the other way, type /resume in the desktop prompt box and pick a session you started from the CLI on this computer. It continues as the same session, not a copy, so claude --resume in the terminal still finds it afterwards.

Two limits on that: /resume works in local sessions only, not in SSH, WSL or cloud sessions, and it cannot move a session that is still open in a terminal or running in the background. Close it in the terminal first.

When /desktop cannot open the app at all, the message names the system command that failed and has its own page.

Sources: the "Coming from the CLI?" section of Desktop application and the /desktop entry on Anthropic's commands reference, read November 18, 2026.

What it does not do

  • It is not free. The Code tab needs Pro, Max, Ultra, Team or Enterprise. A free account gets an upgrade prompt where the session should be.
  • Linux is a beta. Anthropic ships it as apt and .deb packages for Ubuntu and Debian.
  • Scripting still belongs to the CLI. Anthropic's own advice is to use the desktop app to manage parallel sessions and review changes visually, and the CLI when you need scripting, automation or a terminal workflow.

If you are choosing between the desktop app and a session manager built on top of it, our Omniscio vs Claude Code desktop comparison puts the two side by side. This page stays on installing the app and running a first session.

Common mistakes

  • Starting two sessions in one folder and expecting them not to collide. Worktree is off by default. Turn it on, or run one session at a time in that folder.
  • Looking for Claude Code in the sidebar and missing it. It is the Code tab at the top; if the tabs show only icons, hover over one to see its name.
  • Signing in and not restarting. The app asks for an online sign-in in some cases, and the sign-in only takes effect after a restart.
  • Expecting .env to be in a worktree. Gitignored files stay behind unless .worktreeinclude names them.
  • Leaving a terminal session open and then trying to resume it in the app. Close it in the terminal first.

Where these answers come from

Common questions

Is the desktop app the same as the CLI?

Same engine, different interface. Anthropic says Desktop runs the underlying engine with a graphical interface, and the two share configuration and CLAUDE.md files, but each keeps its own session list.

Do I need Node.js?

No. The app ships with Claude Code inside it. Node.js matters only if you also install the CLI.

Can I keep using the terminal?

Yes, and Anthropic suggests it: scripting and automation stay a CLI job, while the app is for parallel sessions and reviewing changes visually.

Does a worktree cost disk space?

Yes. A new worktree is a fresh checkout, so its dependencies have to be installed there, and that install is the disk cost multiplied per session.