From 9dbc856e5cd0b557f7a68f9891e964c147c4855a Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:29:43 -0700 Subject: [PATCH 1/7] docs(cli): draft cloud handoff and orchestration page Fill in cli/cloud-and-orchestration.mdx with the /handoff flow and what context carries over, resuming finished cloud runs from the conversation list, multi-agent orchestration (approval card, local and cloud children), and managing child agents via the agents tab bar. Cross-links the canonical platform/handoff and platform/orchestration pages. Co-Authored-By: Oz --- .../docs/cli/cloud-and-orchestration.mdx | 86 +++++++++++++++++-- 1 file changed, 79 insertions(+), 7 deletions(-) diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx index 70107975..95818a61 100644 --- a/src/content/docs/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/cli/cloud-and-orchestration.mdx @@ -6,22 +6,94 @@ description: >- --- import { VARS } from '@data/vars'; -{/* TODO(cli-cloud-orchestration): draft per drafts/warp-cli-launch-plan.md — "cli/cloud-and-orchestration.mdx" section. Feature-doc content type. */} - -The {VARS.WARP_CLI} documentation for this page is in progress. +The {VARS.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 -{/* TODO(cli-cloud-orchestration): /handoff flow, what context carries over; cross-link platform/handoff. */} +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](/platform/handoff/) 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](/platform/handoff/#what-carries-over) for the full behavior, and [Handoff from local to cloud](/platform/handoff/local-to-cloud/) for prerequisites such as cloud conversation storage and an [environment](/platform/environments/) whose repos match your local checkout. + +### Hand off a conversation + +1. In an active conversation, run `/handoff`, or `/handoff ` 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](https://oz.warp.dev/environments), 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 -{/* TODO(cli-cloud-orchestration): continuing cloud runs in the CLI (--resume, conversation list). */} +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](/platform/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 `. See [Managing conversations in the CLI](/cli/conversations/) for conversation history and resume details. ## Multi-agent orchestration -{/* TODO(cli-cloud-orchestration): orchestrating child agents from the CLI, tab bar navigation; cross-link platform/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](/platform/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](/platform/environments/). 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 -{/* TODO(cli-cloud-orchestration): switching between child agents, stopping a child agent. */} +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](/platform/handoff/) - Directions of handoff and what carries over in each. +* [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Prerequisites, the Warp app flow, and troubleshooting. +* [Multi-agent orchestration](/platform/orchestration/) - The parent/child model, run states, and orchestration patterns. +* [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open, inspect, and continue cloud runs in the Oz web app. +* [Managing conversations in the CLI](/cli/conversations/) - Conversation history, `/conversations`, and `--resume`. +* [Environments](/platform/environments/) - Configure the repos, image, and setup commands cloud agents run with. From af3af378476e6f9f0cf914893bc2ce928e51dbee Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:44:44 -0700 Subject: [PATCH 2/7] docs(cli): use literal Warp CLI in frontmatter {{WARP_CLI}} tokens aren't substituted in MDX frontmatter by the content layer, so replace them with the literal product name in title/description. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz --- src/content/docs/cli/cloud-and-orchestration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx index 95818a61..5a005b47 100644 --- a/src/content/docs/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/cli/cloud-and-orchestration.mdx @@ -1,7 +1,7 @@ --- -title: "Cloud handoff and orchestration in the {{WARP_CLI}}" +title: "Cloud handoff and orchestration in the Warp CLI" description: >- - Hand off {{WARP_CLI}} conversations to cloud agents, resume cloud runs, and + Hand off Warp CLI conversations to cloud agents, resume cloud runs, and run multi-agent orchestration from your terminal. --- import { VARS } from '@data/vars'; From bd6c011b46173f148452a67979346795d7e8669a Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 15:06:47 -0700 Subject: [PATCH 3/7] docs(cli): rename Warp CLI to Warp Agent CLI in frontmatter Follows the confirmed launch name. Body prose picks up the new name via the WARP_CLI content variable from the base branch. Co-Authored-By: Oz --- src/content/docs/cli/cloud-and-orchestration.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx index 5a005b47..c1d2f7de 100644 --- a/src/content/docs/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/cli/cloud-and-orchestration.mdx @@ -1,8 +1,8 @@ --- -title: "Cloud handoff and orchestration in the Warp CLI" +title: "Cloud handoff and orchestration in the Warp Agent CLI" description: >- - Hand off Warp CLI conversations to cloud agents, resume cloud runs, and - run multi-agent orchestration from your terminal. + Hand off Warp Agent CLI conversations to cloud agents, resume cloud runs, + and run multi-agent orchestration from your terminal. --- import { VARS } from '@data/vars'; From a2d88827d7894fbf9f954d3edae5eba2c890d185 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 15:49:05 -0700 Subject: [PATCH 4/7] docs(cli): use WEB_APP vars for Oz web app references Replace hardcoded "Oz web app" text and the oz.warp.dev URL with {VARS.WEB_APP} and VARS.WEB_APP_URL page-wide so a future rename is a one-line change. Co-Authored-By: Oz --- src/content/docs/cli/cloud-and-orchestration.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx index c1d2f7de..a8946a1c 100644 --- a/src/content/docs/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/cli/cloud-and-orchestration.mdx @@ -36,7 +36,7 @@ From the created card: 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](https://oz.warp.dev/environments), and `R` refreshes the list after you create one. +If you have no cloud environments yet, the card prompts you to create one: `Enter` opens the Environments page in the {VARS.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. @@ -70,10 +70,10 @@ From the approval card: 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](/platform/environments/). 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. +* **Cloud child agents** - Each cloud child runs in a cloud [environment](/platform/environments/). Its session shows the run's live status and a link; press `Enter` or click the link to open the run in the {VARS.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. +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 {VARS.WEB_APP}. ::: ## Managing child agents @@ -94,6 +94,6 @@ A focused local child behaves like a regular conversation: send it follow-up pro * [Handoff overview](/platform/handoff/) - Directions of handoff and what carries over in each. * [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Prerequisites, the Warp app flow, and troubleshooting. * [Multi-agent orchestration](/platform/orchestration/) - The parent/child model, run states, and orchestration patterns. -* [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open, inspect, and continue cloud runs in the Oz web app. +* [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open, inspect, and continue cloud runs in the {VARS.WEB_APP}. * [Managing conversations in the CLI](/cli/conversations/) - Conversation history, `/conversations`, and `--resume`. * [Environments](/platform/environments/) - Configure the repos, image, and setup commands cloud agents run with. From b570803e5728d62dcfce3580b6ae30ef833fc9d1 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:06:18 -0700 Subject: [PATCH 5/7] docs(cli): vary repeated see-link phrasing Co-Authored-By: Oz --- src/content/docs/cli/cloud-and-orchestration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx index a8946a1c..a16a2c12 100644 --- a/src/content/docs/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/cli/cloud-and-orchestration.mdx @@ -53,11 +53,11 @@ 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](/platform/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 `. See [Managing conversations in the CLI](/cli/conversations/) for conversation history and resume details. +You can also open a conversation directly at startup with `warp --resume `; [Managing conversations in the CLI](/cli/conversations/) covers 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](/platform/orchestration/) for the model, run states, and common patterns. +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; [Multi-agent orchestration](/platform/orchestration/) covers 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 72a9c811a9a11710669b3f04401c71a46128088c Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:25:40 -0700 Subject: [PATCH 6/7] docs(cli): trim narration of obvious UI mechanics Cut selector arrow/Enter/Esc menu mechanics, transcript-load narration, and tab-click narration per editorial direction. Non-obvious keys, defaults, and caveats kept. Co-Authored-By: Oz --- src/content/docs/cli/cloud-and-orchestration.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx index a16a2c12..4053f144 100644 --- a/src/content/docs/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/cli/cloud-and-orchestration.mdx @@ -24,7 +24,7 @@ See [what carries over](/platform/handoff/#what-carries-over) for the full behav 1. In an active conversation, run `/handoff`, or `/handoff ` 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. +3. To change either value, press `Ctrl+E` to open the searchable environment and model selectors. 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: @@ -46,7 +46,7 @@ Handoff needs the conversation in a state it can fork. You can't hand off while 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. +2. Select a cloud run. Your next prompt continues the conversation locally. Two constraints apply: @@ -81,9 +81,9 @@ Cloud child sessions in the CLI are read-only status views. To send prompts to a 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. +* **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 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. +* **Use the mouse** - Tabs are clickable, and 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. From 536cde4c5ec87763d070f586a876fc0eb243017f Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:38:03 -0700 Subject: [PATCH 7/7] docs(cli): apply editorial audit cuts Compress handoff step 2, drop the redundant Shift+Up input-hint sentence, and shorten the parent/child message description. Co-Authored-By: Oz --- src/content/docs/cli/cloud-and-orchestration.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx index 4053f144..0099539f 100644 --- a/src/content/docs/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/cli/cloud-and-orchestration.mdx @@ -23,7 +23,7 @@ See [what carries over](/platform/handoff/#what-carries-over) for the full behav ### Hand off a conversation 1. In an active conversation, run `/handoff`, or `/handoff ` 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. +2. The card suggests your most recent environment (preferring one that contains the current repository) and keeps your conversation's model when it can run in the cloud; incompatible models are flagged so you can choose another before continuing. 3. To change either value, press `Ctrl+E` to open the searchable environment and model selectors. 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. @@ -67,7 +67,7 @@ From the approval card: * `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. +After launch, a tab bar labeled **Agents:** appears above the session with one tab for the orchestrator and one tab per child agent. Messages between the parent and child agents appear in each agent's transcript. * **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](/platform/environments/). Its session shows the run's live status and a link; press `Enter` or click the link to open the run in the {VARS.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. @@ -78,7 +78,7 @@ Cloud child sessions in the CLI are read-only status views. To send prompts to a ## 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. +The **Agents:** tab bar is how you move around an orchestration. * **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 keeps the bar focused so you can keep cycling.