Claude Code `--teleport`: How to Pull Cloud Sessions Into Your Terminal

You start a task with claude --cloud "fix the flaky auth test", close your laptop, and forget about it. Two hours later you’re at your desk and want to finish the work locally instead of watching it in a browser tab. --teleport is the flag that does that: it pulls the cloud session — its branch, its diff, its entire conversation history — down into your terminal so you can keep going exactly where it left off.

The mechanism is simple once you see it. The confusion comes from what people assume it also does: push work back up, sync bidirectionally, or behave like the similarly-named Remote Control feature. It doesn’t do any of that, and conflating the two is the single most common mistake in coverage of this flag. This guide covers the mechanics precisely, cites the official docs for every claim, and draws the line between --teleport and Remote Control clearly enough that you won’t mix them up again.

What --teleport Does

--teleport resumes a Claude Code on the web session — one you started with claude --cloud "..." from your terminal, or one you kicked off directly at claude.ai/code — inside your local terminal. It is one entry in a small family of flags that move work between your machine and Anthropic’s cloud infrastructure: --cloud sends a task up to a fresh cloud sandbox, and --teleport brings a session back down.

There are four ways to trigger it, all documented on the Claude Code on the web page:

• claude --teleport — opens an interactive picker listing your cloud sessions.
• claude --teleport <session-id> — resumes a specific session directly, no picker.
• /teleport or its short form /tp — run inside an existing local session to open the same picker without restarting Claude Code.
• From /tasks — list your background sessions, then press t to teleport into the selected one.
• From the web UI — the Open in CLI button on claude.ai/code copies a ready-to-paste teleport command.

# Interactive picker
claude --teleport

# Jump straight to a known session
claude --teleport a1b2c3d4

# From inside a running session
/teleport

If you have uncommitted local changes when you run any of these, Claude Code prompts you to stash them before it proceeds.

The One-Way Constraint, Explained Mechanically

This is the part most coverage gets wrong or skips. Here is what actually happens, step by step, per the official docs:

1. The cloud session runs against a specific branch inside Anthropic’s sandboxed VM. When you start a session with claude --cloud, Claude Code clones your current repository’s GitHub remote at your current branch into a fresh, isolated container. Every commit the cloud session makes happens on a branch inside that sandbox, not on your machine.
2. Teleporting checks four things before it resumes anything — this is the actual “Teleport requirements” table from the docs:

3. If all four pass, Claude Code fetches and checks out the branch, then loads the full conversation history into your terminal. Your local git checkout now points at the same commit the cloud sandbox was on.
4. From that moment, your terminal owns its own copy of the session. Work you do locally after teleporting stays local — it does not sync back up to the cloud session on claude.ai or the mobile app. The cloud session and your local session diverge the instant you teleport; they are not kept in lockstep.

That divergence is why the handoff is one-way. There is no --teleport-in-reverse: the CLI has no flag that takes a local session and pushes it into a new cloud sandbox. The closest thing is claude --cloud, but that starts a new session from your current branch — it does not continue the specific conversation you were just having locally. (The one exception: the Desktop app has a Continue in menu that can hand a local session to the web, but that’s a separate Desktop-only feature, not something the CLI does with --teleport or any of its siblings.)

Practical implication: if you want to keep working on a teleported session from your phone after pulling it local, teleporting alone won’t do it — you need to separately start /remote-control inside that local session. That’s the bridge back to a multi-device workflow, and it’s a genuinely different feature from teleport, which is the whole point of the next section.

Also worth knowing: --teleport is distinct from --resume. --resume reopens a conversation from this machine’s local history and never lists cloud sessions. --teleport is the only flag that pulls a cloud session and its branch onto your machine. If you’re used to --resume / --continue for local session management, see our guide to Claude Code’s session flags — it covers the local-only side of this picture in depth.

--teleport vs. Remote Control: Opposite Directions

These two features get confused constantly because both involve “your machine” plus “the cloud,” and both surface at claude.ai/code. But they move different things, in opposite directions:

The official framing from the Remote Control docs puts it cleanly: “the key difference is where the session runs: Remote Control executes on your machine… Claude Code on the web executes in Anthropic-managed cloud infrastructure.” Teleport is the bridge that moves a session from the latter to the former — permanently, one-way. Remote Control never involves a cloud VM at all; it’s a live window (from your phone or another browser) into a process that was already running, and still runs, on your own hardware. Think of it as: teleport relocates a session; Remote Control just adds a remote screen and keyboard to a session that never left home.

Requirements

Two things have to be true before --teleport will work:

• claude.ai subscription authentication. Per the docs, “Teleport requires claude.ai subscription authentication.” If you’re authenticated via API key, run /login to sign in with your claude.ai account instead — API key auth alone isn’t sufficient. It’s also unavailable on Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry, since cloud sessions only run on Anthropic’s own infrastructure.
• GitHub access on the connecting account. Cloud sessions clone from and push to GitHub rather than your machine, so the account needs GitHub connected — either via the Claude GitHub App (set up during web onboarding) or by running /web-setup to sync your local gh CLI token. Without that, there’s no branch for teleport to fetch in the first place.

If your organization has disabled cloud sessions outright, or you’re signed in correctly but still see errors, that’s an org-level policy setting, not something fixable client-side — the docs note this explicitly as the fallback explanation when everything else checks out.

The “Hidden Flag” Note

You’ll see --teleport described online as a “secret” or “hidden” flag. That’s imprecise, and worth correcting: it’s unlisted in claude --help output, but officially documented on Anthropic’s own docs site. The Claude Code on the web page says so directly: “The --cloud and --teleport flags don’t appear in claude --help output, but the CLI accepts them as shown below.” Same goes for --cloud itself, and the CLI reference page lists both flags with full syntax and examples.

So it’s not a secret in the sense of being undocumented — it’s just missing from the one place (--help) most people check first. If you only ever skim --help for what Claude Code can do, you’ll miss it, along with --remote-control/--rc and a handful of other flags. Worth bookmarking the CLI reference directly rather than relying on --help alone.

(One more discoverability note for anyone citing older links: Anthropic moved its docs from docs.claude.com to code.claude.com — old docs.claude.com/en/docs/claude-code/* URLs now 301-redirect to the new domain. If you have bookmarks or scripts pointing at the old paths, update them; the redirect works today but isn’t guaranteed to stay in place indefinitely.)

FAQ

Can I teleport a session that has uncommitted changes in the cloud sandbox? The requirement is about your local working directory being clean, not the cloud session. If your local checkout has uncommitted changes, Claude Code prompts you to stash them before teleporting. The cloud session’s own commits on its branch are what gets fetched and checked out — that part is handled automatically as long as the branch has been pushed to the remote.

What happens to the cloud session after I teleport it? Nothing happens to it automatically — it isn’t deleted or locked. But it becomes effectively stale: continued work happens in your terminal from that point forward, and it does not sync back to the cloud copy. If you open the session again on claude.ai, you’ll see it as it was at the moment you teleported, not with any of your subsequent local changes.

Can I push a local session to the cloud instead? Not with --teleport — that flag only pulls, it doesn’t push. To send work to the cloud, start a new session with claude --cloud "task description", which creates a fresh cloud sandbox from your current branch. It’s a new session, not a continuation of your local conversation. The Desktop app has a separate Continue in feature that can hand a local session to the web, but that’s Desktop-specific and not part of the CLI’s --teleport/--cloud pair.

Is --teleport the same as --resume? No. --resume reopens a conversation from your own machine’s local history and never touches cloud sessions. --teleport is specifically for pulling a cloud session — with its branch and full conversation — onto your machine. If you’re not sure which one applies, ask: “did this conversation start on claude.ai or via --cloud?” If yes, it’s --teleport. If it started and has only ever lived in your terminal, it’s --resume.

Why does --teleport fail with a Remote Control–related error message? Under the hood, --teleport authenticates through the same Remote Control session infrastructure that cloud sessions use, so errors can surface with Remote Control wording (for example, “Remote Control session expired”). That’s a plumbing detail, not a sign you’re accidentally invoking Remote Control — the connection token involved is short-lived and scoped to your account, and re-running --teleport typically resolves it.

Related

• Claude Code —continue and —resume: Never Lose Your Session Context Again