warp: The cloud-backed terminal for individuals and teams

Warp uses a unified icon system to distinguish between local agents and cloud/ambient (third-party CLI) agents across various UI surfaces (vertical tabs, pane headers, conversation lists, and notifications).

Agent Visual Indicators

• Cloud/Ambient Agents (e.g., Claude Cloud, Gemini Cloud, Oz Cloud):

  • Displayed as a brand-colored circle (e.g., Claude-orange, Gemini brand color, or Oz purple).
  • Includes a cloud lobe icon.
  • The status icon inside the cloud lobe updates dynamically (e.g., spinner during setup, or transitioning to Success/Error/Blocked/Cancelled states).

• Local Agents (e.g., local claude CLI, local Oz):

  • Displayed as a brand-colored circle.
  • Includes a bottom-right status badge.
  • No cloud lobe is present for local sessions.

• Legacy Indicators:

  • Plain terminal, shell, or error indicators remain visually unchanged and do not use the agent icon system.

Warp uses a unified icon system to visually distinguish between local agents (like Oz) and cloud/ambient agents (third-party CLIs like Claude). This distinction is communicated through a 'cloud lobe' visual indicator on the agent's avatar.

Agent Types

• Local Agents: Represented by their standard brand icon (e.g., Oz) without additional cloud indicators. is_ambient is set to false.
• Ambient (Cloud) Agents: Represented by their brand icon (e.g., Claude) with an additional cloud lobe rendering. is_ambient is set to true.

UI Surfaces

The icon system is designed to be consistent across multiple UI components:

• Vertical Tabs: Displays the agent icon and status.
• Pane Headers: Displays the same icon and status as the tabs.
• Conversation/Task Cards: Displays the agent icon and status based on the task's registration.
• Notifications: Shows the agent's avatar (including the cloud lobe for ambient agents) when an event occurs (e.g., a blocked permission request).

Warp provides a consistent 'Agent View' experience (including pane headers, exit affordances, and details panels) when viewing conversations powered by 3rd-party cloud agents like Claude or Gemini.

Previously, opening these conversations via different entry points resulted in inconsistent UX. Now, the system uses a 'vehicle' pattern: it mints a fresh, empty Oz-style AIConversation to act as the UI container and retags the 3rd-party block snapshots and rich content onto this container. This ensures that 3rd-party runs pass the should_hide_block agent view filters and appear within the standard agent UI chrome.

Supported entry points for 3rd-party agents include:

• Live shared-session viewer: Joining via warp://shared_session/{id}, the management view (OpenAmbientAgentSession), or the conversation list (OpenAmbientAgentSession).
• Transcript viewer: Loading via warp://conversation/{id}, the management view, or the conversation list (OpenConversationTranscriptViewer).

In the Warp TUI, hover states only update when a physical MouseMoved event is received. If the layout shifts (e.g., expanding a collapsed section) while the mouse is stationary, elements that were previously under the pointer may incorrectly continue to render in a 'hovered' state.

To resolve this, the TUI implements a synthetic mouse replay mechanism:

1. Position Caching: TuiScreen records the last_mouse_position from every positional event.
2. Replay Loop: After every scene build, TuiScreen::draw performs up to three iterations of:
   • Taking invalidations.
   • Performing layout and paint.
   • Replaying the cached mouse position via replay_mouse_position (dispatching a synthetic MouseMoved event with is_synthetic: true).
3. Loop Termination: The loop breaks once the replay stops triggering new invalidations.
4. Feedback Loop Suppression: To prevent infinite layout $\leftrightarrow$ hover feedback loops, TuiHoverable suppresses two consecutive synthetic hover flips using MouseState::last_event_is_synthetic_hover. A non-move event is required to re-arm this guard.

The Remote Codebase Indexing architecture (APP-3792) distributes responsibilities between the Client, the Daemon, and the Backend to enable efficient AI-driven codebase search on remote hosts.

Responsibilities

Daemon (Remote Host)

• Indexing: Builds the Merkle tree and fragment metadata from the remote filesystem.
• Sync: Performs full and incremental sync with the backend using a StoreClient authenticated by the user's token.
• Cache: Persists a serialized Merkle/snapshot cache locally on the remote host.
• File Access: Reads remote file bytes for chunking and fragment hydration.
• Status: Watches the remote filesystem and pushes status/root-hash updates to the client.

Client (Local UI)

• Orchestration: Decides whether to offer remote indexing based on feature flags and user settings.
• UI: Renders status, settings, and speedbump banners for local vs. remote repos.
• Retrieval: Calls the app server directly using the root_hash provided by the daemon to find search candidates, avoiding unnecessary SSH hops.
• Mapping: Uses the daemon only to map content hashes back to remote fragment metadata.

Backend (Cloud)

• Storage: Stores Merkle-tree/index data and embeddings keyed by hashes.
• Authorization: Verifies that the authenticated caller is authorized to use a specific root_hash for the associated remote repo.
• Search: Executes get_relevant_fragments(root_hash, query, repo_metadata, embedding_config) and performs reranking.
• Configuration: Provides codebase context configuration (embedding config, batch sizes, etc.) to both the client and daemon.

The Vertical Tabs Summary (v2) replaces the single-line title and working-directory rendering with a per-line rendering pattern. Key visual changes include:

• Conversation Status Prefixes: Lines representing conversation panes now feature a status pill (icon with a 10%-opacity colored background) as a prefix.
• Prioritized Sorting: Conversation lines (those with a ConversationStatus) are sorted to the top of the list, ensuring they appear before non-conversation lines within the visible 3-line cap.
• Alignment: To maintain visual consistency, if any visible title line has a status icon, a fixed-width spacer is rendered for lines without a status to ensure text columns align.
• Overflow Handling: Both titles and working directories are capped at 3 visible lines; additional entries are moved to a + N more overflow line.
• Region Order: The summary renders in a strict order: Title region $\rightarrow$ Working Directory region $\rightarrow$ Branch region. Empty regions are omitted.

The Warp TUI uses different transport mechanisms for copying text depending on whether the session is local or remote (SSH).

• Local Sessions: The TUI attempts to write directly to the OS clipboard using the arboard crate. If successful, it provides a confirmed Copied status. If the native write fails, it falls back to using OSC 52 sequences sent via stdout.
• Remote/SSH Sessions: The TUI detects an SSH environment (via SSH_CONNECTION or SSH_TTY) and uses OSC 52 sequences to request the host terminal to handle the clipboard. This is considered a best-effort SentToTerminal operation.

User Feedback:

• Confirmed Copy: When text is successfully written to the native OS clipboard, a confirmation hint is shown (e.g., COPY_SELECTION_HINT).
• Best-Effort Copy: When text is sent via OSC 52 (common in SSH or as a fallback), a different hint is shown (e.g., copied via terminal).
• Failure: If both native and OSC 52 methods fail, a failure hint is displayed.

The OrchestrationEventStreamer manages long-lived Server-Sent Events (SSE) connections to deliver v2 orchestration events (cross-agent messages and lifecycle events) to conversations.

An agent run subscribes to its own run_id to act as its 'inbox'. For an agent to receive messages and lifecycle signals, it must maintain this subscription while active.

Subscription Eligibility Invariant: A conversation is subscribed to SSE events if and only if it meets both of these conditions:

1. has_active_consumer(): At least one consumer (e.g., an AgentViewController in the GUI or an agent_sdk::driver in CLI/cloud workers) is registered for the conversation.
2. Orchestration Role: The conversation is either a child (is_child_agent_conversation()) or a parent (has_at_least_one_watched_child_run_id()).

Solo conversations (those that are neither parents nor children) are excluded from subscriptions as they do not participate in an orchestration tree.