docs(cli): agent conversations and conversation management - #399
Conversation
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>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR replaces the stub src/content/docs/cli/agent-conversations.mdx page with a complete feature doc for agent conversation behavior in the Warp CLI, including transcript streaming, tool calls, diffs, questions, task lists, planning, and copying/exporting output. The content is scoped to the changed page, uses the repository's variable conventions already present in the stub, and links to related agent capabilities.
Concerns
- No blocking correctness, security, or documentation-structure concerns found in the attached diff.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
{{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>
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>
hongyi-chen
changed the title
…launch-cli-cli-agent-conversations
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>
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>
| {/* TODO(cli-agent-conversations): streaming responses, markdown and Mermaid rendering, scrolling. */} | ||
| Your prompt appears in the transcript on a highlighted row marked with `>`, followed by the agent's streaming response. The transcript stays pinned to the newest output while the agent responds. Scroll up with the mouse wheel to review earlier output; scroll back to the bottom to resume following new output. While the agent is working, a progress indicator with elapsed time appears above the input. Press `Ctrl+C` once to stop the current response. | ||
|
|
||
| ### Markdown rendering |
There was a problem hiding this comment.
i don't think it's worth mentioning this markdown rendering stuff, not that useful to an end user
There was a problem hiding this comment.
Done in 05fdfdd — collapsed the bulleted list (and the Markdown rendering H3; nothing links to its anchor) into two sentences that keep only the non-obvious caveats: Mermaid renders as source, images show alt text, very long code blocks truncate.
| ## The conversation transcript | ||
|
|
||
| {/* TODO(cli-agent-conversations): streaming responses, markdown and Mermaid rendering, scrolling. */} | ||
| Your prompt appears in the transcript on a highlighted row marked with `>`, followed by the agent's streaming response. The transcript stays pinned to the newest output while the agent responds. Scroll up with the mouse wheel to review earlier output; scroll back to the bottom to resume following new output. While the agent is working, a progress indicator with elapsed time appears above the input. Press `Ctrl+C` once to stop the current response. |
There was a problem hiding this comment.
i don't think the scrolling stuff is necessary, can we simplify that? feels self-explanatory
There was a problem hiding this comment.
Done in 05fdfdd — cut the scroll-up/scroll-down and pinned-to-newest narration. The section now covers only the prompt row, the progress indicator, and Ctrl+C to stop the response.
| ## Tool calls | ||
|
|
||
| {/* TODO(cli-agent-conversations): how tool calls render (commands, file reads, etc.), expand/collapse. */} | ||
| Every tool call the agent makes appears in the transcript in the order it happens, interleaved with the agent's prose. Most tool calls render as a single status row: a colored state glyph followed by a label describing the call, such as reading a file or searching your codebase. The glyph updates as the call moves from pending to running to finished, and failed or canceled calls are marked accordingly. |
There was a problem hiding this comment.
again, this also feels unnecessary for a user to know, you can mention this high level, but i don't think you need to be super detail oriented here
There was a problem hiding this comment.
Done in 05fdfdd — kept the high-level statement (inline status row with glyph + label) and the four navigation bullets, dropped the pending/running/finished/failed glyph state detail. Also swept the rest of the page with the same lens (menu how-tos, click-to-collapse, and double/triple-click narration removed).
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>
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>
harryalbert
left a comment
harryalbert
left a comment
There was a problem hiding this comment.
nice! approving to unblock but had a few small thoughts
| ## The conversation transcript | ||
|
|
||
| {/* TODO(cli-agent-conversations): streaming responses, markdown and Mermaid rendering, scrolling. */} | ||
| Your prompt appears on a highlighted row marked with `>`, followed by the agent's streaming response. While the agent is working, a progress indicator with elapsed time appears above the input; press `Ctrl+C` once to stop the current response. |
There was a problem hiding this comment.
nit, but I feel like this is a little overly detailed? not sure how our other docs look/read but I feel like this UI info isn't as necessary and might become inaccurate as we make small styling changes
There was a problem hiding this comment.
Agreed — trimmed in 819d3a8. Dropped the prompt-row marker and the elapsed-time progress indicator, since both are pure styling that would drift. Kept the two durable bits: the response streams in, and Ctrl+C stops one that's in progress.
The agent's response streams into the transcript below your prompt as it's generated. Press
Ctrl+Conce to stop a response that's still in progress.
On "how our other docs read": the house style is to describe UI by name and function rather than by appearance, so this is the right call for the rest of the CLI pages too.
| 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 | ||
| * `●` - In progress |
There was a problem hiding this comment.
idk if this is possible, but could we make this in progress dot yellow?
There was a problem hiding this comment.
Done in 819d3a8 — and it's accurate to what ships. In crates/warp_tui/src/agent_block_sections.rs, todo_status_glyph maps TodoStatus::InProgress to attention_glyph_style(), which resolves to the active terminal theme's ANSI yellow.
Implemented as a small .glyph-attention utility (src/styles/warp-components.css §20) rather than an inline style, using Starlight's mode-aware --sl-color-orange-high token instead of a fixed hex — Starlight's orange hue is amber, so it reads as terminal yellow while staying legible when the page flips to light mode.
|
|
||
| * `◌` - Pending | ||
| * `●` - In progress | ||
| * `✓` - Completed |
There was a problem hiding this comment.
same question here around a green checkmark
There was a problem hiding this comment.
Done in 819d3a8 — same mechanism, .glyph-success → --sl-color-green-high, matching success_glyph_style() (theme ANSI green) for TodoStatus::Completed.
Left the ◌ pending glyph uncolored, since it renders in normal foreground text. Every glyph keeps its text label, so meaning never depends on color alone.
|
|
||
| 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. | ||
|
|
||
| ### Resuming conversations |
There was a problem hiding this comment.
I think this section should also cover the conversations menu which I think is the main way folks will resume conversations in the TUI. Attaching a demo below:
https://www.loom.com/share/dc054b8fca374155981f58c9a7c3aaef
There was a problem hiding this comment.
Good call — done in 819d3a8. Resuming conversations now leads with the menu instead of the exit command:
There are two ways to pick a past conversation back up:
- The conversation menu - The quickest route, and the one to reach for most of the time. From a running session, open the conversation menu with
/conversationsor←, filter to the conversation you want, and open it.warp --resume- Reopens a specific conversation from your shell as the CLI starts, without going through the menu.
The --resume printout still follows, so the exit path is covered without being framed as the primary one.
Two related notes from the demo:
- The menu is searchable (
query_conversation_entriesinconversation_menu.rs), which the page never said. Added "Start typing to filter the list by title" to Conversation history. - I didn't embed the Loom — it's a share link, and docs video embeds go through
<VideoEmbed>. Happy to add a short GIF of the menu under Conversation history if you think it's worth the visual.
- 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>
- 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>
PR #397 (hyc/launch-cli-cli-conversations) was closed unmerged when #399 absorbed its content into cli/agent-conversations.mdx, but the stub it was meant to fill survived on the launch branch. The sidebar listed it as "Managing conversations" four lines below the real "Agent conversations" page, so the launch would have shipped a nav entry leading to a page that reads "documentation for this page is in progress". - Delete src/content/docs/cli/conversations.mdx. - Drop its sidebar entry in src/sidebar.ts. - Repoint the four inbound links from cloud-and-orchestration.mdx and reference.mdx to the corresponding anchors on cli/agent-conversations. No redirect needed: /cli/conversations has never been published (404 live, and src/content/docs/cli/ does not exist on main). Co-authored-by: Oz <oz-agent@warp.dev>
2 participants
Pages changed
src/content/docs/cli/agent-conversations.mdx(full draft replacing the stub; now also absorbs the conversation-management content from PR docs(cli): conversations #397, which will be closed)Features covered
Ctrl+Cto stop a responseeexpand/collapse all during approval, click-to-toggle per file, collapse after applyThinking...while streaming, collapse toThought for <duration>on finish, click to toggleEnterto confirm,(recommended)badge (confirmed shipped on master), multi-select check marks, Other… free-form answer, multi-question advance≡ Tasksheader, status glyphs (pending/in-progress/completed, canceled struck through), expanded by default,✓ Completed (n/m)progress rows; cross-links agent-platform/capabilities/task-lists/plan <task>, inline plan document, Updated plan entries, click header orCtrl+Shift+Pto toggle; cross-links agent-platform/capabilities/planningcopied to clipboardconfirmation, double/triple-click word/row selection, drag auto-scroll, local clipboard vs OSC 52 over SSH/tmux note,/export-to-clipboardand/export-to-fileAbsorbed from PR #397 (Managing conversations)
/new,/agent,/clear(aliases) with optional immediate prompt argument/conversationsmenu and left-arrow-at-empty-input shortcut (incl. the← for conversationsghost hint); type-to-filter, arrow navigation, Enter/Esc; list includes Warp app conversations and completed cloud agent runs; local-only fallback caution when cloud data fails to load/compact: default and custom summarization instructions; collapsed Conversation summary block, expandablewarp --resume <token>for non-empty conversations;--resumerestores at startup; cross-links cli/referenceDropped/unconfirmed
(recommended)marker (APP-5018): NOT dropped; confirmed shipped (badge rendering wired in the ask-question view and option selector on master).Notes for review
ebinding is documented as active while the approval card is focused, matching its keybinding context.Ctrl+Pcontextual plan toggle (terminals without extended keyboard support) is not documented; the page points to the on-screen hint that shows the exact shortcut.Suggested reviewer(s): harry, ian (moira for markdown rendering)
Co-Authored-By: Oz oz-agent@warp.dev