Blog · November 9, 2026 · 8 min read · by Vilva Athiban P B

claude --teleport: Pull a Cloud Session Into Your Terminal, Start One With --cloud, Send Follow-Ups From the CLI, and the Requirements That Trip People Up

A cloud session is the one Claude Code session you can walk away from without leaving a laptop open. The catch is that work started there eventually has to meet your editor. The cloud sessions page, read on 9 November 2026, documents three CLI moves for that: claude --cloud to start a cloud session from your repo, claude -p ... --cloud <id> to queue a follow-up, and claude --teleport to pull a cloud session back into your terminal. Here are all three, the requirements teleport checks, what breaks, and when to leave the work in the cloud.

The one-way rule first

The docs say it plainly: from the CLI, session handoff is one-way. You can pull a cloud session into your terminal with --teleport, but you cannot push an existing terminal session to the cloud. --cloud with a task description creates a new cloud session for the current repository; it does not upload the conversation you are in. The only surface that can send a local session to the cloud is the Desktop app, from the Open in menu of its Code tab. If you have been pairing with Claude in a terminal for an hour and want the rest done remotely, either write the plan to a file, commit and push it, and start a fresh --cloud run from that, or keep the terminal session alive and steer it from your phone with Remote Control, which is a different feature from cloud sessions.

Start a cloud session from the terminal: claude --cloud

# New cloud session for this repo, at the branch you are on
claude --cloud "Fix the authentication bug in src/auth/login.ts"

# Three independent sessions, running in parallel
claude --cloud "Fix the flaky test in auth.spec.ts"
claude --cloud "Update the API documentation"
claude --cloud "Refactor the logger to use structured output"

The cloud VM clones your current directory’s GitHub remote at your current branch, not your local checkout, so push first if you have local commits. If the terminal prints Branch <name> is not on GitHub, the session still starts, but from a pushed commit in the branch’s history or the default branch, and your unpushed work is not in it. One repository per --cloud call. While the container provisions, the CLI shows a checklist and queues anything you type until the session is ready. The older --remote spelling still works as a deprecated alias. If the repository has no remote, or the Claude GitHub App is not installed on it, Claude Code uploads a bundle of your local repository instead.

Send a follow-up from any machine: claude -p ... --cloud

# Queue one message into a running cloud session and exit
claude -p "Also add a regression test for the null token case" --cloud session_01DiUkqY2kzbUbDmW1w96rfi

# The claude.ai/code URL works too, and so does stdin
echo "Run the full suite before you open the PR" | claude -p --cloud https://claude.ai/code/session_01DiUkqY2kzbUbDmW1w96rfi

# Machine-readable result: {ok, session_id, url}
claude -p "Rebase onto main" --cloud cse_abc123 --output-format json

This posts one message and exits without waiting for a reply. It sends no local session state, so it works from any machine where you have run claude auth login, including a CI runner. The session ID can be the bare session_... or cse_... value or the claude.ai/code URL. On success the CLI prints the session ID and a View link; with --output-format json you get {ok, session_id, url}, or ok: false with an error when the session is missing or archived. Running --cloud <session-id> without -p is refused with a message saying attaching to an existing cloud session is not enabled for your account, so use the -p form.

Pull a cloud session into your terminal: claude --teleport

The docs list five ways to start a teleport. They all end in the same place.

  • claude --teleport opens an interactive picker of your cloud sessions; claude --teleport <session-id> skips the picker.
  • Inside a running CLI session, /teleport or /tp opens the same picker without restarting.
  • /tasks lists your background sessions; press t on one to teleport into it.
  • On claude.ai/code, Open in > Terminal in the session menu copies a command to paste.
  • Inside the cloud session itself, type /teleport and Claude replies with the exact claude --teleport <session-id> command. This needs Claude Code v2.1.223 or later in the session’s environment.
cd ~/src/my-repo            # a checkout of the SAME repository, clean tree
claude --teleport           # pick from the list, or:
claude --teleport session_01DiUkqY2kzbUbDmW1w96rfi

Teleport verifies you are in the right repository, fetches and checks out the branch the cloud session pushed, and loads the full conversation history into your terminal. From then on the terminal has its own copy of the session, and new local work does not appear in the cloud session on claude.ai or the mobile app. If you still want to steer from your phone, start /remote-control in the local session. Note that --teleport is not --resume, which reopens conversations from this machine’s local history and never lists cloud sessions; our resume guide covers that side. One more detail from the changelog entry for v2.1.311 (26 October 2026): teleport now warns when a compacted cloud session loads from its last compaction, because the messages that compaction summarised are not in the local copy.

Teleport requirements

  • Clean git state. No uncommitted changes; teleport prompts you to stash if there are any.
  • Same repository, not a fork. Running from a different repository produces an error naming both. If your remote is an SSH alias such as git@work:owner/repo.git that Claude Code cannot parse into a hostname, it asks you to confirm and accepts the checkout when owner and repo name match.
  • Branch pushed to the remote. Teleport fetches and checks it out; a branch that exists only inside the cloud VM cannot be fetched.
  • Same claude.ai account as the one that owns the cloud session.

The fetch never waits for input. If git or ssh would ask for a password, a key passphrase, or confirmation of a new SSH host, the fetch fails and the checkout works only if your clone already has the branch. Load your key into ssh-agent and run git fetch once by hand so the host is in known_hosts before you teleport.

When teleport is unavailable

Teleport needs claude.ai subscription authentication. With an API key, run /login. Through Amazon Bedrock, Google Cloud’s Agent Platform or another third-party provider, cloud sessions are not available at all and the error names the provider. If you are signed in to claude.ai and it still fails, your organisation may have disabled cloud sessions. The errors Unable to get organization UUID and Error loading Claude Code sessions in the picker both mean the same thing: sign in with claude auth login and retry. Because teleport rides on the Remote Control infrastructure, you may also see Remote Control session expired or Access denied, and /login refreshes the token.

Environment expired: what comes back

Cloud sessions stop after a period of inactivity and the VM is reclaimed. Reopening from claude.ai/code provisions a fresh VM and restores the conversation history. It does not restore background shell commands, subagents, or session-scoped scheduled tasks and a waiting /loop, so ask Claude to rerun or reschedule them. Local sessions have their own idle mechanics; see what happens when you step away from a session.

Teleport it or leave it in the cloud?

  • Teleport when the next step needs your machine: a local-only database, a device simulator, a debugger, or a diff you want to read in your editor before pushing anything else.
  • Teleport when the cloud session is done and you want to keep iterating on its branch from your editor.
  • Leave it in the cloud when the task is still running; teleporting copies the conversation, and anything you do locally diverges from what the cloud continues to do. Send a -p ... --cloud follow-up instead.
  • Leave it in the cloud when you cannot satisfy the requirements right now: a dirty tree you do not want to stash, a fork, or a machine signed in to a different account.
  • Start new with --cloud when you have a pushed plan and want parallel, unattended execution; create the PR from claude.ai/code, or teleport afterwards.

Honest limits

  • One-way. No CLI path pushes a terminal session to the cloud; only the Desktop app can.
  • GitHub only for the round trip. Cloning and PR creation require GitHub (GitHub Enterprise Server on Team and Enterprise plans). A GitLab or Bitbucket repo can go up as a local bundle with CCR_FORCE_BUNDLE=1, but the session cannot push results back, which also means there is no branch for teleport to fetch.
  • Clean tree, same repo, same account. Teleport refuses otherwise, by design.
  • Compaction gaps. A compacted cloud session arrives from its last compaction; the warning is new in v2.1.311.

Knowing when to come back

Every move above assumes you notice when the cloud session finishes or asks a question. The docs say an idle question waits until environment expiry, which is forgiving, but the gap between “done” and “you saw it” is dead time. AI Done Now watches for that moment on your Mac so the teleport or the follow-up happens when it is useful, not when you remember to check.

Keep reading

Desk Exercises for Programmers: 15 Moves to Do While Your AI Agent Codes

7 min read

Exercise While Coding: Turn Claude Code Wait Time Into Micro-Workouts

7 min read

Claude Code Notch Notifications on Mac: See When Claude Is Done Without Watching the Terminal

7 min read

Claude Code Tips and Tricks: 12 Ways to Use Claude Code Effectively

8 min read

Claude Code Multiple Sessions: How to Run Agents in Parallel Without Losing Track

6 min read

A Claude Code Workflow That Doesn't Involve Watching the Terminal

5 min read

Claude Code Hooks: A Practical Guide to Automating Your Agent Workflow

7 min read

Claude Code Auto Mode: Fewer Permission Prompts Without Living Dangerously

7 min read

Claude Code Subagents: How to Delegate Work to Specialized Agents

7 min read

Claude Code Context Management: Treat the Context Window Like a Budget

6 min read

Per-Subagent Model Selection: Route the Grunt Work Down, Keep the Judgment Up Top

7 min read

Skills and Plugins: How to Teach Claude Code Your Way of Working

7 min read

Claude Code Background Tasks: Run Long Commands Without Blocking Your Session

6 min read

Codex CLI Notifications: How to Get a Ding When Codex Is Done or Needs Input

7 min read

Cursor Notification When Done: Every Way to Get Notified When Cursor Finishes

6 min read

Claude Code Notifications: How to Get Notified When Claude Code Finishes or Needs Your Input

6 min read

Want to Be Notified When Claude Responds? How Claude Notifications Work on Web, Desktop, and Mobile

5 min read

Claude Code Notification Scripts: Copy-Paste Recipes for Every Platform

6 min read

Get a Ding the Moment Codex Needs Your Response

6 min read

Get Notified the Moment Claude Code Is Waiting for Your Input

6 min read

“Notifications Are Turned Off for Claude” — Here Is the Fix

6 min read

Codex Sound When Done: Make Codex CLI Play a Sound When It Finishes

6 min read

terminal-notifier + Claude Code: Native macOS Alerts When Your Agent Finishes

6 min read

Gemini CLI Notifications: How to Get a Sound or Alert When Gemini Finishes

6 min read

Get Claude Code Notifications on Your Phone

6 min read

Claude Code Remote Control, Explained

7 min read

preferredNotifChannel: Claude Code's Built-In Notification Setting

6 min read

Claude Code Notifications in tmux and Over SSH

7 min read

Claude Code Effort Levels: Why Your Setting Keeps Getting Ignored

8 min read

Codex vs Claude Code Notifications: How Each One Tells You It Is Done

8 min read

Claude Code Notifications Not Working: A Diagnostic Checklist

10 min read

Claude Code Notifications Inside Your Editor's Terminal

7 min read

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Explained

7 min read

CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP Explained

8 min read

Cursor Alerts Explained: Every Alert Cursor Raises, and How to Control Them

7 min read

Claude Code Environment Variables: The Groups That Actually Matter

10 min read

Claude Code Notifications on WSL and Windows

9 min read

Claude Code Checkpoints and /rewind

8 min read

Claude Remote Control: How It Works, Turning It Off, and Auto Mode

7 min read

Claude Code /loop: Poll a Deploy, Babysit a PR, and Get Told When It's Done

8 min read

Setting Up NotchFit With OpenAI Codex CLI: Hooks, $notchfit-plan, and the Daily Flow

7 min read

Claude Mods Explained: What the New Plugin Layer Can Do, and How to Turn On 'You Should Know'

9 min read

NotchFit vs Mac Break Reminder Apps: A Clock or a Signal From Your Coding Agent?

8 min read

Claude Code Headless Mode: Running claude -p in Scripts and CI, and the Three Signals That It Finished

10 min read

Building a Movement Habit at a Desk: Use the Agent Run as the Cue, One Set as the Unit, and Streaks Carefully

8 min read

Claude Code MCP Servers Explained: Adding Servers, Choosing a Scope, Handling Secrets, and Why Long Tool Calls Go to the Background

10 min read

/notchfit:plan Explained: How Claude Code or Codex Writes a Weekly Workout Plan the Notch Can Actually Run

8 min read

Claude Code Spinner Verbs Explained: What “Pondering” and “Brewing” Mean, How to Change Them, and Why You Should Stop Watching the Spinner

7 min read

Why NotchFit's Done and Permission Alerts Wait Until Your Set Ends, When That Costs You, and How to Turn the Workout Off

7 min read

How to Resume a Claude Code Session: --continue vs --resume, Naming Sessions, the Session Picker, Branching, and What Comes Back

9 min read

NotchFit on a Mac Without a Notch: How Pill Mode Works on Mac mini, iMac, Mac Studio and a MacBook With the Lid Closed

6 min read

How to Run a Claude Code Session in the Background: /background, claude --bg, Agent View, and Getting Back to It

9 min read

What a Notch App Can See: NotchFit's Local-First Design, What the Claude Code and Codex Hooks Send, and What Stays on Your Mac

7 min read

Why Codex CLI Asks for Permission Every Time, and How to Tune the Sandbox and Approval Policy Without Going Full Access

8 min read

What to Do While Claude Code or Codex Works: A Simple Protocol for the Two-to-Twenty-Minute Gap in Every Agent Run

7 min read

Is It Possible to Get a Notification When Claude Code or Codex Hits a Reset? Yes for Claude Code: the quota_auto_resume Hooks, Explained

8 min read

What a MacBook Notch App Can Actually Do: The Five Kinds of Notch Utility, Their Trade-offs, and Where NotchFit Fits

7 min read

How to Make MCP Servers Not Take Up as Much Context in Claude Code: Tool Search, alwaysLoad, Scopes and Output Caps

8 min read

The notchfit Command Line: Drive Your Workout, Read Status as JSON, Validate Plans and Test the Notch Without Leaving the Terminal

7 min read

How to Audit MCP Tool Calls Made by Claude Code: A Five-Minute Hook Audit Log, OpenTelemetry Tool Events, and the Transcript for Investigations

9 min read

Exercise Snacks: What the Research Actually Says About One-Minute Vigorous Breaks, What It Does Not, and How NotchFit's Agent-Run Sets Compare

8 min read

How Long Until a Claude Code MCP Tool Call Times Out? The Four Timers (Startup, Two-Minute Backgrounding, Idle, Wall-Clock), Their Defaults, and Which One to Change

8 min read

Sitting Too Long as a Developer: The Posture Problems Coding Agents Made Worse, What the Research Says About Breaking Up Sitting, and How NotchFit Turns an Agent Run Into the Break

8 min read

Claude Code .mcp.json Explained: Where Project-Scoped MCP Servers Are Read From, What Happens in Subfolders and Monorepos, and Why a Committed Server Shows Pending Approval

8 min read

Standing Desk Exercises for Developers: Why Standing Still Is Not the Goal, Eight Movements That Fit a Thirty-Second Agent Run, and How NotchFit Cues Them From the Notch

8 min read

The claude mcp Command Reference: add Syntax by Transport, What --scope local, project and user Actually Mean, add-json and add-from-claude-desktop, list, get, remove, login and serve

9 min read

Your First Week With NotchFit: Install and Simulate, Run Real Tasks, Write a Smaller Plan Than You Want, Tune the Alerts, Survive the First Skipped Day, and Decide What Stays

8 min read

How to Stop a Running Claude Code Task: Esc vs Ctrl+C, Background Tasks, Subagents, and Disconnecting Remote Control

8 min read

Pomodoro vs Agent-Driven Breaks: Timing Movement to Claude Code and Codex Runs Instead of a Timer

7 min read

Claude Desktop MCP Configuration: claude_desktop_config.json, Logs, Extensions, and the Difference From Claude Code

9 min read

The 20-20-20 Rule for Developers: Eye Strain, the Evidence, and Agent Runs as the Cue

8 min read

Claude Agent SDK + MCP Servers: mcpServers, allowedTools, Status Checks and Auth

9 min read

Discreet Desk Exercises for an Open-Plan Office While Claude Code Runs

7 min read

claude remote-control Server Mode: Run Claude Code as a Session Server

9 min read

Wrist and Forearm Stretches for Developers: A 60-Second Routine for Every Claude Code Run

7 min read

Claude Remote Control vs Claude Code on the Web: Which to Use and How They Differ

9 min read

Neck and Shoulder Stretches for Developers: A 90-Second Routine Between Agent Runs

7 min read

What Happens When You Step Away From a Claude Code Session: Prompt Cache Expiry, Idle Compaction, and When to Come Back

8 min read

Hip Flexor and Lower Back Stretches for Developers: A Two-Minute Standing Routine Between Agent Runs

7 min read

Claude Code's Monitor Tool: Watch Logs, CI Runs and PRs (Even a WebSocket) and Let Claude React While You Keep Working

7 min read

Hunched Over the Keyboard? Upper-Back (Thoracic) Stretches for Developers: A Two-Minute Seated Routine Between Agent Runs

6 min read

Claude Code Ultrareview: The 15–25 Minute Cloud Review, What to Do While It Runs, and How the Findings Come Back

8 min read

Why Your Legs Go Dead After a Long Claude Code Session: A Two-Minute Standing Calf, Glute and Hamstring Routine Between Agent Runs

7 min read

Rounded Shoulders From Typing? A Two-Minute Chest Opener, Chair Twist and Wall Press Desk Routine for Developers Between Agent Runs

7 min read

Claude Code ultrathink Explained: It Now Runs the Turn at xhigh Effort, How It Differs From /effort, What It Costs in Time, and What to Do While It Runs

7 min read

Best Break Reminder Apps for Mac in 2026: Time Out, Stretchly, BreakTimer, LookAway and NotchFit Compared

7 min read

Claude Code 2.1.319: denyInsteadOfPrompting, MCP Background Tasks and What Changes for Unattended Runs and Notifications

8 min read

Drink Water and Stand Up Cues for Developers: Use Claude Code Agent Runs as Hydration and Standing Reminders

7 min read

Claude Code 2.1.323: Code Mode, Progress Heartbeat, Auto-Mode Fallback and 1M Context — What Changed for Unattended Runs

9 min read

Notch Media Controls on a Mac: What the MacBook Notch Can and Cannot Do, Dynamic Island-Style Apps vs NotchFit

7 min read