dev-skills

Appearance

Claude Code Remote Workflows ​

Control Claude Code sessions remotely from your iPhone, your couch, or anywhere away from your desk. Three workflows, from simplest to always-on.

When to use ​

Use remote workflows when you want to monitor, continue, or start Claude Code sessions from the Claude app on your phone — while the actual work happens on your Mac against your real files and tools.

First: Enable remote control globally ​

Do this once. Every Claude Code session you start afterward — in the VS Code extension, in the terminal, anywhere — automatically registers and appears in the Claude app on your phone.

  1. Mac, any Claude Code session: Type /config
  2. Set "Enable Remote Control for all sessions" to true

No per-session /remote-control needed after this.

Known bug: This setting can reset to false on new sessions despite being saved correctly in ~/.claude.json (claude-code#29929). If sessions stop appearing on your phone, check /config again. To detect this programmatically, read ~/.claude.json and verify the enableRemoteControl key is true:

sh
cat ~/.claude.json | grep -o '"enableRemoteControl":[^,}]*'
# expected: "enableRemoteControl":true

If the value is false or missing, re-enable it via /config.

Workflow 1: Check in on any session from your phone ​

The simplest workflow. Work on your Mac as normal, then pick up the session on your phone when you walk away.

Start a session ​

Mac, VS Code Extension: Work with Claude Code as normal — the session auto-registers.

Mac, Terminal: Same — run claude and start working.

Connect from your phone ​

iPhone, Claude App (Code tab): All active sessions appear in the session list. A computer icon with a green dot means the session is online. Tap a session to connect — same files, same MCP servers, same context.

Name sessions ​

Name your sessions before you walk away. Named sessions are much easier to find than auto-generated summaries.

sh
# From within a Claude Code session
/rename eval-run-march

Resume on your Mac ​

VS Code Extension: Click the Past Conversations dropdown at the top of the Claude Code panel, find the session by name, and continue it.

Terminal:

sh
# Interactive picker (searchable)
claude --resume

# Continue the most recent session
claude -c

Workflow 2: Start new sessions from your phone ​

Spawn new Claude Code sessions from your phone, each running on your Mac against your real project files.

One-time setup ​

Mac, Terminal:

sh
cd /path/to/your/project    # must be a git repo for worktree mode
claude remote-control --name "My Project" --spawn worktree

Leave it running. Use tmux to survive closing the terminal window:

sh
tmux new -s claude-rc
cd /path/to/your/project
claude remote-control --name "My Project" --spawn worktree
# Ctrl-b d to detach

Start sessions from your phone ​

iPhone, Claude App (Code tab): Create a new local session — it spawns on your Mac against your real files. Each session gets its own git worktree, so they don't conflict. Spin up multiple sessions in parallel.

Name spawned sessions ​

The --name flag sets a base name visible in the session list. For individual sessions started from your phone, rename them from within the session:

sh
/rename tfidf-eval
/rename batch-api-refactor

Resume on your Mac ​

Same as Workflow 1 — use the Past Conversations dropdown in the VS Code extension or claude --resume in the terminal.

Requirements ​

  • Claude Code v2.1.74+
  • Mac awake and online
  • claude remote-control process still running

Limitation ​

If your Mac reboots or the process dies, you walk back to the desk. Workflow 3 fixes this.

Workflow 3: Always-on daemon ​

Only needed if you use Workflow 2 (spawning new sessions from your phone) and want it to survive Mac reboots. If you only check in on existing sessions (Workflow 1), the global setting handles everything — skip this.

Same as Workflow 2, but a launchd agent keeps the claude remote-control process alive across reboots.

Create the wrapper script ​

Mac, create ~/bin/claude-rc.sh:

bash
#!/bin/bash
cd /path/to/your/project
exec /Users/YOUR_USERNAME/.local/bin/claude remote-control \
  --name "My Project" \
  --spawn worktree \
  --capacity 4

Confirm your binary path first with which claude (likely ~/.local/bin/claude). Then make the script executable:

sh
chmod +x ~/bin/claude-rc.sh

Create the launchd plist ​

Mac, create ~/Library/LaunchAgents/com.claude.remote-control.plist:

xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.claude.remote-control</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>/Users/YOUR_USERNAME/bin/claude-rc.sh</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/claude-rc.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/claude-rc.err</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/usr/local/bin:/usr/bin:/bin:/Users/YOUR_USERNAME/.local/bin</string>
    <key>HOME</key>
    <string>/Users/YOUR_USERNAME</string>
  </dict>
</dict>
</plist>

Load the agent ​

sh
launchctl load ~/Library/LaunchAgents/com.claude.remote-control.plist

Now it starts on login and restarts on crash. Your phone can spin up new sessions anytime your Mac is awake.

Stop the agent ​

sh
launchctl unload ~/Library/LaunchAgents/com.claude.remote-control.plist

Known rough edges ​

  • Each reboot creates a new session ID; old ones linger in the app until they time out (claude-code#29748)
  • No way to reconnect to a previous session after restart — a --resume flag for daemon use is requested but doesn't exist yet
  • Not officially supported — Anthropic hasn't shipped a --headless / --daemon flag

Issues to watch ​

  • claude-code#30447 — --headless daemon mode. Requests daemonizable remote control: no TTY dependency, --resume to reconnect after restart, remote permission handling via the phone app. Would make Workflow 3 first-class instead of DIY.
  • claude-code#30905 — Remote Control for VS Code chat mode. Would let the extension session itself be the remote-controllable session natively, not just via the global config workaround.
  • claude-code#29748 — Persistent session IDs. Would fix stale-session clutter after reboots.
  • claude-code#29929 — Global config resets. The "Enable Remote Control for all sessions" setting sometimes resets to false.