Cloud handoff and orchestration in the Warp CLI

The Warp CLI connects your terminal sessions to the Oz Platform. You can hand off a local conversation to a cloud agent, pick a finished cloud run back up in your terminal, and coordinate multiple agents working in parallel, all without leaving the CLI.

Hand off to a cloud agent

Handoff promotes your current CLI conversation into a cloud agent run. Use it when a task outgrows your machine: long-running work you don’t want to keep your laptop awake for, or work you want to check on later from another device. The Handoff overview explains the feature across all Warp surfaces; this section covers the CLI flow.

The cloud agent receives the same context as a handoff from the Warp app:

• Conversation history - Warp forks the conversation, so the cloud agent sees the full transcript and your local conversation stays untouched.
• Workspace changes - Warp snapshots your uncommitted repository changes, including untracked files, and applies them in the cloud run.
• Pending input - The optional follow-up prompt and any images attached to the input move to the cloud run.

See what carries over for the full behavior, and Handoff from local to cloud for prerequisites such as cloud conversation storage and an environment whose repos match your local checkout.

Hand off a conversation

1. In an active conversation, run /handoff, or /handoff <prompt> to give the cloud agent a follow-up prompt. The Hand off to cloud card replaces the input area while your transcript stays visible.
2. Review the environment and model shown on the card. The card suggests your most recent environment, preferring one that contains the current repository, and keeps your conversation’s model when that model can run in the cloud. If the model isn’t available in the cloud, the card flags it and you choose a compatible one before continuing.
3. To change either value, press Ctrl+E. The card opens two searchable selector pages, environment then model: ↑ and ↓ move within a page, Enter applies the highlighted value, Tab, ←, or → move between pages, and Esc returns to the summary.
4. Press Enter on the card summary to hand off. The card shows progress, then reports that the cloud run was created along with a link to the run.

From the created card:

• Enter opens the cloud run in your browser.
• C continues the conversation locally. The card collapses into a transcript banner with the run link, and the input reopens.
• N starts a new conversation.

Press Ctrl+C at any point before confirming to cancel the handoff; your prompt and attachments return to the input.

Note

If you have no cloud environments yet, the card prompts you to create one: Enter opens the Environments page in the Oz web app, and R refreshes the list after you create one.

Handoff needs the conversation in a state it can fork. You can’t hand off while a command the agent started is still running, or while the conversation has child agents that are in progress or blocked. Cancel the command or let the children finish first. Handing off an orchestrator forks only its own conversation; the orchestration and its child agents stay local.

Resume cloud conversations

Finished cloud agent runs appear in the CLI’s conversation history alongside local conversations, so you can pull a cloud run into your terminal and keep working on it.

1. Press ← in an empty input, or run /conversations, to open the conversation list.
2. Select a cloud run. The CLI loads its transcript, and your next prompt continues the conversation locally.

Two constraints apply:

• The run must be finished - Cloud runs that are still in progress or blocked can’t be opened in the CLI. Steer those from the browser instead; see Viewing cloud agent runs.
• Warp Agent runs only - Conversations that ran with a different harness, such as Claude Code or Codex, can’t be opened in the CLI.

You can also open a conversation directly at startup with warp --resume <token>. See Managing conversations in the CLI for conversation history and resume details.

Multi-agent orchestration

Orchestration lets one conversation spawn child agents that work in parallel, on your machine or in the cloud. The CLI runs the same parent/child model as the rest of the platform; see Multi-agent orchestration for the model, run states, and common patterns.

To start an orchestration, ask the agent to parallelize the work, for example “split this migration across three agents”. When the agent decides to spawn child agents, the CLI shows an approval card titled Can I start additional agents for this task? that summarizes the agents it wants to launch and the run-wide configuration. No child agents launch until you approve.

From the approval card:

• Enter approves the request and launches the child agents.
• Ctrl+E edits the configuration first: where the agents run (on your machine or in the cloud) and which model they use. Cloud agents add pages for the harness, environment, and host, plus an API key page for harnesses that need one.
• Ctrl+C rejects the request.

After launch, a tab bar labeled Agents: appears above the session with one tab for the orchestrator and one tab per child agent. Messages the parent and children exchange appear in each transcript as collapsible rows with the sender’s name and status.

• Local child agents - Each local child runs on your machine as its own session, starting in the parent’s working directory. Local children always run the Warp Agent.
• Cloud child agents - Each cloud child runs in a cloud environment. Its session shows the run’s live status and a link; press Enter or click the link to open the run in the Oz web app. If a cloud child can’t start because GitHub authentication is required, its session shows the authentication link; authenticate, then ask the agent to run the orchestration again.

Caution

Cloud child sessions in the CLI are read-only status views. To send prompts to a cloud child or respond to its approvals, open the run in the Oz web app.

Managing child agents

The Agents: tab bar is how you move around an orchestration. While it’s available, the empty input shows a Shift + ↑ for other agents hint.

• Focus the tab bar - Press Shift+↑ from the input. The bar highlights the active conversation.
• Switch agents - Tab or → selects the next agent and Shift+Tab or ← the previous one, wrapping across the orchestrator and all children. Shift+← and Shift+→ jump to the first and last child. Switching is immediate and keeps the bar focused so you can keep cycling.
• Return to the conversation - ↓ moves focus back to the current session’s input. Esc jumps back to the orchestrator.
• Use the mouse - Click any tab to switch to that agent. When there are more children than fit, arrows at the ends of the bar page through them without changing your selection.

Each agent keeps its own session. Transcript position, input drafts, and running work are all preserved while you view another agent, and child agents keep working in the background. Tabs reorder as statuses change, moving children that need attention, such as blocked ones, toward the front of the bar.

A focused local child behaves like a regular conversation: send it follow-up prompts, respond to its permission requests, and press Ctrl+C to stop its in-progress response. If a child’s tab shows a blocked status, switch to that child to respond to its pending request.

Related pages

• Handoff overview - Directions of handoff and what carries over in each.
• Handoff from local to cloud - Prerequisites, the Warp app flow, and troubleshooting.
• Multi-agent orchestration - The parent/child model, run states, and orchestration patterns.
• Viewing cloud agent runs - Open, inspect, and continue cloud runs in the Oz web app.
• Managing conversations in the CLI - Conversation history, /conversations, and --resume.
• Environments - Configure the repos, image, and setup commands cloud agents run with.