docs: Warp Agent CLI launch documentation

astro.config.mjs

@@ -167,6 +167,7 @@ export default defineConfig({
 					customSets: [
 						{ label: 'Terminal', description: 'Warp Terminal features and configuration.', paths: ['terminal/**'] },
 						{ label: 'Agents', description: 'Warp\'s agents: capabilities, local agents, and CLI agents.', paths: ['agents/**'] },
+						{ label: 'Warp Agent CLI', description: 'The Warp Agent CLI: agent conversations, shell commands, permissions, and configuration in any terminal.', paths: ['cli/**'] },
 						{ label: 'Oz Platform', description: 'Warp\'s Oz platform: cloud agents, orchestration, triggers, integrations, environments, harnesses, and self-hosting.', paths: ['platform/**'] },
 						{ label: 'Code', description: 'Code editor, code review, and Git worktrees.', paths: ['code/**'] },
 						{ label: 'Enterprise', description: 'Enterprise features, SSO, team management, and security.', paths: ['enterprise/**'] },

src/content/docs/cli/agent-conversations.mdx

@@ -0,0 +1,146 @@
+---
+title: "Agent conversations in the Warp Agent CLI"
+description: >-
+  Learn about agent conversations in the Warp Agent CLI, including streamed responses, tool
+  calls, diffs, task lists, plans, plus how to manage and resume conversations.
+---
+import { VARS } from '@data/vars';
+
+When you send the agent a prompt in the {VARS.WARP_CLI}, the conversation appears as a scrollable transcript directly in your terminal. Responses stream in as they're generated, and everything the agent does renders inline: tool calls, file diffs, questions, task lists, and plans. Conversations persist as you work. You can start a new conversation, browse history, compact context, and [resume after exiting](#resuming-conversations).
+
+## The conversation transcript
+
+The agent's response streams into the transcript below your prompt as it's generated. Press `Ctrl+C` once to stop a response that's still in progress.
+
+Responses render as formatted Markdown, including syntax-highlighted code blocks and tables. Be aware of a few terminal-specific caveats: Mermaid diagrams appear as their source in a code block, images show their alt text instead of rendering inline, and very long code blocks are truncated to keep the transcript responsive.
+
+## Tool calls
+
+Every tool call the agent makes appears inline in the transcript, in the order it happens. Most render as a one-line status row with a state glyph and a label describing the action, like "reading a file" or "searching your codebase".
+
+Some tool calls render richer, interactive content:
+
+* **[Shell commands](/cli/input-and-shell-commands/#shell-mode)** - Commands run in your session, with output streamed into the transcript.
+* **[File edits](#code-diffs)** - Expandable diffs with per-file headers.
+* **[Questions](#agent-questions)** - Interactive option prompts.
+* **[Plans](#planning)** - Inline plan documents.
+
+When a tool call needs your approval before it runs, an approval card appears in place of the input. See [permissions in the CLI](/cli/permissions-and-profiles/) to learn how approvals work.
+
+## Code diffs
+
+When the agent edits files, the edit renders as a diff in the transcript:
+
+* **Per-file sections** - Each edited file gets its own header showing the action taken and the lines added or removed.
+* **Multi-file edits** - Each file's section nests, indented, under one collapsible summary header (for example, `Edited 3 files`).
+
+Diffs are fully expanded while the agent waits for your approval, then collapse to their headers once the edits are applied. Press `e` while the approval card is active to expand or collapse all diffs at once.
+
+## Thinking blocks
+
+For models that expose their reasoning, the agent's thinking streams into a collapsible section with the header `Thinking...`, which collapses to a single `Thought for` row once it finishes.
+
+## Agent questions
+
+When the agent needs a decision from you mid-task, it asks a question with an interactive option list that temporarily replaces the input. Use the arrow keys to navigate between options, or press an option's number on your keyboard to select it. **Other…** accepts a free-form answer when the listed options don't fit.
+
+Options the agent suggests as the best fit are labeled `(recommended)`. For multi-select questions, chosen options are marked with a check mark so you can select more than one. When the agent asks several questions at once, the card advances through them.
+
+## Task lists
+
+For multi-step work, the agent tracks its progress with a task list rendered directly in the transcript under a `≡ Tasks` header. Each task row starts with a status glyph:
+
+* `◌` - Pending
+* <code class="glyph-attention">●</code> - In progress
+* <code class="glyph-success">✓</code> - Completed
+
+Canceled tasks appear struck through. As the agent finishes tasks, compact confirmation rows (e.g., `✓ Completed <task> (2/5)`) track progress without repeating the whole list.
+
+Task lists in the CLI reflect the same agent behavior as in the Warp app. Learn more about [how task lists work](/agents/capabilities/task-lists/).
+
+## Planning
+
+To have the agent first research and produce a plan before making changes, use the `/plan` slash command followed by a description of your task. You can also ask for a plan in natural language.
+
+The plan renders inline in the transcript as a formatted document with its own header row showing the plan's status. An `Updated plan` entry appears when the agent revises it. Press `Ctrl+Shift+P` to expand or collapse the latest plan.
+
+Planning in the CLI follows the same workflow as the Warp app. See [Planning](/agents/capabilities/planning/) to learn how to create, review, and execute plans.
+
+## Selecting and copying output
+
+Select text anywhere in the transcript by clicking and dragging with the mouse. Releasing the mouse button copies the selection automatically.
+
+To copy an entire conversation as Markdown, use the `/export-to-clipboard` slash command, or use `/export-to-file` to save it to a file.
+
+:::note
+In local sessions, the CLI writes directly to your system clipboard. Over SSH, it copies through your terminal using OSC 52 escape sequences (including from inside tmux), so the text lands on your local clipboard. Terminals that disable OSC 52 may ignore the copy.
+:::
+
+## Managing conversations
+
+The CLI saves every agent conversation as you work, so closing your terminal won't lose your progress.
+
+### Conversation persistence
+
+Conversations save to your Warp account, so the same history is available in the Warp app and on your other devices. Reopening a conversation restores the full transcript, including agent responses, tool calls, and file-edit diffs. You can continue prompting from where the agent left off.
+
+The CLI shows one conversation at a time. Opening a past conversation replaces the current transcript, and the previous one remains available in history. You can't switch conversations while the current conversation is responding or a command is running. Finish or stop it with `Ctrl+C` first.
+
+### Starting a new conversation
+
+Use any of these slash commands to clear the transcript and start a fresh conversation:
+
+* `/new`
+* `/agent`
+* `/clear`
+
+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. To keep the history but reduce its size instead, use [`/compact`](#compacting-context).
+
+### Conversation history
+
+To browse and reopen past conversations, you can open the conversation menu in 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 menu lists your Warp Agent conversations, including conversations started in the Warp app and completed cloud agent runs tied to your account. Start typing to filter the list by title.
+
+:::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](/cli/cloud-and-orchestration/).
+
+### Resuming conversations
+
+There are two ways to pick a past conversation back up:
+
+* **The [conversation menu](#conversation-history)** `(recommended)` - From a running session, press `←` or run `/conversations`, then filter to the conversation you want.
+* **`warp --resume`** - Reopens a specific conversation from your shell as the CLI starts, without going through the menu.
+
+When you exit the CLI with a non-empty conversation, it prints the `--resume` command for that conversation:
+
+```bash
+To continue this conversation, run:
+warp --resume YOUR_CONVERSATION_TOKEN
+```
+
+`YOUR_CONVERSATION_TOKEN` is a conversation identifier generated by Warp. For the complete list of command-line flags, see the [CLI reference](/cli/reference/).
+
+### Compacting context
+
+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 <instructions>`** - 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, and the conversation keeps working normally with the summary standing in for the compacted history.
+
+## Related pages
+
+* **[Permissions and profiles](/cli/permissions-and-profiles/)** - Approve, reject, or auto-approve the agent's tool calls.
+* **[Input and shell commands](/cli/input-and-shell-commands/)** - How commands the agent (or you) run appear in the transcript.
+* **[Cloud handoff and orchestration](/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.
+* **[Planning](/agents/capabilities/planning/)** - The full planning workflow.
+* **[Task lists](/agents/capabilities/task-lists/)** - How agents create and update task lists.