From ca8304af7cc219a6d75726c9df49949070e78c08 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:24:35 -0700 Subject: [PATCH 1/2] docs(cli): draft conversations page (persistence, history, compact, resume) Replace the cli/conversations.mdx stub with a full draft covering conversation persistence and restore, /new//agent//clear, the /conversations history menu (including the left-arrow shortcut), /compact and the collapsed summary block, and the exit/--resume flow. Co-Authored-By: Oz --- src/content/docs/cli/conversations.mdx | 61 ++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 8 deletions(-) diff --git a/src/content/docs/cli/conversations.mdx b/src/content/docs/cli/conversations.mdx index de6c9fbc..265b10a2 100644 --- a/src/content/docs/cli/conversations.mdx +++ b/src/content/docs/cli/conversations.mdx @@ -6,26 +6,71 @@ description: >- --- import { VARS } from '@data/vars'; -{/* TODO(cli-conversations): draft per drafts/warp-cli-launch-plan.md — "cli/conversations.mdx" section. Feature-doc content type. */} - -The {VARS.WARP_CLI} documentation for this page is in progress. +The {VARS.WARP_CLI} saves every agent conversation as you work, so closing your terminal never loses your progress. You can start fresh conversations, reopen past ones from a searchable history, compact long conversations to free up context, and resume a conversation after exiting the CLI. ## Conversation persistence -{/* TODO(cli-conversations): conversations persist across sessions and restore with full detail. */} +The {VARS.WARP_CLI} saves conversations to your Warp account automatically. There is no separate save step. When you reopen a past conversation, the CLI restores the full transcript, including agent responses, tool calls, and file-edit diffs, so you can review earlier work in detail before continuing. + +The CLI shows one conversation at a time. Opening a past conversation replaces the current transcript, and your previous conversation remains available in the conversation history. You can't switch conversations while the current conversation is responding or while a command is running; wait for it to finish or stop it with `Ctrl+C` first. ## Starting a new conversation -{/* TODO(cli-conversations): /new, /agent, /clear. */} +Use any of these slash commands to clear the transcript and start a fresh conversation: + +* **`/new`** - Starts a new conversation. +* **`/agent`** - Same as `/new`. +* **`/clear`** - Same as `/new`. + +Each command accepts an optional prompt. For example, `/new write tests for the parser` starts a new conversation and immediately sends that prompt to the agent. + +Starting a new conversation is useful when you switch tasks. The agent begins with a clean context window, and you avoid carrying over history that is no longer relevant. If you want to keep the history but reduce its size instead, use [`/compact`](#compacting-context). ## Conversation history -{/* TODO(cli-conversations): /conversations menu and navigation into past conversations. */} +To browse and reopen past conversations, open the conversation menu in either of two ways: + +* **`/conversations`** - Run the slash command from the input. +* **`←`** - Press the left arrow key when the input is empty and the cursor is at the start. The empty input shows a `← for conversations` hint as a reminder. + +The menu lists your Warp Agent conversations, including conversations started in the Warp app and completed cloud agent runs tied to your account. To use the menu: + +1. Type to filter conversations by title. +2. Press `↑` and `↓` to change the selection. +3. Press `Enter` to open the selected conversation, or `Esc` to close the menu. + +Opening a conversation restores its transcript with tool calls and diffs intact, and new prompts you send continue that conversation. + +:::caution +If the CLI can't load conversation data from Warp's servers, the menu shows conversations from your local device only and displays a warning. Conversations from other devices reappear once the connection recovers. +::: + +To continue a cloud agent run from the CLI, or to hand the current conversation off to a cloud agent, see [cloud handoff and orchestration in the {VARS.WARP_CLI}](/cli/cloud-and-orchestration/). ## Compacting context -{/* TODO(cli-conversations): /compact, when to use it, what the summary block looks like. */} +Long conversations eventually fill the model's context window, which can degrade response quality. The `/compact` command frees up context by asking the agent to summarize the conversation history so far and carry only the summary forward. + +* **`/compact`** - Summarizes the conversation history with default instructions. +* **`/compact `** - Adds custom summarization instructions. For example, `/compact keep the API design decisions` tells the agent what to preserve in the summary. + +After compaction, a collapsed **Conversation summary** block appears in the transcript. The summary stays collapsed so it doesn't crowd the transcript; select it to expand the full summary text. The conversation keeps working normally after compaction, with the summary standing in for the compacted history. ## Resuming conversations -{/* TODO(cli-conversations): exit summary with resume command; `--resume` flag. */} +When you exit the {VARS.WARP_CLI} with a non-empty conversation, it prints a command for picking that conversation back up: + +```bash +To continue this conversation, run: +warp --resume YOUR_CONVERSATION_TOKEN +``` + +Run the printed command to reopen the conversation in a new CLI session. YOUR_CONVERSATION_TOKEN is a conversation identifier generated by Warp; you don't need to record it yourself as long as you can scroll back to the exit message, and the same conversation also remains available from the [`/conversations` menu](#conversation-history). + +The `--resume` flag loads the conversation at startup and restores the full transcript, so you can continue prompting where you left off. For the complete list of command-line flags, see the [{VARS.WARP_CLI} reference](/cli/reference/). + +## Related pages + +* [Agent conversations in the {VARS.WARP_CLI}](/cli/agent-conversations/) - How transcripts, tool calls, diffs, and agent questions render +* [Cloud handoff and orchestration in the {VARS.WARP_CLI}](/cli/cloud-and-orchestration/) - Hand off conversations to cloud agents and resume cloud runs +* [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts From b2a1cd4687334db544af73fe83dcd8238a9ea8c5 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:44:50 -0700 Subject: [PATCH 2/2] docs(cli): use literal Warp CLI in conversations frontmatter {{WARP_CLI}} tokens are not substituted in MDX frontmatter by the build pipeline, so the built title/description showed the raw token. Body {VARS.WARP_CLI} usages are unchanged. Co-Authored-By: Oz --- src/content/docs/cli/conversations.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cli/conversations.mdx b/src/content/docs/cli/conversations.mdx index 265b10a2..5b7cdeeb 100644 --- a/src/content/docs/cli/conversations.mdx +++ b/src/content/docs/cli/conversations.mdx @@ -1,7 +1,7 @@ --- -title: "Managing conversations in the {{WARP_CLI}}" +title: "Managing conversations in the Warp CLI" description: >- - Start, switch, compact, and resume agent conversations in the {{WARP_CLI}}, + Start, switch, compact, and resume agent conversations in the Warp CLI, including conversation history and the --resume flag. --- import { VARS } from '@data/vars';