How to hand a Claude Code session to the cloud and bring it back

Claude Code on the web runs a session in the cloud while your laptop is closed, and claude --teleport brings one back down to your terminal. Going up is the hard part: a session on your computer cannot be uploaded. Here is why, how to hand the work over by hand, what to keep out of it, and how hopsesh does the round trip for you.

Why a session can’t be uploaded

A local Claude Code session is a file on your computer, ~/.claude/projects/<project>/<session-id>.jsonl. Claude Code on the web keeps its sessions on Anthropic’s side and starts each one from a prompt and a repository it clones, usually from GitHub. No command takes a local transcript and turns it into a cloud session, and no other vendor’s cloud takes a conversation either.

So a hand-off to the cloud is two things:

• A briefing: a prompt that tells the cloud session what was done, what is open, what you asked for last and what to check first. It replaces the conversation.
• The code, on GitHub: the cloud works on a clone, so anything you have not pushed does not exist for it. Unpushed commits and uncommitted files have to go up on a branch first.

Coming back is easier. claude --teleport brings the whole cloud conversation into your terminal, because that direction is built in.

The manual way

1. Put the work on a branch. From the repository, commit what the cloud should see and push it to a branch of its own, so your own branch is not touched:

   git switch -c handoff/fix-flaky-tests
   git add -A && git commit -m "WIP for the cloud"
   git push -u origin handoff/fix-flaky-tests

   Check git status first: git add -A stages everything that is not ignored.

2. Write the briefing. A few hundred words is plenty. Say which branch to check out, what the session did, what is left, the last thing you asked for, and what to verify before changing anything, such as git status and the last commits. Say that it is a summary, not the full history.

3. Start the cloud session from the repository with the briefing as its prompt:

   claude --cloud "$(cat briefing.md)"

   The first time, Claude Code asks whether you trust the folder. Claude Code prints a link to the new session on claude.ai, where you can follow and steer it. Cloud sessions use your Claude plan’s allowance.

4. Bring it back when it is done, from a checkout of the same repository:

   claude --teleport <session-id>

   Teleport fetches the cloud session’s branch and opens the conversation in your terminal. Claude Code saves its local copy only after you send a message in it, so send one, even “ok”, before you close it.

What to keep out

The cloud clones what is on the branch, and the briefing is text you send. Neither should hold secrets.

• Files: .env files, SSH keys, .pem and .key files and other credentials belong in .gitignore, never on a hand-off branch, even a short-lived one. Large binaries and Git LFS files usually don’t need to go.
• The briefing: a session’s history often holds tokens and passwords you pasted or a tool printed. Read the briefing before you send it.
• The conversation itself: committing the transcript to the branch to give the cloud more context means anyone who can see the branch can read it.
• Hidden reasoning: Claude Code’s thinking blocks stay with the local session in any case. The cloud session starts fresh from your briefing.

Doing it with hopsesh

hopsesh is a free, open-source command-line tool, terminal UI and app for macOS and Windows that does the steps above for you, from a session on this computer or on another of yours, and in Claude Code or Codex. It runs Claude Code’s own claude --cloud and claude --teleport, signed in as you; it never reads your login and never calls Anthropic’s servers itself.

hopsesh clouds allow claude-cloud            # each cloud is off until you allow it
hopsesh plan claude/<id> --to claude-cloud   # what goes and what stays; changes nothing
hopsesh handoff claude/<id> --to claude-cloud
hopsesh pull claude-cloud:<session-id> --run # bring it home (or paste its link)

In the app, pick the session and choose Move → Hand off to Claude Code cloud…. Before anything happens, the plan shows:

• The briefing, about 2,000 tokens, written by hopsesh from the session, never by a model. Likely secrets are masked, the plan says how many, and you can edit it.
• The branch: a clean branch already on GitHub goes as it is. Otherwise hopsesh pushes a hopsesh/handoff/<date>-<id> branch with a snapshot of your unpushed commits and changed files, without touching your checkout, index or branch. Untracked files go only when you tick them.
• What stays: the conversation, tool output and hidden reasoning, plus credential-like files (.env*, SSH keys, .pem, .key, .npmrc), Git LFS files and files over 50 MB, which never go whatever you pick.

claude --cloud runs in a terminal you see: a tab of the app’s own hopsesh Terminal, or your own terminal app. When Claude Code asks whether it trusts hopsesh’s hand-off folder, you answer, once per repository. hopsesh never answers it and never changes Claude Code’s settings to skip it.

Bringing a cloud session home runs claude --teleport in a new worktree beside your checkout, so your own branch stays as it is, and keeps the cloud’s branch as hopsesh/from/claude-cloud/…. The conversation comes back whole, as Claude Code’s own copy. Send it one message and hopsesh picks it up. From there it is an ordinary session: continue it here, move it to another of your computers, or continue it in Codex.

hopsesh undo takes a hand-off back: it deletes the hand-off branch while the cloud has not pushed to it. The cloud session itself stays in your claude.ai list, since no command can archive it. Once the work is merged, hopsesh clouds cleanup offers to delete the hand-off branch and the cloud’s own claude/… branch, and deletes only what you confirm.

Codex cloud and the others

The same commands work with Codex cloud (--to codex-cloud --env <environment>), which runs each task in an environment you made on the web. For now the codex command can only use older Codex cloud environments, not ones made in today’s Codex cloud. A Codex cloud task comes home as its diff, committed on its own branch, with its title and outcome written as a session. hopsesh can also pass a session from one cloud to the other through your computer, and, experimentally, hand sessions to the GitHub Copilot cloud agent, Jules, Devin and Amp, which have been tested only against stand-ins of their command lines so far.

hopsesh is alpha software. Claude Code cloud and Codex cloud were also checked by hand against the real tools. It is an independent project, not affiliated with Anthropic or OpenAI.

Claude Code sessions and the cloud

Can I upload a local Claude Code session to Claude Code on the web?

No. Claude Code on the web starts each session from a prompt and a repository it clones; no command takes a local transcript. The closest is a briefing: a prompt that says what was done, what is open and what to check first, with the work pushed to a branch the cloud can clone.

What does claude --teleport do?

It brings a Claude Code on the web session down to your terminal: the whole conversation, and the branch the cloud worked on. Run it from a checkout of the same repository, and send one message in it so Claude Code saves the local copy.

Do my unpushed commits and uncommitted files go to the cloud?

Only what is on a branch the cloud can clone. Commit and push the work to a branch first. hopsesh does this for you: it pushes a hand-off branch with a snapshot of unpushed commits and changed files, without touching your checkout, and untracked files go only when you pick them.

How do I keep secrets out of a cloud hand-off?

Keep .env files and keys out of git, and read the prompt before you send it, because a session’s history can hold pasted tokens. hopsesh masks likely secrets in its briefing, shows how many it masked, and never sends .env files, SSH keys, .pem or .key files, whatever you pick.

Can I hand a Claude Code session to Codex cloud instead?

Yes, with hopsesh: hopsesh handoff claude/<id> --to codex-cloud --env <environment> starts a Codex cloud task from the same kind of briefing and branch. For now the codex command can only use older Codex cloud environments.