Mobile-to-desktop workflows

What to understand

• The core insight: separate where work RUNS from where you DECIDE. The agent's loop (read, propose, act, observe) runs on a host with your repo, tools, and credentials. Your phone or browser is a thin control surface that sends prompts and approvals and shows diffs. Nothing executes on the phone, it is a window into a session running somewhere with real compute. Get this distinction and every mobile feature below stops being magic and becomes obvious.
• Codex remote connections (shipped mid-May 2026) make your phone a remote control for a paired desktop host. From the ChatGPT mobile app you start or continue threads on a connected Mac or Windows machine, answer the agent's questions, approve commands, and review diffs, test output, terminal output, and screenshots. The host supplies everything real, repositories, shells, plugins, Chrome, and Computer Use (the agent driving a GUI by looking at the screen), while the phone only steers. You can also continue the same thread later from another signed-in Codex App device.
• Claude Code splits portability into three distinct mechanisms, and conflating them is the most common beginner error. Remote Control drives a session running on YOUR machine from a phone or browser. Teleport PULLS a CLOUD session down into your local terminal. Claude Code on the web (via --remote) PUSHES a task UP to an Anthropic-managed cloud VM that runs without your laptop. They answer different questions: 'control my local run remotely', 'bring a cloud run home', and 'run it in the cloud while I'm offline'.
• Claude Code Remote Control keeps the session LOCAL the entire time. When you run claude remote-control (or --remote-control, or /remote-control from inside a session), your machine keeps running the agent and makes only outbound HTTPS calls, it never opens an inbound port. claude.ai/code and the Claude mobile app are just windows into that local session, so your filesystem, MCP servers, and project config all stay available, and the conversation stays in sync across terminal, browser, and phone simultaneously. Requires v2.1.51+.
• Teleport is a one-way cloud-to-local handoff that moves the WHOLE task. Run claude --teleport for an interactive picker, or claude --teleport <session-id> to resume a specific cloud session in your terminal. It verifies you're in the right repository, fetches and checks out the cloud session's branch, and loads the full conversation history, so you continue exactly where the cloud left off. You cannot push a terminal session up the same way; for that you start a fresh cloud session with --remote.
• Mobile makes sense when the human decision is cheap but the work is slow, and rarely otherwise. The classic shapes: kick off a long task before you leave the desk and approve milestones from your phone; triage and unblock a stuck agent during a commute; review and merge a finished diff while away; or delegate a self-contained task from your phone (Claude's Dispatch can message a task from mobile that spawns a Desktop session to handle it). Mobile is for steering and approving, not for authoring large changes on a 6-inch screen.
• Both products gate this behind account, plan, and admin controls. Codex requires the phone and host on the same ChatGPT account and workspace, and a managed workspace needs an admin to enable Remote Control access before pairing works. Claude Code Remote Control needs a Pro/Max/Team/Enterprise plan with claude.ai OAuth login (API keys are NOT supported), and on Team/Enterprise an admin must turn on the Remote Control toggle in admin settings. Plan the access path before you rely on it mid-commute.
• Security is enforced end-to-end, but the host is your responsibility. Codex routes through a secure relay so trusted machines stay reachable without being exposed to the public internet; the guidance is to keep the host awake and online, use a VPN or mesh network (a private overlay network such as Tailscale) for off-network access rather than exposing the host's local app server, and use trusted SSH keys and least-privilege accounts for SSH hosts. Claude Code's local session times out after roughly 10 minutes offline and ends entirely if the process is killed, so the host staying awake and connected is a hard requirement, not a nicety.
• Convenience does not lower the review bar. Approving from a phone surfaces the same diff, test output, and terminal output you'd see at the desk, read it before you tap approve. The danger of mobile is not technical; it's psychological: a small screen and a spare moment make it tempting to rubber-stamp an irreversible action. Carry the same red lines (no silent deletes, pushes, sends, or spend) onto the phone, and demand the same evidence before approving.

Deeper dive

Session portability mechanisms compared

The four ways to move agentic work between phone, browser, cloud, and desktop in 2026. They are NOT interchangeable, each answers a different question about where work runs and which direction the session moves. Names, version requirements, and defaults change fast; verify at the official docs below before relying on them.

Sources (as of June 2026): Codex. Remote connections · Claude Code. Remote Control · Claude Code on the web (teleport / --remote)

Step by step

1

Decide which mechanism the task actually needs

Before pairing anything, classify the task against the comparison table. Does the work need your REAL local tools, credentials, or MCP servers (then run it on your host and drive it remotely)? Can it run autonomously and unattended on just what's committed to the repo (then push it to the cloud with claude --remote and monitor from mobile, the isolated VM only sees committed code and an allowlisted network)? Is there already a cloud session you want to finish locally (then teleport it down)? Write the one you'll use and why.

HintThe wrong reflex is 'put it on my phone'. The right question is 'where should this run?', capability and safety both follow from that, not from the screen you happen to be holding.

2

Confirm your access path (account, plan, admin)

For Codex: make sure the ChatGPT mobile app and the Codex App host are signed in to the SAME account and workspace, or the host never appears on your phone; on a managed workspace, have an admin enable Remote Control access first. For Claude Code: confirm you're on Pro/Max/Team/Enterprise and logged in via claude.ai (run /login. API keys do NOT work for Remote Control; setup-token and API-key logins are inference-only and are rejected), CLI v2.1.51+; on Team/Enterprise have an admin turn on the Remote Control toggle in admin settings. You've confirmed the path when you can name your plan and workspace and, on a managed account, you've seen the admin toggle on.

HintMismatched workspaces (Codex) and API-key logins (Claude) are the two most common reasons pairing silently fails, fix these before you're standing on a platform trying to unblock an agent.

3

Pair the phone to the host

12

Codex: on the Codex App select 'Set up Codex mobile' in the sidebar to show a QR code (pairing always starts on the trusted host), scan it with your phone, and complete any SSO/MFA/passkey prompts, the host then appears in your mobile Codex projects. Claude Code: run `claude remote-control` in your project (press spacebar to show a QR code), scan it to open the session in the Claude app, or open claude.ai/code and pick the session by name. Either way, pairing has worked when the session opens in the app showing the computer icon with a green status dot.

HintIf you don't have the Claude app yet, run /mobile inside Claude Code to show a download QR; for Codex, ensure both the ChatGPT app and Codex App are on current versions.

On this screen

1. 1Pairing starts on the host. Both tools display the QR from the trusted desktop; the phone only completes the link, it never initiates execution.
2. 2'Before you set up mobile access'. The requirements note on this page, current app versions on both devices, same account and workspace, is where most pairing failures start.

4

Kick off the task with an async-delegation brief

Use the production prompt from this lesson. Send a self-contained brief with a tight scope, pre-authorised autonomy for the cheap reversible work (read, edit, run tests), and explicit GATES where the agent must stop for your phone approval. State the definition of done. For bigger tasks, settle the plan at the desk first (plan mode or read-only), commit it, and make the brief 'execute the plan in docs/plan.md', judgement where review is cheap, execution where your presence is optional. Then leave the desk, the host keeps running the agent's loop while you're away. You'll know the brief worked when the first notification you see is 'GATE 1. PLAN READY', not a clarifying question.

HintFront-load specificity: a vague mobile prompt can burn ten minutes down the wrong path before you even see it. The brief is your stand-in while you're gone. And check the host's power/sleep settings before you walk away (step 7).

5

Steer and approve from your phone, but keep the review bar

When the agent hits a gate, a notification surfaces (Claude can push when it needs a decision or a task finishes; ask 'notify me when the tests finish' to request one). Open the diff, test output, terminal output, or screenshots it surfaces and actually read them before approving. Answer questions, approve in-scope steps, and decline anything that crosses a red line. A good gate review ends with evidence you actually read, you should be able to name one specific thing in the diff or test output you checked before tapping approve.

HintA spare moment and a small screen make rubber-stamping tempting, that's exactly when an irreversible mistake slips through. Demand the same evidence you would at the desk.

6

Finish on the desktop, teleport or continue, then do the git steps

Back at your desk, bring the task home. If it ran in the cloud, run `claude --teleport` (or /teleport) to pull the session and its branch into your terminal with full history; if it ran on your host, continue the same thread locally. Now do the deliberate, irreversible steps, review the final diff, commit, push, open the PR, with full context and a real keyboard. Teleport has worked when your terminal shows the cloud session's branch checked out and the full conversation history loaded.

HintDefer commit/push/PR to the desk on purpose: state-changing git is the textbook 'don't approve this from a phone' action. The clean handoff (teleport pulls the branch + history) is what lets you finish without re-explaining anything.

7

Keep the link safe and the host alive

Keep the host awake and online for the duration. Codex drops the link if the host sleeps, and Claude Code Remote Control times out after ~10 minutes offline and ends entirely if the process is killed. For off-network access use a VPN or mesh network rather than exposing the host's local app server (the process the relay talks to) to the internet; for Codex SSH hosts use trusted keys and least-privilege accounts. Sandbox and approval settings stay enforced on remote sessions, don't loosen them just because you're mobile.

HintAdjust power/sleep settings before you walk away. The most common 'it stopped working on the train' cause is the laptop lid closing, not the network.

Production prompt examples

STANDING INSTRUCTIONS apply (read-only first, ask before anything irreversible). This is an ASYNC DELEGATION: I am sending this from my phone and will be away from the desk for ~45 minutes, so you must be self-sufficient within the boundaries below and NOT block waiting on me except at the named gates.

ROLE: You are a careful senior engineer running unattended on a trusted host. I will review and approve from my phone at the gates, and finish at my desk.

CONTEXT: Repo is already open on this host on branch `main`. In scope ONLY: src/payments/refund.ts and its test file src/payments/refund.test.ts. Do not read or modify anything else without telling me which file and why first.

TASK: Add idempotency to the refund handler so a duplicate refund request with the same idempotency-key is a no-op that returns the original result. Add tests for: first call, duplicate call, and a different-key call.

AUTONOMY (what you MAY do without asking, since I'm away):
- Read the two in-scope files and run the existing test suite for them.
- Make the edit and write the new tests.
- Run the tests for those files as many times as needed to get them green.

GATES (STOP and wait for my phone approval at each):
- GATE 1 (plan): Before editing, post a 3-5 line plan: the approach, the exact files you'll touch, and how you'll test. Then STOP.
- GATE 2 (diff): After tests pass locally, post the full diff and the test output. Then STOP. Do NOT commit, push, or open a PR, I will do the git steps at my desk.

HARD STOPS (never, even though I'm away): no commit, push, force-push, branch changes, package installs, deploys, deletes outside the two files, network calls, or spend.

NOTIFY: When you reach each gate, make it obvious in your first line ('GATE 1. PLAN READY' / 'GATE 2. DIFF READY') so I see it in the notification. If you get stuck or the task is ambiguous, STOP at once with 'BLOCKED:' and one tight question rather than guessing.

OUTPUT STYLE: Terse. Plans as short bullets, changes as diffs, test results as the raw pass/fail summary. Don't restate files back to me.

Confirm you understand in one line, then begin and stop at GATE 1.

Common mistakes to avoid

• Conflating Claude Code's three mechanisms. Remote Control (drives a LOCAL session), teleport (pulls a CLOUD session DOWN), and --remote (pushes a task UP to the cloud). They run in different places and move in different directions.
• Trying to author large changes on a phone instead of using mobile for what it's good at, steering, approving, and unblocking. The phone is a control surface, not a workstation.
• Sending a vague one-liner before walking away: at the desk you'd correct it in seconds, but async there's no one watching, so the agent can run far down the wrong path before you see it.
• Pairing while the phone and desktop are on different ChatGPT workspaces (Codex), or logging into Claude Code with an API key instead of claude.ai (Remote Control rejects API-key auth).
• Letting the host sleep or closing the laptop lid, which silently drops the Codex link or times out the Claude Code Remote Control session after ~10 minutes offline.
• Approving irreversible actions, especially commit/push/PR, from a phone in a spare moment without reading the surfaced diff and test output. Defer git to the desk on purpose.
• Exposing the host's local app server directly on a shared network instead of using a VPN or private mesh network for off-network access.
• Loosening sandbox or approval settings because you're on mobile, remote convenience is not a reason to lower the safety dial.

Source conflicts to review

• Both tools shipped mobile/portability features in 2026 and iterate weekly: Codex mobile remote access landed ~mid-May 2026, with Windows-host control added in Codex App v26.527.1 on 29 May 2026; Claude Code Remote Control requires CLI v2.1.51+ and push notifications v2.1.110+. Treat versions as a floor and re-verify at the official docs, distrust tutorials older than a few weeks.
• Secondary write-ups routinely blur Claude Code's three distinct mechanisms (Remote Control runs locally, --remote/web runs in the cloud, teleport pulls cloud -> local). Prefer the official remote-control and claude-code-on-the-web docs over blogs that present them as a single 'mobile mode'.
• Platform pairing rules differ and changed mid-2026 (which device can control which host). As of June 2026 you can control a Windows or Mac host from ChatGPT iOS/Android or from a Mac, but Windows cannot act as a controller, confirm current support on the Codex remote-connections page.