How to Use Claude Code --teleport to Hand Off Sessions to Your Phone

When you close your laptop or walk out of the office, every Claude Code session running in your terminal gets a SIGHUP signal and exits — taking all in-progress context with it. Claude Code now ships two official mechanisms to break this laptop dependency: web sessions with --teleport for cloud-based persistence, and Remote Control for local sessions you can steer from any device. This tutorial walks through both, plus a community DIY approach, and closes with how to eliminate the laptop dependency entirely rather than just bridge it.

TL;DR

To keep a Claude Code session alive when you leave your desk:

• Web sessions (start at claude.ai/code): run in Anthropic's cloud, persist even when your laptop closes, accessible from the Claude iOS/Android app. Use claude --teleport to pull the session back into your local terminal when you return.
• Remote Control: expose a locally-running Claude Code session to claude.ai — steer it from phone or browser, but your laptop must stay awake.
• DIY browser terminal: the community-built pattern for persistent sessions on your own infrastructure.
• Always-on VM: remove the laptop requirement entirely by running Claude Code on persistent remote compute.

Why Do Claude Code Sessions Die When You Leave Your Desk?

Claude Code runs as a foreground process in your terminal. When you close your laptop lid, macOS suspends processes and severs network connections. When you close the terminal window, the OS sends SIGHUP to all child processes and Claude Code exits.

This isn't a Claude Code bug — it's standard Unix process lifecycle. The fix is either keeping the session process alive in a context that survives disconnects (a remote machine, a cloud VM, or a terminal multiplexer), or using Claude Code's official handoff mechanisms to move the session somewhere persistent. The How to Keep Claude Code Running After You Close Your Terminal guide covers the tmux path in depth. This post focuses on the paths that also give you mobile access while the session runs.

Prerequisites

Required:

• Claude Code installed and authenticated: npm install -g @anthropic-ai/claude-code
• A claude.ai account (free tier works for Remote Control and web sessions)
• The Claude iOS or Android app installed on your phone

For the --teleport path:

• Access to claude.ai/code from a browser or the Claude iOS app

For the DIY path:

• A machine that stays on — see the infrastructure requirements overview at the Sealos Claude Code mobile guide for the full picture of host machine, VPN, and session persistence options

Recommended (not required):

• Grass CLI (npm install -g @grass-ai/ide) for mobile permission forwarding and sessions that survive laptop sleep — covered in its own section below

Path 1: Web Sessions + claude --teleport

Web sessions are the most robust path for true session persistence — they run on Anthropic's infrastructure, not your laptop, so they stay alive regardless of what your machine does. As the Claude Code web docs explain: "Web sessions persist even if you close your laptop, and you can monitor them from anywhere including the Claude iOS app."

Step 1: Start the Session on the Web (or Transfer from Your Terminal)

Option A — Start directly on the web: Navigate to claude.ai/code in your browser or open the Claude iOS app and start a session there. Kick off your task directly in the web interface — Claude runs in Anthropic's cloud from the start and the session is immediately accessible from any device.

Option B — Transfer from an active terminal session: If you're already mid-session in your terminal and need to hand off to the cloud before leaving, prefix your next message with &:

> & continue implementing the authentication module and open a PR when done

This creates a new web session initialized with your current conversation context. Note the constraint the docs are explicit about: "Session handoff is one-way: you can pull web sessions into your terminal, but you can't push an existing terminal session to the web." The & prefix doesn't migrate your terminal session wholesale — it starts a new web session seeded with the current context.

Step 2: Monitor from Your Phone

Once a session is running on the web, open the Claude iOS or Android app. Your active web sessions appear in the session list — you can read the agent's progress, send follow-up prompts, and observe tool calls in real time without being at a keyboard. This is the mobile monitoring workflow: the session runs in Anthropic's cloud, and the Claude app is your read/write window into it from anywhere.

Step 3: Pull Back to Your Terminal with --teleport

When you return to your desk and want to continue in your local terminal environment:

claude --teleport

This pulls the active web session into your local Claude Code context, resuming the conversation with the full session history intact. The web session ends and you continue from your terminal. Anthropic's docs describe this as the primary use case: "Kick off a long-running task on the web or iOS app, then pull it into your terminal with claude --teleport."

Path 2: Remote Control — Keep Your Local Session Reachable from Any Device

Remote Control is a different tradeoff: your Claude Code session runs on your local machine, and claude.ai — or the Claude iOS/Android app — connects to it remotely. Nothing runs in Anthropic's cloud.

As the Remote Control docs describe: "Start a task at your desk, then pick it up from your phone on the couch or a browser on another computer. When you start a Remote Control session on your machine, Claude keeps running locally the entire time, so nothing moves to the cloud."

How to Enable Remote Control

From within an active Claude Code session, start a Remote Control session. Claude Code generates a URL you can open from your phone or another browser — the exact setup steps and UI are documented at code.claude.com/docs/en/remote-control. You'll get a live view of the session: send prompts, read responses, monitor agent activity, and steer the task exactly as if you were at your terminal.

When Remote Control Falls Short

Remote Control requires your laptop to stay awake and connected. If you close the lid on a long commute or run a multi-hour overnight build, the session will stop when your machine sleeps. Remote Control is the right choice for shorter gaps — a meeting, a walk between buildings, monitoring from the couch. For tasks where you genuinely need to walk away and come back hours later, the web session path is more reliable.

Path 3: DIY Browser Terminal

Before Anthropic shipped official mobile workflows, developers built their own. One community member posted in r/ClaudeCode about building a browser-based terminal specifically to solve this problem — the core design goal was that "sessions persist if the browser closes."

The pattern: a lightweight HTTP server running alongside Claude Code serves a browser-based terminal UI. Since the server process lives independently of any connected client, closing your phone's browser doesn't kill the session. This approach requires the server machine to stay running, but it decouples session lifetime from any individual client connection.

The prerequisites for this path include a machine that stays on, a secure network path to reach it remotely, and session isolation so the terminal process survives disconnects. The How to Run Claude Code on a Remote Server guide covers the underlying setup — tmux for session persistence, SSH for remote access, and optional Tailscale for secure connectivity from any network.

How Do You Verify the Session Is Still Running?

For web sessions:

1. Open the Claude iOS app and confirm your session appears in the active session list
2. Send a short follow-up prompt from your phone — if you get a response, the session is live
3. Back at your terminal: run claude --teleport — if it picks up the conversation, the round-trip worked

For Remote Control:

1. Open the remote URL on your phone
2. Confirm the session history is visible
3. Send a test message: "What are you currently working on?" — the response should reflect the active task context

Troubleshooting

claude --teleport finds no active web session

--teleport only works when you have an active web session running at claude.ai/code. Check whether the session completed, timed out, or was never started on the web. If you used the & prefix in your terminal to create a web session, verify it was accepted before closing your terminal.

Web session timed out mid-task

Anthropic web sessions can time out during very long tasks or during periods of tool-use inactivity. Structure long jobs as subtasks with natural checkpoints — shorter autonomous runs that each complete before timeout windows close.

Remote Control disconnects when the laptop sleeps

This is expected behavior. Remote Control keeps Claude running locally, but sleep breaks the network bridge. Either keep your laptop awake (caffeinate -d on macOS prevents display sleep), or switch to the web session path for tasks requiring true unattended operation.

Permission prompts blocking the session

When Claude Code needs to run a bash command, write a file, or make a web fetch, it pauses and waits for approval. If you're away from your desk, these gates freeze the session until you respond. The Claude Code Keeps Asking for Permission post covers your options — from auto-approving specific trusted tools to forwarding approval gates to your phone in real time.

How Grass Eliminates the Laptop Dependency Entirely

The paths above bridge the laptop dependency — they give you mobile visibility into a session that still ultimately depends on some machine staying awake. Grass takes a different approach: your agent runs on an always-on cloud VM, so there's no machine to babysit.

The local path takes under five minutes:

npm install -g @grass-ai/ide
cd ~/your-project
grass start

Grass starts a local HTTP server and prints a QR code. Scan it with the Grass iOS app (or open the URL in any browser on the same network) and you're connected — live streaming chat, a diff viewer showing git diff HEAD, and native permission modals for every tool call the agent wants to make.

The permission forwarding is the part that changes the workflow most concretely. When Claude wants to run a bash command or write a file, a native modal appears on your phone: the tool name, a syntax-highlighted preview of what will be executed, and two buttons — Allow or Deny. You're not waiting to get back to a terminal; you're operating the agent from wherever you are. Full details on what this looks like in practice: How to Approve or Deny a Coding Agent Action from Your Phone.

If you're away from your home network, grass start -n tailscale emits a QR code pointing to your Tailscale IP instead of your local IP — so you can reach the session from any network without opening ports. The Tailscale + Claude Code guide covers the VPN setup if you don't have Tailscale running yet.

For true laptop-independence, the cloud VM product at codeongrass.com removes the final constraint. Grass provisions a Daytona workspace with Claude Code, Codex, and Open Code pre-loaded. The VM is always-on — sessions survive your laptop sleeping, restarting, or being left at the office entirely. The workflow becomes: kick off a task from your phone, leave for a meeting, check progress on your commute, tap Allow on a permission modal in the elevator, review the diff on your way home. The laptop is optional, not the load-bearing piece.

What Grass adds that --teleport and Remote Control don't:

The free tier at codeongrass.com includes 10 hours, no credit card required.

FAQ

How does claude --teleport work?

claude --teleport pulls an active Claude Code web session — one running at claude.ai/code — into your local terminal. You start a task on the web (either directly at claude.ai/code, via the Claude iOS app, or by prefixing a message with & in your terminal session), and when you return to your desk, claude --teleport resumes the session locally with the full conversation history intact.

Can I push a local Claude Code terminal session directly to my phone?

Not with --teleport alone — the handoff is one-way: web sessions can be pulled to your terminal, but you can't migrate an existing terminal session to a web session wholesale. To move mid-session context to the web, prefix your next message with & — this creates a new web session initialized with your current conversation context, which you can then monitor from the Claude iOS app.

What happens to Claude Code when my laptop goes to sleep?

If the session is running locally — including under Remote Control — it pauses or exits when the machine sleeps and loses its network connection. If the session is a web session at claude.ai/code, it continues running in Anthropic's cloud regardless of your laptop's state. For long-running tasks where you need genuine laptop independence, web sessions or an always-on remote machine are the reliable paths.

What's the difference between Remote Control and web sessions?

Remote Control keeps Claude Code running locally on your machine and lets you connect to it from a phone or browser. Your code stays local, nothing runs in Anthropic's cloud. Web sessions run on Anthropic's infrastructure — useful when you need the session to survive laptop sleep or when you want to start a task from your phone before you're even at a computer. The two mechanisms serve different scenarios; neither replaces the other.

How do I handle Claude Code permission prompts when I'm away from my desk?

The official --teleport and Remote Control paths don't include built-in remote permission forwarding — the session pauses at each approval gate until you're back at a terminal. The Grass CLI forwards permission requests to your phone as native modals (tool name, syntax-highlighted preview, Allow/Deny), so approval gates don't freeze your session while you're away. Alternatively, you can configure --dangerously-skip-permissions for specific workflows where you trust the agent's tool calls completely — but use this carefully and only for well-understood, bounded tasks.

Next Steps

Start with whichever path fits your current setup:

• Quickest win: Enable Remote Control during your next Claude Code session and monitor it from the Claude iOS app while it works in the background.
• For longer tasks: Start your next multi-hour job at claude.ai/code so it runs on Anthropic's infrastructure, then use claude --teleport to resume in your terminal when you return to your desk.
• To eliminate the laptop dependency: Get started with Grass in 5 minutes — install the CLI, scan the QR code, and approve your first agent action from your phone. Or provision an always-on cloud VM at codeongrass.com. Free tier, no credit card.