Control Claude Code CLI from your phone browser, anywhere. Continue sessions seamlessly between Mac and phone.
Your Mac runs a Go server that wraps Claude Code in a pseudo-terminal. Your phone reaches it over a Cloudflare Tunnel (no VPN, no port forwarding, works on mobile data) and interacts via a mobile-optimized chat UI. Ask Claude to "handoff to phone" β scan QR to continue your session.
- Session handoff β ask Claude "handoff to phone", scan QR, continue on phone
- Two handoff modes β attach to running terminal (like tmux) or continue with full conversation history
- MCP integration β claude-remote runs as both web server and MCP server for Claude Code
- Folder picker β browse Desktop/Downloads/Documents, choose working directory
- Chat UI β native text input with IME support, colored terminal output with smooth native scrolling
- Quick actions β Enter, Accept (y), Reject (n), Esc, Ctrl+C buttons for Claude's prompts
- Several agents at once β β° Sessions: start Claude, Codex, OpenCode, Gemini (or any CLI in config
agents) side by side, each in its own git worktree andcr/<name>branch so they never edit the same checkout; live state per session (working / needs you / done) - Push notifications β the phone buzzes when a session needs you or finishes (Claude Code hooks; other agents via the OSC 7501 status sequence). On iPhone: Share β Add to Home Screen, open it from there, β° β π Notify me
- Review and ship β Β± Changes: changed files with line counts, per-file diffs, β¨ commit message drafted by
claude -p, Commit, Commit & push, Open pull request (gh) - Plan usage β 5-hour and weekly Claude plan usage in β° Sessions, read from the official status line data (your own status line keeps working)
- Automations β prompts that start a session hourly, daily or weekly (nightly dependency bumps, weekly triage), notifying you like any session
- Mac screen control β view and drive the whole Mac desktop from the phone (noVNC over macOS Screen Sharing), with a paste bar that handles Vietnamese and other non-ASCII text
- QR auth β scan once, JWT cookie lasts 90 days and renews itself while you keep using it
- Cloudflare Tunnel β HTTPS from anywhere with nothing installed on the phone; Tailscale/LAN still supported
- Self-diagnosing β
claude-remote doctorchecks every link in the chain and prints the exact fix - Auto-start β launchd keeps server running on Mac boot; the tunnel restarts itself if it drops
# Prerequisites: Go 1.25+, cloudflared (brew install cloudflared)
make build
./claude-remote setup # generates the auth secret
./claude-remote serve # starts the server + tunnelIn another terminal:
./claude-remote qr # QR code with the live tunnel URLScan it with your phone β pick a folder β start Claude. If anything fails:
./claude-remote doctorSet the tunnel block in ~/.claude-remote/config.json:
| Mode | URL | Setup | Notes |
|---|---|---|---|
quick (default) |
random *.trycloudflare.com |
none | URL changes whenever cloudflared restarts, so re-pair with claude-remote qr |
named |
your own stable hostname | Cloudflare account + tunnel token | URL never changes, so the phone stays paired |
off |
https://<host>:8822 |
Tailscale or LAN | Requires a valid TLS cert; server binds 0.0.0.0 |
With a tunnel enabled the server binds 127.0.0.1 only β cloudflared is the sole way in, and /mcp plus the pairing endpoints stay on the loopback listener where the tunnel cannot reach them.
brew install cloudflared # tunnel client
make install # build, sign, copy binary + static/ to ~/bin, load launchd
# Set the absolute path to the claude binary (launchd's PATH is minimal):
# ~/.claude-remote/config.json β "claude_path": "/Users/yourname/.local/bin/claude"
claude-remote setup # first time only: generate the auth secret
claude-remote qr # pair the phone
# Register MCP with Claude Code (one-time, user scope)
claude mcp add --transport http -s user claude-remote http://127.0.0.1:8823/mcpmake install templates launchd/com.claude-remote.plist with your home directory and reloads the service with launchctl bootout + bootstrap (plain load keeps the old plist running). Other targets:
| Target | What it does |
|---|---|
make restart |
Reload the service without rebuilding |
make logs |
tail -f ~/.claude-remote/server.log |
make uninstall |
Unload the service, remove plist and binary |
launchd starts the server with no TERM/LANG and a minimal PATH. The server fills those in for the Claude process itself (TERM=xterm-256color, LANG=en_US.UTF-8, ~/.local/bin, ~/bin and Homebrew dirs prepended to PATH), but claude_path in config.json must still be absolute.
Go signs binaries ad hoc, so each rebuild looks like a brand-new app and macOS asks again for Desktop/Documents (or Full Disk Access). make install signs with a claude-remote-signing identity when one exists. Create it once:
cat > /tmp/cs.cnf <<'EOF'
[req]
distinguished_name = dn
x509_extensions = ext
prompt = no
[dn]
CN = claude-remote-signing
[ext]
basicConstraints = critical,CA:false
keyUsage = critical,digitalSignature
extendedKeyUsage = critical,codeSigning
EOF
openssl req -x509 -newkey rsa:2048 -nodes -days 3650 -config /tmp/cs.cnf -keyout /tmp/cs.key -out /tmp/cs.pem
openssl pkcs12 -export -legacy -inkey /tmp/cs.key -in /tmp/cs.pem -name claude-remote-signing -out /tmp/cs.p12 -passout pass:tmp
security import /tmp/cs.p12 -k ~/Library/Keychains/login.keychain-db -P tmp -T /usr/bin/codesign
rm /tmp/cs.cnf /tmp/cs.key /tmp/cs.pem /tmp/cs.p12The certificate does not need to be trusted. Grant the permissions one last time after the first signed install.
Windows 10 1809+ / Windows 11 is supported. Claude runs in a ConPTY pseudo-console instead of a Unix pty; everything else (tunnel, QR pairing, handoff, MCP, file browser, history, uploads) works the same.
winget install GoLang.Go
winget install --id Cloudflare.cloudflared
# Build, copy claude-remote.exe + static\ to ~\bin, register the logon task
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
~\bin\claude-remote.exe setup
~\bin\claude-remote.exe qr
~\bin\claude-remote.exe doctor # if anything fails
claude mcp add --transport http -s user claude-remote http://127.0.0.1:8823/mcp- Auto-start is a Task Scheduler task named
claude-remote(at logon, in your desktop session). It runsconhost.exe --headless claude-remote.exe serve --log ~\.claude-remote\server.log, so no console window appears.claude-remote installre-registers and restarts it;claude-remote uninstallstops and removes it. claude_pathmay point atclaude.exe(native installer,~\.local\bin) orclaude.cmd(npm,%APPDATA%\npm); both directories are added to the childPATH.- Screen page needs a VNC server running as a service on
127.0.0.1:5900, e.g. TightVNC (winget install GlavSoft.TightVNC), withAllowLoopback=1andLoopbackOnly=1underHKLMSOFTWARETightVNCServer. The login asks only for the VNC password; when the PC is locked the page offers an unlock form (Ctrl+Alt+Del, then your Windows password or PIN). The modifier button becomes Ctrl, the paste bar uses Ctrl+V, π runsLockWorkStation. Smooth video mode (ScreenCaptureKit) is macOS only, so the page stays on VNC. - HEIC uploads are not converted (no
sips); phones usually send JPEG anyway.
The server can wake other machines on its LAN, e.g. a sleeping Mac while it runs on an always-on Windows PC. List them in ~/.claude-remote/config.json and restart the server:
"wake": [
{"name": "macbook", "mac": "aa:bb:cc:dd:ee:ff"},
{"name": "nas", "mac": "11:22:33:44:55:66", "broadcast": "192.168.1.255"}
]- Phone: a β» Wake button appears in the header; pick the machine.
- Claude Code: "wake my macbook" (MCP tool
wake). - Terminal:
claude-remote wake macbook, orclaude-remote wake aa:bb:cc:dd:ee:fffor a machine not in the list.
The packet goes to 255.255.255.255 and to the broadcast address of every LAN interface (port 9), or only to broadcast when set. Only configured machines can be woken from the phone. The target must have Wake-on-LAN enabled: on a Mac, System Settings β Battery/Energy β "Wake for network access" (works on Ethernet and, for many Macs, Wi-Fi while sleeping, not when shut down); on a PC, the NIC's "Wake on Magic Packet" plus BIOS WoL. The sender must be on the same LAN: Tailscale and Cloudflare cannot carry it.
The killer feature: continue Claude Code sessions on your phone.
Mac (Claude Code) Phone (browser)
ββββββββββββββββββββββββ
β > working on feature β
β > "handoff to phone" β
β β
β ββββββββββββββββ β Scan QR
β ββββββββββββββββ β βββββββββββββΊ ββββββββββββββββββββ
β ββββββββββββββββ β β Continue from β
β β β computer β
β Scan to continue β β β
β on phone β β [π Attach] β
ββββββββββββββββββββββββ β [π Continue] β
β [π New folder] β
ββββββββββββββββββββ
Attach β connect to the same running terminal. See live output, type into the same session. Like tmux attach.
Continue β start a new Claude session with --continue flag. Gets full conversation history from the previous session in the same directory.
- Ask Claude to "handoff to phone" (Claude calls the MCP
handofftool) - Claude generates a QR code with a one-time token (expires 15 min)
- Scan with phone camera
- Phone opens claude-remote web UI, auto-authenticates via token
- Choose mode: attach or continue
- Start working on phone
The MCP handoff tool is registered globally. In any Claude Code session (CLI, VS Code, Cursor), just ask:
- "handoff to phone"
- "generate QR for phone"
- "transfer session to phone"
Claude will call the handoff MCP tool and display the QR code.
In Claude Code CLI, the /handoff skill also works (requires the skill file in .claude/skills/ or ~/.claude/skills/).
The π₯ Screen button in the header opens /screen.html: a full view of the Mac desktop you can tap, drag and type into.
- On the Mac: System Settings β General β Sharing β Screen Sharing β on.
- On the phone: tap π₯ Screen and log in with your macOS username and password (the login runs inside the browser; the server only pipes bytes to
127.0.0.1:5900).
Video mode (π₯, the default) streams one display as H.264 over WebRTC, which is far smoother than VNC with large or multiple monitors; Screen Sharing still carries taps and keys, so the macOS login above is still needed. π₯ switches display, VNC switches back to plain Screen Sharing. A locked Mac cannot be captured, and its lock screen over VNC (both displays at full size) is too slow to use, so the page stops fetching pixels and just asks for the Mac password, types it on the lock screen (ASCII only, never stored) and returns to video once unlocked. Show the lock screen fetches it over VNC when you need to see it. The first time, macOS asks to allow claude-remote under Privacy & Security β Screen & System Audio Recording. WebRTC uses host candidates only: the phone must reach the Mac directly (Tailscale or the same Wi-Fi), not just through Cloudflare.
The key bar has β¨ (live key-by-key typing), β€’ Fit, a sticky β modifier, Esc, Tab, Enter, Backspace and arrows. Screen Sharing drops non-ASCII keystrokes, so for Vietnamese or any accented text use the text bar at the bottom: Paste puts the text on the Mac clipboard and presses βV, Enter β΅ pastes it and presses Enter (or just presses Enter when the bar is empty).
Only needed if you turn the Cloudflare tunnel off. Tailscale creates a private VPN mesh so your phone can reach your Mac from anywhere β no port forwarding, no public IP needed.
- Mac: Download from tailscale.com/download or
brew install tailscale - Phone (iOS): App Store β search "Tailscale"
- Phone (Android): Play Store β search "Tailscale"
Sign in with the same account on both devices.
Go to Tailscale admin console β enable MagicDNS. This gives your Mac a stable hostname like macbook-pro.tail1234.ts.net.
# Get your Mac's Tailscale hostname
tailscale status
# Generate TLS cert (requires sudo)
sudo tailscale cert <your-hostname>.ts.net
# Copy to config dir:
mkdir -p ~/.claude-remote
sudo cp ~/Desktop/<your-hostname>.ts.net.crt ~/.claude-remote/
sudo cp ~/Desktop/<your-hostname>.ts.net.key ~/.claude-remote/
sudo chown $(whoami) ~/.claude-remote/*.key ~/.claude-remote/*.crtOn your phone (connected to Tailscale):
- Open Safari/Chrome β
https://<your-hostname>.ts.net:8822/health - Should show
{"status":"ok","version":"0.1.0"}
Phone (chat UI / screen page)
β HTTPS + WebSocket via Cloudflare Tunnel (or Tailscale HTTPS :8822 in mode off)
cloudflared β 127.0.0.1:8822
Mac (Go server)
ββ pseudo-terminal β Claude Code CLI
ββ /ws/vnc β 127.0.0.1:5900 (macOS Screen Sharing)
ββ WebRTC (UDP, direct) β claude-remote-screencap (ScreenCaptureKit β H.264)
Claude Code (MCP client)
β JSON-RPC over HTTP (:8823, localhost only)
Mac (Go server /mcp endpoint)
β generates QR + handoff token
Two listeners:
- Port 8822 β web UI for the phone; static files public, API/WS protected by JWT. Plain HTTP on
127.0.0.1behind the tunnel, HTTPS on all interfaces in modeoff - Port 8823 (HTTP, 127.0.0.1 only) β MCP endpoint for Claude Code, plus the pairing/status endpoints used by
qranddoctor
| Command | Description |
|---|---|
setup |
Generate the auth secret (first time) |
serve |
Start server + tunnel (foreground) |
qr |
Print a pairing QR for the running server (alias pair) |
doctor |
Check every link in the connection chain and print fixes |
status |
Show running state, tunnel state, phone URL |
revoke |
Regenerate secret, invalidate all sessions |
install |
Install launchd plist + load |
uninstall |
Unload + remove launchd plist |
version |
Print version |
Old cookie with invalid signature (or revoke was run). Scan a fresh QR from claude-remote qr; if that still fails, clear cookies for the site in the phone browser.
Quick tunnels get a new *.trycloudflare.com URL every time cloudflared restarts. Run claude-remote qr again, or switch to a named tunnel for a stable hostname. qr refuses (503) while the tunnel is still coming up β wait a few seconds and retry.
Claude process failed to start. Check:
~/.claude-remote/config.jsonβclaude_pathmust be absolute (e.g.,/Users/you/.local/bin/claude)~/.claude-remote/server.logβ look for "Claude start failed" or "claude process exited"claude auth statusβ verify Claude Code is authenticated
- Run
claude-remote doctor - Check server logs:
make logsβ every request is logged asREQ <method> <path> β <status> - Mode
offonly: check Tailscale on both devices (tailscale status) andhttps://<hostname>.ts.net:8822/health
The server starts Claude with --settings {"tui":"default"} because the fullscreen TUI has no scrollback. If you start Claude yourself with "tui": "fullscreen", attaching from the phone won't scroll.
Enable System Settings β General β Sharing β Screen Sharing on the Mac.
The binary is ad-hoc signed. Create the claude-remote-signing identity (see Stop macOS re-asking for permissions), make install, and grant access once more.
MCP uses HTTP on port 8823 (localhost only). Verify:
curl http://127.0.0.1:8823/health
# Should return {"status":"ok"}- Go β single binary, no runtime deps
- cloudflared β Cloudflare Tunnel (default); Tailscale optional
- noVNC β Mac screen in the browser, over macOS Screen Sharing
- MCP β Streamable HTTP (JSON-RPC) for Claude Code integration
- xterm.js β ANSI processing (hidden, cell-by-cell rendering)
- Vanilla JS β no framework, no build step
If you find this useful, consider buying me a coffee: