feat: move a local Claude chat to a cloud workspace (teleport)
Closed
SU
14d ago+1018+1018+0123456789012345678901234567890123456789-5-5-0123456789
Summary
- New Move to cloud button in the chat pane header, beside the history icon. One click continues the current Claude chat in a new cloud workspace, with the same conversation and the same code, including uncommitted work.
- True resume, not a summary: the cloud agent resumes Claude's own session file, so it keeps its full context.
Why / Context
A chat that starts on a laptop often needs to keep running after the laptop closes, or needs a bigger machine. Until now the only way across was to start over in the cloud. Claude ties sessions to a working directory, and cloud workspaces clone only from GitHub, so both the session and the code need a way across.
How It Works
- Desktop (
MoveToCloudButton,useMoveChatToCloud): after a confirm, calls the local host'steleport.prepareClaudeSession, matches the repository against the org's GitHub App repositories, then callscloudWorkspace.create({ repositoryId, branch, agent: "claude", resume })and opens the new workspace. - Local host-service (
teleport.prepareClaudeSession):- Finds the chat's Claude session file through the shared harness-session lookup, in a worker.
- Pushes the worktree to
superset/teleport-<id>. This includes uncommitted and untracked work and goes through a separateGIT_INDEX_FILE, so the user's index, tree and branch do not change. It runs as a worker task (git/pushSnapshot). - Uploads the session file to R2 through
attachment.createUpload.
- API:
cloudWorkspace.createtakes an optionalresume { harnessSessionId, transcriptFileId }. The file is anchored to the workspace, so the box'sattachment.resolvecan reach it, and the launch carries both ids to the box as environment. - Sandbox first boot:
- Downloads the file to
<CLAUDE_CONFIG_DIR>/projects/<encoded worktree>/<id>.jsonl(claudeSessionPath) and rewrites the recordedcwdon each line (rehomeClaudeSession). - Launches the chat (or terminal) with
resumeSessionId. ACPsession/resumethen replays the history into the new chat, sochat.dbis not copied. - If the file cannot be placed, it starts a new session instead of failing the launch.
- Downloads the file to
Manual QA Checklist
Not run yet. This needs a cloud-enabled account and a real sandbox, which I did not have in this session.
- Button shows only for a Claude chat with a session, on a local workspace, with the
cloud-workspacesflag on; hidden on cloud workspaces and for other agents - Confirm → cloud workspace opens; its branch contains the local uncommitted and untracked edits; the local worktree, index and branch are unchanged
- Cloud chat shows the earlier conversation, and the agent answers a question about an earlier turn
- A repo the GitHub App cannot see → clear error toast; a host without the new procedure → "update the host service" toast
- Box with an unreadable or missing transcript → a fresh chat still starts (log:
[sandbox] could not place the moved Claude session) - Chat surface off for the user (terminal launch) →
claude --resume <id>in the terminal
Testing
bun run typecheckinapps/desktop,apps/api,packages/trpc,packages/shared,packages/host-servicebiome checkon changed filesbun run check:i18n(translations added for all 16 shipped locales)bun testfor:packages/shared/src/cloud-agent-launch.test.ts(resume round trip), the newworkers/tasks/git-push-snapshot.test.ts(real repo plus local bare remote: snapshot pushed, worktree untouched), the newteleport/rehome-claude-session.test.ts, host-servicesandbox-self-seed,workers,terminal-agents,no-main-loop-blocking, the desktopusePaneRegistrysuites, the trpccloud-workspacesuites, andpackages/i18n
Design Decisions
- Session file over a handoff prompt: keeps the agent's real context, tool results included, rather than a summary capped at 36k characters.
- Upload from the host, not the renderer: the session file can be large; the host PUTs it straight to R2, and the bytes never pass through the renderer.
- Snapshot through a separate index: shipping uncommitted work needs a commit, but must not touch the user's branch or staging area.
Known Limitations
- Claude only (preset id
claude). Codex and pdev need their own session file placement. - Depends on Claude's undocumented project-directory layout (
claudeProjectDirName), the same dependency the handoff and resume code already has. - Session files over 200 MB are refused.
- If the remote is not GitHub, the branch is pushed before that is detected.
- The local chat stays as it is. Nothing stops both copies from running.
- Not verified end to end: that
claude-agent-acp's session id equals the Claude session file name. The history picker and resume already assume this.
Compatibility / Rollout
- All tRPC changes are additive: an optional
resumeinput oncloudWorkspace.create, and a new host-service procedure. - The API must deploy before a desktop build with this button is used. An older API strips
resume, so the workspace starts from the pushed branch with an idle chat and no history. - A box running an older host-service ignores the new env vars, with the same result.
- A desktop calling a host without
teleport.*gets the "update the host service" toast. - Behind the existing
cloud-workspacesflag.
Rollback
Revert the PR. No data or schema changes. Pushed superset/teleport-* branches stay on remotes and can be deleted by hand.
Summary by cubic
Adds a Move to cloud button in the chat pane that continues a local Claude chat in a new cloud workspace, with the same conversation and code, including uncommitted and untracked work.
Flow
- The local host pushes the worktree snapshot to a new
superset/teleport-*branch through a separate git index, so the user's branch, index and working tree stay unchanged. - Claude's session file is uploaded straight from the host to cloud storage, and the cloud workspace is created with a resume payload so the agent keeps its full context instead of a handoff summary.
- The sandbox downloads the file into Claude's project directory, rewrites the recorded cwd, and resumes the session; if the file cannot be placed, it starts a new session instead of failing the launch.
Rollout
- The API must deploy before a desktop build with this button is used; an older API starts the workspace from the pushed branch with an idle chat and no history, and an older host-service produces the same result.
- Claude only, behind the existing
cloud-workspacesflag.