feat: move a local Claude chat to a cloud workspace (teleport)

Closed
SU
14d ago
+1018-5

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

  1. Desktop (MoveToCloudButton, useMoveChatToCloud): after a confirm, calls the local host's teleport.prepareClaudeSession, matches the repository against the org's GitHub App repositories, then calls cloudWorkspace.create({ repositoryId, branch, agent: "claude", resume }) and opens the new workspace.
  2. 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 separate GIT_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.
  3. API: cloudWorkspace.create takes an optional resume { harnessSessionId, transcriptFileId }. The file is anchored to the workspace, so the box's attachment.resolve can reach it, and the launch carries both ids to the box as environment.
  4. Sandbox first boot:
    • Downloads the file to <CLAUDE_CONFIG_DIR>/projects/<encoded worktree>/<id>.jsonl (claudeSessionPath) and rewrites the recorded cwd on each line (rehomeClaudeSession).
    • Launches the chat (or terminal) with resumeSessionId. ACP session/resume then replays the history into the new chat, so chat.db is not copied.
    • If the file cannot be placed, it starts a new session instead of failing the launch.

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-workspaces flag 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 typecheck in apps/desktop, apps/api, packages/trpc, packages/shared, packages/host-service
  • biome check on changed files
  • bun run check:i18n (translations added for all 16 shipped locales)
  • bun test for: packages/shared/src/cloud-agent-launch.test.ts (resume round trip), the new workers/tasks/git-push-snapshot.test.ts (real repo plus local bare remote: snapshot pushed, worktree untouched), the new teleport/rehome-claude-session.test.ts, host-service sandbox-self-seed, workers, terminal-agents, no-main-loop-blocking, the desktop usePaneRegistry suites, the trpc cloud-workspace suites, and packages/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 resume input on cloudWorkspace.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-workspaces flag.

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-workspaces flag.