Claude Code Mac Desktop + Remote Control: A CLI User's Guide

The Claude Code Mac desktop app and the claude remote-control subcommand solve the same problem from opposite directions. The desktop app gives you a window with three tabs (Chat, Cowork, Code) and a workspace you can arrange around your code. Remote Control gives you the exact opposite: no window at all on your local machine, just a process that serves your local session to the Claude app on your phone or claude.ai/code in any browser.¹

If you came up on claude in a terminal, both surfaces look strange at first. Why would I want a GUI when the TUI is fine? Why would I want to drive my Mac from my phone when my Mac is right here? The answer to both is the same: your local environment is the part you can’t move. Filesystem, MCP servers (Yurei, Cloudflare, GitHub), Xcode, code-signing identities, your Yurei socket, your ~/.claude/projects/ history. All of it lives on the machine. The desktop app and Remote Control are two ways to get to that environment from somewhere else: another window, another device, a couch, a meeting.

This essay is the reference I wish I’d had when I switched. It covers the three modes (local CLI, cloud, local + Remote Control), how to set each up, what slash commands work where, the push-notification story, and the specific places the desktop app diverges from claude in a terminal. Honest about the limitations. No filler.

TL;DR

• Three modes that look similar from claude.ai/code but run very differently: Local CLI, Cloud session (claude --remote from terminal, the Remote environment in Desktop, or starting a new session at claude.ai/code), and Local + Remote Control. Only the first and third have access to your filesystem, MCP servers, and Xcode.¹²
• The Mac desktop app’s Code tab is a graphical Claude Code session: same engine as the CLI, same ~/.claude.json config, same CLAUDE.md, same MCP servers. But it has its own pane layout, side chats, and sessions sidebar.²
• claude remote-control (server mode) keeps the process running locally and lets you connect from any device. claude --remote-control is an interactive session with Remote Control enabled. /remote-control is the same thing as a slash command from inside an existing session.¹
• iOS app push notifications work via /config → “Push when Claude decides” (v2.1.110+). Claude pushes when a long task finishes or it needs your input.¹³
• For native macOS or iOS builds, Local CLI or Local + Remote Control is the only environment that actually works. Cloud sessions can’t run Xcode, can’t sign, can’t see your local Yurei socket.²

The Three Modes That Matter

Same claude.ai/code URL, same iOS app icon, three completely different runtime environments behind them.

1. Local CLI

This is claude in a terminal. Process runs on your Mac. Session lives at ~/.claude/projects/<project-path>/<session-id>.jsonl on disk, not in your Anthropic account.⁴ Your iPhone cannot see it. There is no remote surface.

What you get:

• Full filesystem access: ~/Projects, ~/.claude/, anywhere the user has read/write
• All your MCP servers: Yurei (/tmp/yurei.sock), Cloudflare, GitHub, Supabase, Playwright, etc.
• Xcode, simulators (xcrun simctl), code-signing identities, App Store Connect
• Plugins, skills, and hooks installed locally
• Voice mode (/voice)
• Every CLI flag (--worktree, --rc, --print, --output-format, etc.)

What you don’t get: any way to see or steer the session from another device.

For a Mac app build (Return, Get Bananas, Water, the apps in the App Intents and MCP server posts), Local CLI works perfectly. So does Local + Remote Control (covered in section 3 below): both keep the Claude process on your Mac, so both reach Xcode, simulators, and signing. The cloud session is what can’t run the Apple toolchain.

2. Cloud Session

This is claude --remote "task" from the terminal, selecting Remote when starting a desktop-app session, or visiting claude.ai/code on the web and starting a new session there. The Claude Code process runs on Anthropic’s managed cloud infrastructure, not your machine.² (Older docs and shell habits sometimes show & task as a shorthand for the same outcome; treat the explicit --remote flag as the canonical form.)

What you get:

• Persistence across machines and devices: visible from your iPhone, iPad, browser
• Continues running after you close the app or shut down your laptop
• Anthropic-managed environment, no local setup required
• Multi-repo support: cloud sessions can clone several GitHub repositories into the same workspace²

What you don’t get:

• No filesystem access to ~/Projects
• No local MCP servers (Yurei socket, local Cloudflare cache scripts, custom MCPs in .mcp.json won’t be reachable)
• No Xcode, no simulators, no signing
• Can’t see your ~/.claude/ config or skills (only what’s in the cloned repo’s .claude/)
• Can’t @mention files (the @-autocomplete pulls from the local project; cloud sessions don’t have one)²

Use case: a self-contained coding task with no Apple toolchain dependency. Open a PR review, run a test suite, refactor a file, write a Python script. Anything where the only things you need are git + standard Linux + Python/Node.

3. Local + Remote Control

This is the third option, the one most CLI users overlook. There are three ways to enable it: claude remote-control (server mode), claude --remote-control (or --rc, an interactive session with Remote Control on), or /remote-control from inside an existing session. The Claude Code process keeps running on your Mac with full local access, but it also registers with the Anthropic API so you can drive it from your iPhone, iPad, or browser.¹

What you get: everything Local CLI has, plus a phone you can prompt from. The conversation stays in sync across all connected devices. You can send a message from the Mac terminal, see it on the iPhone, type a follow-up on the iPhone, see it back in the terminal. The local process is still doing the work; your phone is just a window.

What you give up: a small, specific set of slash commands. The docs explicitly call out /mcp, /plugin, and /resume as local-only (they each open an interactive picker that needs a terminal). The docs explicitly list the commands that produce text output and work from mobile and web: /compact, /clear, /context, /usage, /exit, /extra-usage, /recap, /reload-plugins.¹

This is the answer for native macOS or iOS app builds. You get Xcode, you get MCP, you get the Yurei socket, and you get phone visibility.

Setting Up The Mac Desktop App

The desktop app and the CLI are not alternatives. They’re two clients for the same engine. You can run both simultaneously on the same machine, even on the same project. Each tracks its own session history, but they share CLAUDE.md, ~/.claude.json, MCP servers, hooks, and skills.²

Download from claude.com/download. Install. Sign in with your claude.ai account. The app has three tabs:²

• Chat for regular Claude conversations
• Cowork for Dispatch (long-running tasks, optionally messaged from your phone)
• Code for Claude Code with a graphical interface

The Code tab is what concerns us. Click + New session in the sidebar. Configure four things in the prompt area:²

1. Environment: Local (this Mac), Remote (Anthropic cloud), or SSH (a remote machine you manage)
2. Project folder: the directory Claude works in
3. Model: Sonnet 4.6, Opus 4.6, Opus 4.7, or others
4. Permission mode: Ask, Auto-accept edits, Plan, Auto, or Bypass permissions

Type your prompt, press Enter. From here it feels like a chat app: messages stack, tool calls render as collapsible cards, and a diff stats indicator (+12 -1) appears when files change. Click the indicator to open the diff viewer with file-by-file review and line-level comments.²

For local sessions, the @ key in the prompt box autocompletes file paths from your project: same as the CLI’s @ mention. For remote sessions, @ is disabled because the cloud process can’t see your local files.²

Requirements Before You Start

Four preconditions for any Remote Control session:¹

• Claude Code v2.1.51 or later (check with claude --version).
• Subscription: Pro, Max, Team, or Enterprise. API keys are not supported. On Team and Enterprise, an admin must enable the Remote Control toggle in claude.ai/admin-settings/claude-code first.
• Authentication: run claude and use /login (claude.ai option) if you haven’t already. Inference-only tokens from claude setup-token or the CLAUDE_CODE_OAUTH_TOKEN env var will not work.
• Workspace trust: run claude in your project directory at least once and accept the workspace-trust dialog.

Four Ways To Start A Remote Control Session

The current docs list four invocation surfaces (three from the CLI plus a VS Code command). The Mac desktop app is not a Remote Control host; Remote Control is hosted by claude (CLI) or the VS Code extension.¹

Server mode: claude remote-control

cd ~/Projects/blakecrosley.com
claude remote-control

The terminal becomes a server. No interactive prompt. It displays a session URL and (if you press spacebar) a QR code. Connect from another device by opening the URL or scanning the QR. While the session is active, the terminal shows connection status and tool activity.

Useful flags:¹

• --name "My Project": custom session title visible at claude.ai/code
• --remote-control-session-name-prefix <prefix>: overrides the auto-name (default is your machine’s hostname, producing names like myhost-graceful-unicorn)
• --spawn same-dir (default): all sessions share the current working directory
• --spawn worktree: each session gets its own git worktree (requires a git repo); press w at runtime to toggle between same-dir and worktree
• --spawn session: single-session mode, rejects additional connections; set at startup only
• --capacity N: max concurrent sessions (default 32, can’t combine with --spawn=session)
• --sandbox / --no-sandbox: toggle filesystem and network isolation (off by default)

Server mode is the right choice when you want to start the session and walk away. The terminal is a daemon now, not a workspace.

Interactive: claude --remote-control

claude --remote-control
# or shorter
claude --rc

Same as a normal interactive session, but with Remote Control turned on. You can type messages locally and from claude.ai/code or the iOS app. The conversation stays in sync. Optional: claude --rc "Project Name".

Use this when you want to keep working at the terminal but also want phone visibility. It’s the most common case.

Slash command: /remote-control

Already in a session and want to enable Remote Control on this conversation specifically? Type /remote-control (or /rc). The current conversation history carries over and a session URL + QR appear. Pass a name: /remote-control My Project.

The --verbose, --sandbox, and --no-sandbox flags don’t work with the slash form: only with claude remote-control (server mode).

VS Code extension

In the Claude Code VS Code extension, type /remote-control (or /rc) in the prompt box, or open the command menu with / and select it. Requires Claude Code v2.1.79 or later.¹ A banner appears above the prompt box showing connection status. Click Open in browser to jump straight to the session, or find it in the session list at claude.ai/code. Disconnect by clicking the close icon on the banner or running /remote-control again.

The VS Code command does not accept a name argument and does not display a QR code. The session title is derived from the conversation history or first prompt.

Always-on: /config → “Enable Remote Control for all sessions”

If you want every interactive claude session to register a remote session by default, run /config and toggle Enable Remote Control for all sessions to true.¹ Each interactive process gets one remote session. Multiple instances → multiple sessions. For multiple concurrent sessions from a single process, server mode is still the right tool.

The Push Notification Story

Push to your phone when something interesting happens. The setup has four steps:¹³

1. Install the Claude app for iOS or Android. Inside Claude Code, /mobile shows a download QR code if you don’t already have it.
2. Sign in with the same Claude account you use for Claude Code in the terminal.
3. Accept the OS notification permission prompt.
4. In the terminal, run /config and enable Push when Claude decides (v2.1.110+).

After that, Claude decides when to push. Two cases trigger it: a long-running task finishing, or Claude needing your input to continue. You can also request one explicitly in your prompt: notify me when the tests finish. There is no per-event configuration: it’s on or off.

If you toggle the setting on but don’t see notifications, the most common fix: open the Claude app on your phone so it can refresh its push token. The /config screen shows No mobile registered until that happens. iOS Focus modes and Android battery-optimization can also delay or suppress delivery; check Settings → Notifications → Claude on iOS, or exempt the Claude app from battery optimization on Android.¹

For background context: a separate push-notification tool (also v2.1.110+) lets Claude itself decide to send notifications during a session, not just at task end. It pairs with the same Remote Control surface, no extra setup.³

Slash Commands That Work Remotely

This is the part most CLI users care about. When you’re typing on your phone instead of your terminal, what works?

Work from any connected client (terminal, browser, iOS app):¹

• /compact, /clear: context management
• /context, /usage, /extra-usage: usage and context inspection (v2.1.113+ added Remote Control support for /extra-usage)
• /exit, /recap, /reload-plugins
• All non-picker text input (regular prompts, normal slash commands that produce text output)

Local-only (terminal only):¹

• /mcp: opens an interactive picker
• /plugin: opens an interactive picker
• /resume: needs to render a session list with selection UI

The pattern: anything that requires a list-with-keyboard-selection in the terminal stays local. Anything that’s text-in / text-out works from mobile or web.

Some commands have version-specific Remote Control support. /extra-usage only works from Remote Control clients in v2.1.113 and later: earlier versions silently failed.⁵ Worth checking claude --version if a command behaves differently from your phone than your Mac.

Permission Modes Are A Little Different

The desktop app has five permission modes; the CLI has those five plus dontAsk:²

dontAsk is CLI-only. Everything else maps to a UI control next to the send button. The CLI flag --dangerously-skip-permissions corresponds to Bypass permissions, which you have to opt into via Settings → Claude Code → “Allow bypass permissions mode”.²

Auto mode requires Claude Sonnet 4.6, Opus 4.6, or Opus 4.7 on Team/Enterprise/API; Opus 4.7 on Max. Not available on Pro plans or third-party providers.²

The Cowork Tab and Dispatch (Adjacent, Not The Same)

The desktop app’s Cowork tab is a different feature with overlapping ergonomics. Dispatch is “message a task to Claude from your phone, and it decides whether to handle the task itself or spawn a Code session on your Mac.”²

Pairing happens once: install the Claude mobile app, link it to your Mac via the Cowork tab. After that, you can text Dispatch a task (“fix the login bug, open a PR”) and it routes the work. Bug fixes, dependency updates, test runs, and PR creation typically end up as Code sessions on your Mac with a Dispatch badge in the sidebar. Research, document editing, and spreadsheet work stay in Cowork.

App-approval permissions for Dispatch-spawned Code sessions expire after 30 minutes (vs. lasting the session for regular Code sessions), so a long-running Dispatched task may re-prompt you for app permissions you’d already approved.²

Dispatch needs Pro or Max. Not available on Team or Enterprise.

This is not Remote Control. Dispatch is “send Claude a task to run autonomously”; Remote Control is “drive a session that’s already running.” They are documented as independent surfaces: Remote Control is hosted by the CLI or VS Code, Dispatch spawns Desktop Code sessions: and the docs do not currently describe combining them. Pick one based on whether you want to delegate (Dispatch) or steer (Remote Control).

What Carries Over From The CLI

The desktop app reads the same configuration files as the CLI:²

• CLAUDE.md and CLAUDE.local.md in your project
• ~/.claude.json (global) and .mcp.json (per-project) for MCP servers
• Hooks and skills defined in ~/.claude/settings.json or .claude/settings.json
• Permission rules in settings.json
• All available models

CLI flag → desktop equivalent:²

One configuration footgun worth flagging: the Claude Desktop chat app (the chat-only client at claude_desktop_config.json) and Claude Code Desktop (the dev client we’re talking about) are different products. MCP servers configured for the chat app won’t appear in the Code tab. Code reads ~/.claude.json and .mcp.json, not claude_desktop_config.json.²

CLI → Desktop: When To Move

The desktop app shines for three things the CLI doesn’t do well:²

1. Parallel sessions side-by-side: each Code-tab session gets its own Git worktree at <project-root>/.claude/worktrees/. Cycle with Ctrl+Tab / Ctrl+Shift+Tab. Run a refactor in one session while a test suite runs in another, and review them visually rather than by ANSI escape codes.
2. Visual diff review: click the +12 -1 indicator. Comment on lines. Submit comments back to Claude with Cmd+Enter. Beats reading inline diffs in a terminal.
3. Embedded preview pane: Claude can start a dev server and open the running app in an embedded browser, take screenshots, click around, and verify its own changes. Auto-verify is on by default per project (toggle in .claude/launch.json or via the Preview dropdown).²

The CLI still wins for: scripting (--print, --output-format), automation (cron jobs, CI), tmux/screen workflows, and anything that needs dontAsk permission mode.

To move a CLI session into Desktop without losing context, run /desktop in the terminal. Saves the session, opens it in the desktop app, exits the CLI.²

Limitations And Footguns

Real ones, from the docs:¹

• One remote session per interactive process. Outside server mode, each claude invocation supports one remote session. Need multiple? Use claude remote-control (server mode).
• Local process must keep running. Remote Control is hosted by the claude CLI process or the VS Code extension. Close the terminal, quit VS Code, or kill the claude process and the remote session ends. There is no detached-from-terminal mode.¹
• Network outage > 10 minutes terminates the session. The Mac can be awake but unable to reach the network for 10 minutes; the process exits and you have to restart.
• Ultraplan disconnects Remote Control. Both occupy the claude.ai/code surface and only one can be connected at a time.
• Auto mode requires recent models. Opus 4.7 on Max; Sonnet 4.6, Opus 4.6, or Opus 4.7 on Team/Enterprise/API. Not on Pro.
• API keys and inference-only tokens won’t work. Remote Control requires a full-scope claude.ai OAuth login. If ANTHROPIC_API_KEY is set, unset it. If you authenticated via claude setup-token or CLAUDE_CODE_OAUTH_TOKEN, run claude auth login to refresh.
• Team and Enterprise admins must enable it. Off by default. The toggle is at claude.ai/admin-settings/claude-code → Remote Control. Some data-retention configurations make the toggle unavailable.

The most common “why isn’t this working” failure: the user is signed in with an inference-only token. The error “Remote Control requires a full-scope login token” maps to that case. Fix: claude auth login and pick the claude.ai option.¹

Other troubleshooting cases worth knowing

The official docs cover several more failure modes that cost a beginner real time. Distilled:¹

• “Remote Control requires a claude.ai subscription”: you’re not authenticated with claude.ai. If ANTHROPIC_API_KEY is set, unset it first, then claude auth login.
• “Unable to determine your organization for Remote Control eligibility”: cached account info is stale. Run claude auth login to refresh.
• “Remote Control is not yet enabled for your account”: check for CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, or CLAUDE_CODE_USE_FOUNDRY in your environment. Remote Control requires claude.ai authentication; third-party providers won’t work. Unset and /logout then /login.
• “Remote Control is disabled by your organization’s policy”: three causes per the docs: (a) you’re on an API key or Console account (use claude.ai OAuth), (b) Team/Enterprise admin hasn’t enabled the toggle, (c) the admin toggle is grayed out due to a data-retention configuration that’s incompatible with Remote Control (contact Anthropic support).
• “Remote credentials fetch failed”: re-run with --verbose to see the underlying error: claude remote-control --verbose. Usually a not-signed-in case, a firewall blocking outbound HTTPS to the Anthropic API on 443, or an earlier session-creation failure (look for Session creation failed: see debug log).
• Workspace trust dialog: if Remote Control fails to start with no obvious error, run claude in the project directory at least once and accept the workspace-trust dialog. This step is required before Remote Control will register the session.

A Decision Tree For CLI Users

Faced with a real task, pick the mode based on what the work needs:

Does the work need Apple toolchain (Xcode, simulators, signing)?
├── YES → Local CLI or Local + Remote Control
│         (cloud cannot reach the toolchain)
│
└── NO → Does it need your local MCP servers (Yurei, Cloudflare, etc.)?
         ├── YES → Local CLI or Local + Remote Control
         │
         └── NO → Do you need to monitor or steer it from your phone?
                  ├── YES → Local + Remote Control, OR Cloud session
                  │         (cloud is better if the task is multi-hour)
                  │
                  └── NO → Local CLI is fine

Mac/iOS app development: what most of my apps do: falls in the top branch every time. Cloud sessions can’t xcodebuild, can’t talk to a simulator, can’t sign. For Get Bananas’s MCP extension, my Yurei-powered census scripts, or the Apple Ecosystem cluster work, the Apple toolchain dependency is unavoidable. Local + Remote Control is the only path that gives me both that toolchain and a phone-visible surface.

FAQ

Can I run the CLI and the desktop app at the same time on the same project?

Yes. They share configuration (CLAUDE.md, ~/.claude.json, MCP servers, hooks, skills) but maintain separate session histories.² You can have a claude session in iTerm and a Code-tab session in the desktop app, both pointed at the same ~/Projects/blakecrosley.com, both writing to git. Be careful with parallel writes if you’re not using worktrees.

What happens to a Remote Control session when my Mac sleeps?

The session reconnects automatically when your machine comes back online. If your Mac is awake but unable to reach the network for more than ~10 minutes, the session times out and you have to start a new one with claude remote-control.¹

Does Remote Control work with & task (background) syntax?

& task and Remote Control are different surfaces. & task sends work to a cloud session. Remote Control connects you to a local session from another device. They can both surface in claude.ai/code’s session list, but the cloud one runs on Anthropic infrastructure and the Remote Control one runs on your machine.¹

Can I use Remote Control with a third-party provider (Bedrock, Vertex, Foundry)?

No. Remote Control requires claude.ai authentication. If you have CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, or CLAUDE_CODE_USE_FOUNDRY set, the eligibility check will fail with “Remote Control is not yet enabled for your account”. Unset them and re-run.¹

What’s the difference between --remote-control and claude remote-control?

claude --remote-control (or --rc) starts a normal interactive session in your terminal, with Remote Control enabled. You can type locally and from another device. claude remote-control (no flag, subcommand) is server mode: the terminal becomes a server with no local prompt, just connection status. Both create one remote session by default; server mode can serve multiple via --capacity or --spawn.¹

Does the desktop app have skills, plugins, and hooks like the CLI?

Yes. They’re the same skills, plugins, and hooks. The desktop app reads ~/.claude/settings.json and project-level .claude/settings.json like the CLI does. Click the + button next to the prompt box to browse installed plugins and skills. Plugins are not available in remote (cloud) sessions but work fine in local desktop sessions.²

Why doesn’t /mcp work from my phone?

/mcp opens an interactive picker that needs a terminal-only UI for selection. It’s local-only. The same is true of /plugin and /resume.¹ Anything that produces text output (/compact, /clear, /context, /usage, /extra-usage, /exit, /recap, /reload-plugins) works from mobile and web.

Is there a free tier or does this all require a subscription?

Remote Control is available on Pro, Max, Team, and Enterprise plans. API keys are not supported. On Team and Enterprise, an admin must enable the Remote Control toggle in claude.ai admin settings before users see the feature.¹ The desktop app itself is free to download but requires a claude.ai login to use.

The shortest version: Local CLI is the substrate. The desktop app is a graphical client for the same substrate. /remote-control is the bridge that makes the substrate reachable from your phone. Pick by what the work needs and where you happen to be.

References