mirror of
https://github.com/stablyai/orca.git
synced 2026-10-30 16:47:34 +00:00
docs(chat): explain structured sessions and conversation handoffs (#32063)
* docs(chat): explain structured sessions and conversation handoffs * docs(chat): distinguish copy handoffs from in-place view switches Same labels mean different things by surface: tab/header Continue in Chat UI opens a new structured chat, while the terminal-pane context menu toggles the transcript view in place. Scope composer live-value routing by session type. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Neil
Claude
@@ -1,25 +1,48 @@
|
||||
---
|
||||
title: Chat UI (native chat)
|
||||
description: Optional chat surface over supported agent terminals — skills, model pickers, and transcript view.
|
||||
description: Open supported agents in structured chat and continue conversations in chat or the terminal.
|
||||
---
|
||||
|
||||
import { Callout } from '@/components/docs/prose'
|
||||
|
||||
Chat UI is an experimental view layered on supported agent terminal sessions. The terminal remains the source of truth; Chat UI is a structured transcript + composer for the same PTY. Transcript decoding covers **Claude**, **Codex**, **Grok**, and **OMP** — OMP sessions open in Chat UI like the others instead of staying raw-terminal-only.
|
||||
Chat UI is an experimental conversation view with a transcript, composer, and agent controls. Supported new agent sessions open in **structured chat**, which communicates directly with the agent rather than displaying a terminal session. Other agents and unsupported execution environments open in the terminal.
|
||||
|
||||
Existing terminal-backed chats use a transcript view over an agent running in a terminal. These keep their original form; turning Chat UI on or off does not convert existing sessions.
|
||||
|
||||
## Enable
|
||||
|
||||
1. Open **Settings → Experimental → Chat UI**.
|
||||
1. Turn **Chat UI** on.
|
||||
1. Optionally set **Default view** to **Chat UI** so new supported agent tabs open in chat; keep **Terminal** to open the TUI first.
|
||||
1. Open a new supported agent tab to start in structured chat. Turn **Chat UI** off to open new agents in the terminal instead. Existing chats stay available.
|
||||
|
||||
Toggle Chat UI ↔ terminal from the agent pane once enabled.
|
||||
You can also choose which supported agents open as chats under **Settings → Chat → Providers**. Turning an agent off there makes its new sessions open in the terminal.
|
||||
|
||||
## Continue a conversation in chat or the terminal
|
||||
|
||||
To open a saved conversation in another form:
|
||||
|
||||
1. Open **Agent Session History** in the right sidebar.
|
||||
1. Open the conversation's menu.
|
||||
1. Choose **Resume in New Chat** for a supported CLI conversation, or **Resume in New Terminal** for a supported chat conversation.
|
||||
|
||||
Both actions open a new tab with a copy of the conversation; the original stays unchanged. For example, **Resume in New Terminal** copies a Claude or Codex chat into a new CLI session. These actions depend on the agent, saved conversation, and execution host; they are not available for every session. Older Orca versions label them **Resume in New Native Chat** and **Resume in New CLI**.
|
||||
|
||||
You can also right-click an open agent tab:
|
||||
|
||||
- On a structured chat tab, **Continue with Terminal Agent** starts a new terminal agent with a copy of the conversation.
|
||||
- On a supported terminal agent tab, **Continue in Chat UI** opens the conversation in a new structured chat. The terminal pane header shows the same action as a chat button.
|
||||
|
||||
## Switch an existing terminal-backed chat
|
||||
|
||||
Structured chat tabs have no in-place terminal view; use **Continue with Terminal Agent** above instead.
|
||||
|
||||
A terminal-backed chat is a view over a running terminal agent, so switching it does not create a new session. Use the pane header's **Show terminal** button, or **Continue with Terminal Agent** in its tab menu, to return to the terminal. Right-clicking inside a supported terminal pane offers **Continue in Chat UI**, which shows that same terminal session as a transcript instead of creating a structured chat.
|
||||
|
||||
## Composer
|
||||
|
||||
- Type a message and send (or stop a working turn). Attach files/images when the host supports it. Unsent draft text and attachments stay with the pane across disconnect/reconnect when the host can restore them. A settled transcript also stays on screen while the same session reconnects, instead of blanking until the fresh load finishes (desktop and mobile share that retention).
|
||||
- Type `/` for slash commands and discovered **skills** (filtered per agent when possible). The slash catalog is agent-aware (Claude vs Codex command sets) and shared with mobile Chat UI.
|
||||
- Use the **model** and options pills (thought level, mode, agent-specific session options) when the agent exposes them. **Claude** model choices come from the **installed Claude CLI on that host** (not a hardcoded list), so new models show up after you update the CLI. **Codex** supports direct model selection from the pill (sends `/model <id>`), with bare `/model` still opening the agent picker. **Grok** exposes **model** (`-m` at launch, `/model` mid-session) and **reasoning effort** (`--reasoning-effort` at launch, `/effort` mid-session); the model list is probed from the signed-in Grok CLI (`grok models`) so retired ids drop out of the picker. Effort choices follow the selected model: Grok 4.6 includes **Extra high**, while Grok 4.5 stops at **High**. **Before the agent process starts**, the composer can show draft launch options that apply on first start; after the session is live, pills that only affect a running turn stay disabled or labeled until the session is ready. Live values go to the CLI in that tab.
|
||||
- Use the **model** and options pills (thought level, mode, agent-specific session options) when the agent exposes them. **Claude** model choices come from the **installed Claude CLI on that host** (not a hardcoded list), so new models show up after you update the CLI. **Codex** supports direct model selection from the pill (sends `/model <id>`), with bare `/model` still opening the agent picker. **Grok** exposes **model** (`-m` at launch, `/model` mid-session) and **reasoning effort** (`--reasoning-effort` at launch, `/effort` mid-session); the model list is probed from the signed-in Grok CLI (`grok models`) so retired ids drop out of the picker. Effort choices follow the selected model: Grok 4.6 includes **Extra high**, while Grok 4.5 stops at **High**. **Before the agent process starts**, the composer can show draft launch options that apply on first start; after the session is live, pills that only affect a running turn stay disabled or labeled until the session is ready. In a structured chat, live values go to the agent session; in a terminal-backed chat, they go to the CLI in that tab.
|
||||
|
||||
## Questions from the agent
|
||||
|
||||
@@ -27,7 +50,7 @@ When Claude shows an **AskUserQuestion** (or similar structured permission/quest
|
||||
|
||||
## Availability
|
||||
|
||||
Chat UI ships on desktop for supported local and remote (paired server) agent sessions. The [mobile companion](/docs/mobile) reuses chat-style transcript patterns for the same paired sessions.
|
||||
Chat UI ships on desktop for supported local and remote (paired server) agent sessions. The available agents and actions depend on the execution host and client capabilities; an older paired host or an unsupported launch can still open in the terminal. The [mobile companion](/docs/mobile) reuses chat-style transcript patterns for paired sessions; the desktop menu steps above describe the desktop app.
|
||||
|
||||
<Callout title="Experimental">
|
||||
Transcript fidelity, streaming, and terminal parity are still under active tuning. Prefer the raw
|
||||
|
||||
@@ -168,6 +168,6 @@ Settings are grouped into panes. Everything here is searchable with `Cmd-,` then
|
||||
- Compact worktree cards — hide redundant second lines in the sidebar while the layout is still experimental.
|
||||
- [Agent hibernation](/docs/agents/hibernation) — pause idle background agents and auto-resume them on reopen.
|
||||
- **Agent Dashboard** — kanban of Needs You / Working / Done agents (optional Idle), with search and project/workspace/PR filters; open in-window or as a pop-out. **Show idle agents** lives on the dashboard board settings control, not here. See [Agents & sessions](/docs/model/agents-sessions#agent-dashboard).
|
||||
- **Chat UI** — optional chat surface on supported agent terminals. See [Chat UI](/docs/agents/native-chat).
|
||||
- **Chat UI** — opens supported new agents in structured chat. Other agents open in the terminal, and existing chats keep their form. See [Chat UI](/docs/agents/native-chat) for continuing conversations in chat or the terminal.
|
||||
- **Cloud VM** — show setup controls and workspace **Run on** targets for repo-owned, on-demand environments (cloud sandboxes, VMs, or local Docker). Setup guide and recipe install live under this experimental toggle. See [Ways to run Orca](/docs/ways-to-run#4-cloud-vms-per-workspace-environments).
|
||||
- Features not yet stable — behavior may change.
|
||||
|
||||
Reference in New Issue
Block a user