Skip to content

Commit d12e1b6

Browse files
hongyi-chenoz-agent
hongyi-chen
and
oz-agent
authored
docs(cli): agent conversations and conversation management (#399)
* docs(cli): draft agent conversations page Covers the streaming transcript, Markdown/Mermaid rendering, tool-call rows, file-edit diffs, thinking blocks, interactive agent questions, task lists, /plan flow, and transcript selection/copy for the Warp CLI. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in frontmatter {{WARP_CLI}} tokens are not substituted in MDX frontmatter by the content layer, so built titles/descriptions showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): absorb conversation management into agent conversations page Adds a Managing conversations section group (persistence/restore, /new /agent /clear, /conversations menu + left-arrow shortcut, /compact, exit summary + --resume) from the standalone conversations page, which is being removed in the consolidation. Updates the intro, description, and related pages accordingly. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename to Warp Agent CLI in frontmatter Follows the launch-name change; body prose picks up the new name via the WARP_CLI var from the base branch merge. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial polish on agent conversations page Reduces product-name repetition after the intro, links bold lead terms in the tool-call list instead of trailing See-X sentences, swaps 'unfolds' for 'appears', fixes 'just', and de-metas the intro's managing-conversations pointer. No factual, heading, or link-target changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim self-evident UI narration per review Per PR review: cut transcript scrolling narration, collapse the markdown-features list to its non-obvious caveats (folding the H3), drop the tool-call glyph state-machine detail, and sweep the rest of the page with the same lens (menu how-tos, click-to-collapse, and double/triple-click narration removed). Feature facts, caveats, shortcuts, and cross-links are unchanged. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): apply editorial audit cuts Seven targeted trims: intro filler sentence, diff-header bullet detail, multi-question tail, bold header adjective, copy-confirmation footer mention, managing-conversations enumeration, and history restore phrasing. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): address review feedback on agent conversations - Trim styling narration from the transcript intro (prompt row marker, elapsed-time progress indicator) that would go stale with small UI changes; keep the durable behavior (streaming, Ctrl+C to stop). - Color the task-list status glyphs to match the TUI: yellow in-progress dot and green completed check, via mode-aware Starlight hue tokens so they stay legible in dark and light mode. - Lead "Resuming conversations" with the conversation menu, the primary way to resume in the CLI, and note type-to-filter in the menu. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial pass for redundancy and flow - Collapse three separate "restores the full transcript" statements into one, in Conversation persistence, where the detail belongs. - Replace the duplicated "saved automatically" claim with the account vs. local-machine distinction, which sets up the menu contents and the offline caution that follow. - Move Resuming conversations next to Conversation history so the two cross-referencing sections are adjacent instead of split by Compacting context. - Point the intro's resume link at #resuming-conversations directly, and fix a dangling modifier in the tool-call description. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>
1 parent 95fbeef commit d12e1b6

2 files changed

Lines changed: 141 additions & 14 deletions

File tree

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

Lines changed: 117 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,146 @@
11
---
2-
title: "Agent conversations in the {{WARP_CLI}}"
2+
title: "Agent conversations in the Warp Agent CLI"
33
description: >-
4-
How agent conversations work in the {{WARP_CLI}}: streaming responses, tool
5-
calls, code diffs, agent questions, task lists, and planning.
4+
How agent conversations work in the Warp Agent CLI: streaming responses, tool
5+
calls, diffs, task lists, plans, plus managing and resuming conversations.
66
---
77
import { VARS } from '@data/vars';
88

9-
{/* TODO(cli-agent-conversations): draft per drafts/warp-cli-launch-plan.md — "cli/agent-conversations.mdx" section. Feature-doc content type. */}
10-
11-
The {VARS.WARP_CLI} documentation for this page is in progress.
9+
When you send the agent a prompt in the {VARS.WARP_CLI}, the conversation appears in a scrollable transcript directly in your terminal. Responses stream in as they're generated, and everything the agent does along the way renders inline: tool calls, file diffs, questions, task lists, and plans. Conversations persist as you work: you can start new ones, browse history, compact context, and [resume after exiting](#resuming-conversations).
1210

1311
## The conversation transcript
1412

15-
{/* TODO(cli-agent-conversations): streaming responses, markdown and Mermaid rendering, scrolling. */}
13+
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.
14+
15+
Responses render as formatted Markdown, including syntax-highlighted code blocks and tables. 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.
1616

1717
## Tool calls
1818

19-
{/* TODO(cli-agent-conversations): how tool calls render (commands, file reads, etc.), expand/collapse. */}
19+
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, such as reading a file or searching your codebase.
20+
21+
Some tool calls render richer, interactive content instead:
22+
23+
* **[Shell commands](/cli/shell-commands/)** - Run in your session and stream their output into the transcript.
24+
* **[File edits](#code-diffs)** - Expandable diffs with per-file headers.
25+
* **[Questions](#agent-questions)** - Interactive option prompts.
26+
* **[Plans](#planning)** - Inline plan documents.
27+
28+
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/) for how approvals work.
2029

2130
## Code diffs
2231

23-
{/* TODO(cli-agent-conversations): file-edit diffs, expanded by default, `e` to expand/collapse all. */}
32+
When the agent edits files, the edit renders as a diff in the transcript:
33+
34+
* **Per-file sections** - Each edited file gets a header with the action and change counts.
35+
* **Multi-file edits** - Group under one summary header (for example, `Edited 3 files`) with each file's section nested beneath it.
36+
37+
Diffs open fully expanded while the agent waits for your approval, and 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.
2438

2539
## Thinking blocks
2640

27-
{/* TODO(cli-agent-conversations): collapsed reasoning blocks. */}
41+
For models that expose their reasoning, the agent's thinking streams into a collapsible section headed `Thinking...`, which collapses to a single `Thought for` row once it finishes.
2842

2943
## Agent questions
3044

31-
{/* TODO(cli-agent-conversations): interactive question prompts, option selection, recommended answers. */}
45+
When the agent needs a decision from you mid-task, it asks a question with an interactive option list that temporarily replaces the input. Besides the arrow keys, you can press an option's number to choose it, and **Other…** accepts a free-form answer when the listed options don't fit.
46+
47+
Options the agent suggests as the best fit are labeled `(recommended)`. Multi-select questions mark each chosen option with a check mark so you can pick several. When the agent asks several questions at once, the card advances through them.
3248

3349
## Task lists
3450

35-
{/* TODO(cli-agent-conversations): agent task list rendering and progress. */}
51+
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:
52+
53+
* `◌` - Pending
54+
* <code class="glyph-attention">●</code> - In progress
55+
* <code class="glyph-success">✓</code> - Completed
56+
57+
Canceled tasks appear struck through. As the agent finishes tasks, compact confirmation rows such as `✓ Completed <task> (2/5)` mark progress without repeating the whole list.
58+
59+
Task lists in the CLI reflect the same agent behavior as in the Warp app. Learn more about [how task lists work](/agent-platform/capabilities/task-lists/).
3660

3761
## Planning
3862

39-
{/* TODO(cli-agent-conversations): /plan command and plan review flow; cross-link agent-platform/capabilities/planning. */}
63+
Use the `/plan` slash command, followed by a description of your task, to have the agent research first and produce a plan before making changes. You can also ask for a plan in natural language.
64+
65+
The plan renders inline in the transcript as a formatted document with its own header row showing the plan's status, and an `Updated plan` entry appears when the agent revises it. Toggle the latest plan with `Ctrl+Shift+P`; while a plan is open, a hint below it shows the exact shortcut.
66+
67+
Planning in the CLI follows the same workflow as the Warp app. See [Planning](/agent-platform/capabilities/planning/) for how plans are created, reviewed, and executed.
4068

4169
## Selecting and copying output
4270

43-
{/* TODO(cli-agent-conversations): transcript selection, copy behavior, opt-in auto-copy on select. */}
71+
Select text anywhere in the transcript by dragging with the mouse. Releasing the mouse button copies the selection automatically.
72+
73+
:::note
74+
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.
75+
:::
76+
77+
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.
78+
79+
## Managing conversations
80+
81+
The CLI saves every agent conversation as you work, so closing your terminal never loses your progress.
82+
83+
### Conversation persistence
84+
85+
Conversations save to your Warp account rather than only to your machine, 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 carry on prompting from where it left off.
86+
87+
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.
88+
89+
### Starting a new conversation
90+
91+
Use any of these slash commands to clear the transcript and start a fresh conversation:
92+
93+
* **`/new`** - Starts a new conversation.
94+
* **`/agent`** - Same as `/new`.
95+
* **`/clear`** - Same as `/new`.
96+
97+
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).
98+
99+
### Conversation history
100+
101+
To browse and reopen past conversations, open the conversation menu in either of two ways:
102+
103+
* **`/conversations`** - Run the slash command from the input.
104+
* **`←`** - 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.
105+
106+
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.
107+
108+
:::caution
109+
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.
110+
:::
111+
112+
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/).
113+
114+
### Resuming conversations
115+
116+
There are two ways to pick a past conversation back up:
117+
118+
* **The [conversation menu](#conversation-history)** - The quickest route, and the one to use most of the time. From a running session, press `←` or run `/conversations`, then filter to the conversation you want.
119+
* **`warp --resume`** - Reopens a specific conversation from your shell as the CLI starts, without going through the menu.
120+
121+
When you exit the CLI with a non-empty conversation, it prints the `--resume` command for that conversation:
122+
123+
```bash
124+
To continue this conversation, run:
125+
warp --resume YOUR_CONVERSATION_TOKEN
126+
```
127+
128+
YOUR_CONVERSATION_TOKEN is a conversation identifier generated by Warp. For the complete list of command-line flags, see the [CLI reference](/cli/reference/).
129+
130+
### Compacting context
131+
132+
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.
133+
134+
* **`/compact`** - Summarizes the conversation history with default instructions.
135+
* **`/compact <instructions>`** - Adds custom summarization instructions. For example, `/compact keep the API design decisions` tells the agent what to preserve in the summary.
136+
137+
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.
138+
139+
## Related pages
140+
141+
* **[Permissions and profiles](/cli/permissions-and-profiles/)** - Approve, reject, or auto-approve the agent's tool calls.
142+
* **[Running shell commands](/cli/shell-commands/)** - How commands the agent (or you) run appear in the transcript.
143+
* **[Cloud handoff and orchestration](/cli/cloud-and-orchestration/)** - Hand off conversations to cloud agents and resume cloud runs.
144+
* **[{VARS.WARP_CLI} reference](/cli/reference/)** - Command-line flags, slash commands, and keyboard shortcuts.
145+
* **[Planning](/agent-platform/capabilities/planning/)** - The full planning workflow.
146+
* **[Task lists](/agent-platform/capabilities/task-lists/)** - How agents create and update task lists.

‎src/styles/warp-components.css‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1561,3 +1561,27 @@ site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-
15611561
:root[data-theme='light'] .warp-search-keyboard-hints__kbd {
15621562
background: rgba(0, 0, 0, 0.06);
15631563
}
1564+
1565+
/* --------------------------------------------------------------------------
1566+
20. Terminal status glyphs — inline color for CLI transcript indicators
1567+
--------------------------------------------------------------------------
1568+
The Warp Agent CLI paints status glyphs with the active terminal theme's
1569+
ANSI colors — yellow while something is in progress, green once it
1570+
succeeds. Tinting the same glyph inline lets a docs bullet read the way
1571+
the transcript actually looks on screen.
1572+
1573+
Applied to `<code>` so the glyph keeps the inline-code chip that plain
1574+
Markdown backticks produce; only the foreground changes. Starlight's
1575+
mode-aware `-high` hue tokens are used instead of fixed hex values, so
1576+
the glyphs stay legible when the page flips between dark and light mode.
1577+
1578+
Color is decorative here: every glyph is paired with a text label, so
1579+
meaning never depends on color alone. */
1580+
1581+
.sl-markdown-content code.glyph-attention {
1582+
color: var(--sl-color-orange-high);
1583+
}
1584+
1585+
.sl-markdown-content code.glyph-success {
1586+
color: var(--sl-color-green-high);
1587+
}

0 commit comments

Comments
 (0)