Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / desktop-application

Desktop application

Hermes Desktop is a native chat client for Hermes Agent. It joins an Electron shell, a React workspace, and one or more Hermes gateways so a user can run agent sessions, complete setup, manage models and preferences, update the app, and use plugin features without a terminal. Packaged builds carry the agent runtime as an immutable payload. Source and development builds use an explicitly selected Hermes checkout. Desktop belongs to the user interfaces area and is separate from the web dashboard and the TUI gateway and RPC surface.

System boundaries

Desktop keeps machine control, user experience, and agent work in separate authorities. The renderer presents live gateway state. It does not own sessions, tools, models, or streamed work.

flowchart LR
    User[User] --> Renderer[React workspace]
    Renderer -->|typed native requests| Electron[Electron shell]
    Renderer -->|REST and WebSocket JSON-RPC| Gateway[Hermes gateway]
    Electron -->|ensures or attaches to| Gateway
    Gateway --> Agent[Sessions, models, tools, and streams]

Electron shell

The Electron shell owns the app process and the local machine. It manages windows, backend connections, local files, terminals, notifications, previews, updates, and process recovery. It exposes named capabilities through the preload bridge instead of general Node.js access. The single-instance owner also controls launch recovery and backend startup. apps/…/main.ts• L736-774, apps/…/preload.ts• L32-134.

Native content follows a trust path. Content-driven windows are denied. External pages open only through a trusted user action. Gateway file saves use the connection and profile that own the file. apps/…/window-open-policy.ts• L1-58, apps/…/main.ts• L11730-11741, apps/…/gateway-file-download.ts• L104-161.

References: apps/…/main.ts• L736-774 apps/…/preload.ts• L32-134 apps/…/window-open-policy.ts• L1-58 apps/…/gateway-file-download.ts• L104-161

React workspace

The React workspace owns navigation, panes, settings, and interaction state. It turns gateway state into chat, lists, previews, terminals, and setup surfaces. The same renderer can run in native Desktop or as a gateway-served Webapp with fewer host capabilities. apps/…/main.tsx• L1-129, apps/…/host-capabilities.ts• L1-84.

References: apps/…/main.tsx• L1-129 apps/…/host-capabilities.ts• L1-84

Gateway service

The gateway owns durable sessions, model calls, tools, configuration, schedules, and stream events. Desktop attaches to the gateway that owns a profile instead of copying agent work into the renderer. A connection identifies a backend source. A profile identifies an agent context on that source, so a profile name alone is not a complete backend identity. apps/…/local-gateway.ts• L61-87, apps/…/connection-config.ts• L827-930, apps/…/client.ts• L592-635.

Local profiles normally share one host gateway and carry profile scope in requests. Isolated or unscopable mutations use a profile-owned backend. URL and Cloud connections share the remote route. SSH and URL configuration can map a Desktop profile label to a different profile name on the backend. apps/…/connection-config.ts• L434-443, apps/…/connection-config.ts• L576-624, apps/…/desktop-profile.ts• L218-283.

References: apps/…/local-gateway.ts• L61-87 apps/…/connection-config.ts• L434-443 apps/…/connection-config.ts• L576-624 apps/…/connection-config.ts• L827-930 apps/…/client.ts• L592-635

Backend lifecycle

Desktop treats backend access as a lifecycle. It selects a connection and profile, proves that the target is usable, binds the renderer to that target, and can reconnect or move the work without rebuilding the whole window.

Connection and profile routing

A request keeps its (connection, profile) owner when it crosses the renderer, Electron, and gateway boundaries. Session, configuration, capability, plugin, messaging, cron, file, and terminal requests use this owner when several sources expose the same profile name. Main owns remembered connection profiles so a new window can restore the right remote route before a renderer exists. apps/…/desktop-profile.ts• L111-126, apps/…/desktop-profile.ts• L218-283, apps/…/client.ts• L592-697.

Profile names that cross into backend process arguments use the shared profile-id grammar. Invalid values do not become new backend directories. Local skin and boot preferences use the same grammar, so display state and backend state name the same profile. apps/…/profile-id-guard.ts• L1-30, apps/…/desktop-boot-preference.ts• L16-30, apps/…/local-skin.ts• L109-121.

References: apps/…/desktop-profile.ts• L111-126 apps/…/desktop-profile.ts• L218-283 apps/…/profile-id-guard.ts• L1-30 apps/…/desktop-boot-preference.ts• L16-30 apps/…/client.ts• L592-697

Primary startup and local ownership

Primary startup first restores a saved route. When no remote is selected, Desktop ensures a usable local gateway owner and attaches to its endpoint. The owner outlives a window, so closing or switching a window disconnects the viewer rather than stopping shared agent work. apps/…/local-gateway.ts• L15-57, apps/…/local-gateway.ts• L220-256, apps/…/main.ts• L4822-4843.

Local dials use short-lived native grants. The grant is tied to the gateway instance, profile, purpose, and requesting window. Stale control data causes one bounded re-discovery; a failed second attempt becomes a real connection error. apps/…/local-gateway.ts• L274-315, apps/…/local-gateway.ts• L332-380, apps/…/local-gateway.ts• L626-683.

References: apps/…/local-gateway.ts• L15-57 apps/…/local-gateway.ts• L220-256 apps/…/local-gateway.ts• L274-315 apps/…/main.ts• L4822-4843

Remote and SSH connections

Remote mode keeps the gateway host as the execution boundary. Agent tools, terminal commands, and file operations run on that host, not on the computer showing the Desktop window. URL and Cloud gateways use token or OAuth authentication. OAuth connections mint a fresh WebSocket ticket and treat a confirmed 401 or 403 as a sign-in problem; network errors remain connection problems. apps/…/connection-config.ts• L13-19, apps/…/connection-config.ts• L250-306, apps/…/connection-config.ts• L109-197.

SSH mode creates a tunnel to a remote Hermes backend. It checks the remote install and platform, uses bounded operations, rejects changed host keys, and reuses or cleans up a dashboard only when Desktop can prove ownership. A remote backend can serve several profiles through one connection. apps/…/remote-lifecycle.ts• L194-379, apps/…/ssh-connection.ts• L839-943, apps/…/ssh-shared-profile-backend.ts• L1-149.

References: apps/…/connection-config.ts• L13-19 apps/…/connection-config.ts• L109-197 apps/…/connection-config.ts• L250-306 apps/…/remote-lifecycle.ts• L194-379 apps/…/ssh-connection.ts• L839-943 apps/…/ssh-shared-profile-backend.ts• L1-149

Reconnection and rehoming

Boot and reconnect use bounded waits and backoff. A sleep, network change, restart, or stale endpoint can rebuild the socket and reattach live sessions. A connection or profile switch is a soft re-home: the shell stays open while gateway-bound state is cleared and the new route becomes authoritative. Running jobs keep their owner route and may continue to emit events in the background. apps/…/use-gateway-boot.ts• L208-255, apps/…/use-gateway-boot.ts• L432-637, apps/…/README.md• L212-218.

Cross-profile reads use bounded aggregation. A slow or offline source becomes a named error beside healthy rows instead of blocking the whole sidebar or looking like an empty list. apps/…/global-remote-session-route.ts• L31-101, apps/…/profile-session-routing.ts• L1091-1180.

References: apps/…/use-gateway-boot.ts• L208-255 apps/…/use-gateway-boot.ts• L432-637 apps/…/README.md• L212-218 apps/…/global-remote-session-route.ts• L31-101 apps/…/profile-session-routing.ts• L1091-1180

Bundled runtime payload

Bundled builds run the agent from the payload named by the build stamp. Electron does not search PATH, select another Python, or repair a missing payload at runtime. A missing or damaged bundled runtime is an install failure and directs the user to reinstall Desktop. apps/…/payload-backend.ts• L14-48, apps/…/main.ts• L4824-4843, apps/…/main.ts• L5055-5065.

Linux AppImages need a stable payload path because their mount disappears on exit. The first launch copies the payload to a per-build data directory, verifies the copy, and reuses it on later launches. Cleanup keeps copies used by a live Desktop or gateway service. apps/…/appimage-payload.ts• L1-5, apps/…/appimage-payload.ts• L117-139, apps/…/appimage-payload.ts• L430-495, apps/…/cli-provision.ts• L59-138.

References: apps/…/payload-backend.ts• L14-48 apps/…/payload-backend.ts• L78-109 apps/…/appimage-payload.ts• L117-139 apps/…/appimage-payload.ts• L430-495 apps/…/cli-provision.ts• L59-138

Update handoff

Desktop updates the client and its connected backend as separate targets. It waits for a safe boundary, hands work to the owner of the installation or source, and reports the result after the new process or package is ready.

Update ownership

Packaged clients use platform owners: Windows sideload builds use App Installer, Store builds use Microsoft Store, and macOS builds use electron-updater. Linux has no published update feed. Source installs use their checkout update path. Remote and SSH backends update at their own source, while Cloud owns updates for its agent instances. apps/…/BUILDING.md• L3-21, apps/…/BUILDING.md• L315-328, apps/…/system.ts• L148-171.

The payload and package are checked as one release unit during packaging. The pack step proves that the payload arrived without missing files, extra files, changed sizes, or changed link targets before platform relocation and signing. apps/…/packaged-payload.mjs• L37-73, apps/…/after-pack.mjs• L63-84.

References: apps/…/BUILDING.md• L3-21 apps/…/BUILDING.md• L315-328 apps/…/packaged-payload.mjs• L37-73 apps/…/after-pack.mjs• L63-84

Relaunch and result reporting

Before an update, Desktop waits for active backend work to reach a safe boundary. It starts the responsible updater and may exit while the handoff continues. A detached relaunch helper is used when the platform must replace the running package. On Linux AppImage relaunch, the helper starts the image without the old mount paths or inherited high file descriptors. apps/…/app-relaunch.ts• L27-107, apps/…/relaunch-target.ts• L65-79, apps/…/relaunch-target.ts• L137-172.

A run marker and correlation id let the next boot match one result to one update attempt. The handoff is successful only when the updater claims the run. If the claim fails, Desktop keeps running or restores its backend and shows a recoverable error. apps/…/checkout-handoff.test.ts• L150-204, apps/…/checkout-handoff.test.ts• L346-367, apps/…/checkout-handoff.test.ts• L369-433.

References: apps/…/app-relaunch.ts• L27-107 apps/…/relaunch-target.ts• L65-79 apps/…/relaunch-target.ts• L137-172 apps/…/checkout-handoff.test.ts• L150-204 apps/…/checkout-handoff.test.ts• L346-367

Local API integration

Desktop uses gateway APIs for agent work and the native or browser bridge for host capabilities. REST carries durable data and settings. WebSocket JSON-RPC carries interactive turns, prompts, approvals, and live events.

Gateway transport

The transport preserves connection and profile ownership across local, remote, Cloud, multiplexed, and pooled backends. Local WebSockets use one-use native grants. Remote WebSockets use tokens or single-use OAuth tickets. Renderer paths stay relative to the selected HTTP origin. apps/…/client.ts• L14-35, apps/…/backend-api-url.ts• L11-49, apps/…/connection-config.ts• L93-106.

The session contract covers creation, prompts, approvals, edits, branches, compression, workspace changes, and model changes. Session reads and writes retain the owner route. Older gateways have narrow fallbacks for missing endpoints. apps/…/sessions.ts• L115-176, apps/…/sessions.ts• L244-435.

Gateway file saves keep the backend owner with the request. Electron streams a result to a temporary file and moves it to the chosen destination only after the transfer succeeds. apps/…/gateway-file-download.ts• L104-183, apps/…/main.ts• L7373-7442.

References: apps/…/client.ts• L14-35 apps/…/backend-api-url.ts• L11-49 apps/…/connection-config.ts• L93-106 apps/…/sessions.ts• L115-176 apps/…/sessions.ts• L244-435 apps/…/gateway-file-download.ts• L104-183

Browser-hosted transport

The renderer can run from a gateway-served Webapp without Electron. It keeps API and socket traffic on the serving origin and uses browser-safe equivalents for files, uploads, windows, terminal access, plugins, preferences, and notifications. Its startup profile is scoped to the serving page and follows profile rename or deletion. Native process, filesystem, update, and window powers are not recreated in the page. apps/…/browser-desktop-bridge.ts• L25-159, apps/…/browser-startup-profile.ts• L8-75, apps/…/host-capabilities.ts• L19-80.

References: apps/…/browser-desktop-bridge.ts• L25-159 apps/…/browser-startup-profile.ts• L8-75 apps/…/host-capabilities.ts• L19-80

Native capability bridge

The preload bridge exposes named capabilities for windows, files, clipboard, notifications, updates, Quick Entry, HUD, previews, screenshots, and helper overlays. Auxiliary windows use the same session and owner scope as the main window. Device preferences stay local, while gateway configuration stays backend state. apps/…/preload.ts• L32-420, apps/…/ui-preferences.ts• L1-16.

Native file and plugin doors resolve paths in Electron. A remote gateway's reported home belongs to another machine and cannot select this machine's Desktop plugin root or local file door. apps/…/fs-ipc.ts• L120-166.

References: apps/…/preload.ts• L32-420 apps/…/ui-preferences.ts• L1-16 apps/…/fs-ipc.ts• L120-166

Chat and onboarding surfaces

The main workspace turns gateway sessions into live chat. It combines durable transcript state with streaming text, tool activity, approvals, attachments, voice, queues, previews, scheduled work, and focused helper windows. First-run setup uses the same session model, so setup is a guided conversation rather than a separate agent path.

Chat workspace

The chat view connects a selected durable session to a live runtime and renders assistant text, reasoning, tools, subagents, usage, prompts, notices, and errors. Session ownership remains separate from the visible route, so a profile switch or reconnect can preserve the correct backend target. apps/…/index.tsx• L94-126, apps/…/wiring.tsx• L418-522.

The composer is shared by the main chat, session tiles, Quick Entry, HUD, and onboarding. It accepts text, files, links, voice input, directives, context references, and answers to blocking prompts. While a turn runs, the user can send, queue, steer, stop, or answer. Its scope keeps attachments, focus, awaiting-input state, and owner profile separate for each visible composer. apps/…/index.tsx• L134-233, apps/…/index.tsx• L972-1055, apps/…/scope.tsx• L11-80.

The model pill and model catalog are the same selection surface across the composer and other Desktop model pickers. They show the model served by the current session surface, gate speed labels by the model's capabilities, and keep manual new-chat choices visibly pinned. apps/…/model-pill.tsx• L39-80, apps/…/model-catalog-menu.tsx• L239-289, apps/…/model-status-label.ts• L222-274.

References: apps/…/index.tsx• L94-126 apps/…/wiring.tsx• L418-522 apps/…/index.tsx• L134-233 apps/…/index.tsx• L972-1055 apps/…/scope.tsx• L11-80 apps/…/model-pill.tsx• L39-80 apps/…/model-catalog-menu.tsx• L239-289

Stream reconciliation

The stream layer joins WebSocket events with stored history. It keeps tool and reasoning parts with the turn that owns them, preserves late tool events on their original assistant bubble, and avoids duplicate output after reconnect or interim commentary. apps/…/index.ts• L165-251.

Turn completion has two related signals: message.complete and the later session.info report with running=false. Desktop tracks reports owed by completed turns so a late report cannot settle a newer turn. If the completion frame is missing, a confirmed end report can still release the composer and hydrate the stored transcript. apps/…/turn-end-report.ts• L1-65, apps/…/message-stream.ts• L402-501, apps/…/session-info.ts• L319-511.

References: apps/…/index.ts• L165-251 apps/…/turn-end-report.ts• L1-65 apps/…/message-stream.ts• L402-501 apps/…/session-info.ts• L319-511

Transcript windows and session lists

Long transcripts use a bounded render window and fetch older durable pages only when the user asks. Session lists group recents, projects, profiles, pinned chats, messaging rows, and search results while retaining the row's profile and connection owner. Large flat lists use virtualization. Search rows keep the backend title and archived state, so a matched message does not become the session name and its menu uses the correct archive verb. apps/…/transcript-window.ts• L20-185, apps/…/transcript-backfill.ts• L79-213, apps/…/sessions-section.tsx• L273-311, apps/…/virtual-session-list.tsx• L92-193, apps/…/search-result-to-session.test.ts• L1-85.

Session tiles persist across restarts and resume only after their owner gateway is open. A pane can leave the visible layout while its live state remains active. apps/…/pane-mirror.ts• L1-211, apps/…/session-tile.tsx• L168-257.

References: apps/…/transcript-window.ts• L20-185 apps/…/transcript-backfill.ts• L79-213 apps/…/sessions-section.tsx• L273-311 apps/…/virtual-session-list.tsx• L92-193 apps/…/search-result-to-session.test.ts• L1-85

First-run setup

First-run setup is a backend-owned run shown inside Desktop chat. Desktop starts or resumes the run in the selected default context, opens its session, and follows completion, skip, and reconnect state. Provider setup supports browser sign-in, device codes, API keys, custom endpoints, model confirmation, and recovery to another provider. apps/…/onboarding-run.ts• L125-198, apps/…/index.tsx• L1-180, apps/…/flow.tsx• L46-155.

flowchart TD
    State[Read backend setup state] -->|setup due| Start[Start or resume setup run]
    Start --> Open[Open setup session]
    Open --> Guide[Show sign-in and model steps]
    Guide -->|complete| Done[Backend ends the run]
    Guide -->|skip| Skip[End setup]
    Done --> Restore[Restore normal workspace]
    Skip --> Restore

References: apps/…/onboarding-run.ts• L125-198 apps/…/index.tsx• L1-180 apps/…/flow.tsx• L46-155

Preview, terminal, and auxiliary surfaces

The preview surface shows local files, generated artifacts, and live web pages beside chat. Native Desktop uses an isolated guest surface. Embedded content receives no app credentials and cannot open an OS page by itself. apps/…/preview-pane.tsx• L124-133, apps/…/inline-preview-directive.tsx• L13-51, apps/…/window-open-policy.ts• L1-58.

The terminal is a persistent PTY surface rather than a disposable view. Hidden tabs keep their shell, scrollback, current directory, and agent reader. The active terminal owns global selection shortcuts and can add selected shell or preview text to the chat composer. apps/…/use-terminal-session.ts• L50-64, apps/…/use-terminal-session.ts• L164-195, apps/…/use-terminal-session.ts• L554-588, apps/…/pty-output.ts• L1-11.

Focused chat surfaces can open in separate native windows. Electron owns their lifetime. The renderer keeps their session, profile, and connection scope aligned with the main chat. apps/…/preload.ts• L104-194, apps/…/controller.tsx• L100-126.

References: apps/…/preview-pane.tsx• L124-133 apps/…/inline-preview-directive.tsx• L13-51 apps/…/use-terminal-session.ts• L50-64 apps/…/use-terminal-session.ts• L554-588 apps/…/preload.ts• L104-194

Settings and preferences

Settings separate gateway-owned agent behavior from device-local Desktop behavior. A settings page can target a selected connection and profile. Appearance, window, shortcut, notification, privacy, and update choices belong to this installation or window.

Gateway connections

The Connections surface manages named local, URL, Cloud, and SSH sources. It supports source tests, sign-in state, primary and launch choices, removal, profile overrides, and update actions. A remote connection test exercises the authenticated HTTP and WebSocket legs that the app will use. apps/…/connections-registry.tsx• L118-196, apps/…/connections-registry.tsx• L332-555, apps/…/main.ts• L15089-15104.

References: apps/…/connections-registry.tsx• L118-196 apps/…/connections-registry.tsx• L332-555 apps/…/main.ts• L15089-15104

Profile-scoped configuration

Configuration pages read and write the gateway schema for the selected target. Desktop keeps local drafts and caches separate by connection and profile. The scope covers models, delegation, tools, connectors, MCP, web access, billing, memory, and voice. A model picked in a live chat affects that session or its next turn; Settings changes the profile default for new sessions. apps/…/config-settings.tsx• L70-289, apps/…/use-model-controls.ts• L100-131, apps/…/use-model-controls.ts• L238-256.

References: apps/…/config-settings.tsx• L70-289 apps/…/use-model-controls.ts• L100-131 apps/…/use-model-controls.ts• L238-256

Device preferences and maintenance

Device-local settings control theme, layout, text scale, keep-awake, notifications, shortcuts, clipboard behavior, and local Webapp access. They do not become gateway agent state. The Command Center exposes maintenance actions such as doctor, security audit, backup, memory status, and debug share. apps/…/ui-preferences.ts• L1-16, apps/…/context.tsx• L41-146, apps/…/maintenance.tsx• L52-170.

References: apps/…/ui-preferences.ts• L1-16 apps/…/context.tsx• L41-146 apps/…/maintenance.tsx• L52-170

Backup and agent transfer

Backup creates an archive for a selected gateway. Transfer moves a local agent into a Hermes Cloud agent while preserving the Cloud host's sign-in, model, and Cloud services. The target creates an undo archive before restore, so a failed or partial restore has a recovery point. apps/…/backup-settings.tsx• L63-243, apps/…/agent-transfer.ts• L249-430.

flowchart LR
    Source[Selected local agent] --> Backup[Create source backup]
    Backup --> Upload[Stream archive to Cloud agent]
    Upload --> Restore[Restore while keeping Cloud host settings]
    Restore --> Ready[Open transferred agent]
    Restore --> Undo[Offer undo from target backup]

References: apps/…/backup-settings.tsx• L63-243 apps/…/agent-transfer.ts• L249-430

Session retention

The Sessions settings surface restores archived conversations, permanently deletes them, and controls optional automatic archiving. The retention rule remains gateway-owned, so Desktop and other Hermes surfaces use the same policy. apps/…/sessions-settings.tsx• L53-144, apps/…/sessions-settings.tsx• L224-229.

References: apps/…/sessions-settings.tsx• L53-144 apps/…/sessions-settings.tsx• L224-229

Plugin-facing UI

Desktop lets agent and Desktop plugins add focused product surfaces without taking ownership of the app shell. The host owns navigation, scope, native actions, settings placement, package review, and cleanup. Plugins contribute features inside those boundaries.

Capability catalog and package management

The Capabilities page brings Skills, Plugins, Connectors, and Toolsets into one connection- and profile-aware surface. Users can inspect a package source, choose its target, install or enable it, update it, reveal local files, and remove the part that applies to the current machine or backend. Remote agent backends cannot materialize a Desktop half on this machine. apps/…/index.tsx• L32-101, apps/…/plugins-tab.tsx• L96-131, apps/…/plugins-tab.tsx• L447-520.

The public catalog uses published snapshots rather than per-entry requests. Desktop validates catalog links, merges installed and available entries, and prefetches a catalog only while the browser is idle. A failed catalog stays available for an explicit retry instead of causing repeated background work. apps/…/catalog-data.ts• L54-75, apps/…/catalog-data.ts• L211-301, apps/…/catalog-data.ts• L304-330.

References: apps/…/index.tsx• L32-101 apps/…/plugins-tab.tsx• L96-131 apps/…/catalog-data.ts• L54-75 apps/…/catalog-data.ts• L211-330

Contribution registry

The contribution registry places plugin panes, routes, sidebar items, commands, settings pages, titlebar items, status items, context-menu rows, completion sources, and composer slots into host-owned areas. Runtime plugins can load, reload, enable, and disable without taking down the shell. The host tracks plugin-owned listeners and other cleanup work. apps/…/registry.ts• L5-27, apps/…/runtime-loader.ts• L364-382, apps/…/runtime-loader.ts• L463-524.

The plugin context is a trust boundary, not a security sandbox. It provides scoped gateway access, storage, translations, notifications, links, dialogs, clipboard, and app actions. The SDK exposes those doors as one authoring surface and gives plugins read-only views of focused session state. apps/…/plugin.ts• L111-179, apps/…/index.ts• L1-19, apps/…/index.ts• L161-223.

References: apps/…/registry.ts• L5-27 apps/…/runtime-loader.ts• L364-382 apps/…/runtime-loader.ts• L463-524 apps/…/plugin.ts• L111-179 apps/…/index.ts• L1-19

Plugin settings and session controls

Settings exposes plugin pages through the same profile selector used by gateway configuration. Agent plugins with a schema receive a generated form whose draft and write remain bound to one profile. Plugin session controls use the host's pin, order, and color stores and resolve a durable or live id to the loaded session row before writing. apps/…/plugin-settings.tsx• L90-207, apps/…/plugin-settings.tsx• L336-445, apps/…/sessions.ts• L11-80.

References: apps/…/plugin-settings.tsx• L90-207 apps/…/plugin-settings.tsx• L336-445 apps/…/sessions.ts• L11-80

Hermes Bots surfaces

The Hermes Bots plugin presents one row per agent profile and opens that bot's canonical Bot Chat. It adds a Bots pane, profile editing, routines, group chats, cross-connection mentions, screen access, and bot-to-bot relay. Bot Chats stay hidden from the normal Sessions list so the roster row remains the one door to the continuous conversation. apps/…/plugin.tsx• L1-16, apps/…/plugin.tsx• L433-490.

Above a Bot Chat composer, the plugin can show unsettled teammate deliveries. The strip reads delivery receipts, reports queued, working, waiting, failed, or unknown outcomes, opens the target bot's own chat, and never resends an uncertain delivery. This keeps the UI honest when a gateway or connection fails between send and receipt. apps/…/teammate-waits.tsx• L1-11, apps/…/teammate-waits.tsx• L118-131, apps/…/teammate-waits.tsx• L212-258, apps/…/plugin.tsx• L439-443.

References: apps/…/plugin.tsx• L1-16 apps/…/plugin.tsx• L433-490 apps/…/teammate-waits.tsx• L1-11 apps/…/teammate-waits.tsx• L118-131 apps/…/teammate-waits.tsx• L212-258

Change checklist

When these files or sections are changed, remember to consider these:

  • Backend route changes must preserve the full (connection, profile) owner through session, settings, plugin, messaging, cron, file, terminal, preview, audio, and background requests.
  • Local shared-host changes must keep profile query scope aligned with the route table. Mutations that the server cannot scope must not fall through to the primary profile.
  • Profile-id changes must update the shared grammar used by Desktop routes, boot preferences, local skins, remote mappings, plugin-created profiles, and backend argv.
  • Local gateway changes must keep endpoint validation, one-use grants, stale-owner recovery, and profile-specific ticket minting aligned.
  • Remote connection changes must keep URL normalization, OAuth ticket refresh, access-proxy header filtering, SSH profile mapping, and connection preflight consistent.
  • Payload changes must keep the build stamp, prepared payload, packaged payload, relocation step, runtime paths, AppImage stable copy, CLI links, and update strategy consistent.
  • Update changes must preserve platform ownership, backend drain order, detached relaunch behavior, handoff claim, correlation, and recovery when the updater does not start.
  • API bridge changes must update the Electron handler, preload bridge, renderer type, browser equivalent where needed, and every auxiliary window that uses the capability.
  • Composer changes must keep per-surface owner scope, IME input, queue state, blocking prompts, voice interruption, model capability labels, and explicit stop behavior aligned.
  • Stream changes must preserve message identity, late turn-end report ownership, runtime rebind rules, missing-completion recovery, and transcript hydration scope.
  • Sidebar changes must preserve profile and connection provenance, archived-row verbs, search titles, pinned rows, project grouping, and virtualized row identity.
  • Plugin changes must keep contribution cleanup, scoped gateway requests, reviewed catalog sources, profile-bound settings, canonical Bot Chat identity, and no-resend teammate reporting aligned.

Important failure modes

TriggerConsequenceGuard
A request carries only a profile nameWork can go to an equal profile on another gatewayCarry the owning connection and profile at the request boundary
An invalid profile value reaches --profileDesktop can create or target a phantom backend directoryValidate through the shared profile-id grammar
A stale local gateway descriptor is reusedReconnect loops against a dead owner or returns repeated ticket errorsForget the descriptor once and re-run the canonical ensure
OAuth ticket minting treats a network error as sign-outA temporary outage forces needless reauthenticationRetry transient transport failures but fail immediately on confirmed 401 or 403
A remote header reaches a different origin or overrides transport headersCredentials can leak or the request can be malformedMatch the gateway origin and reject protected header names
A bundled payload is missing or alteredDesktop can run an unintended runtime or ship a broken packageUse the stamped payload only and compare the prepared and packaged trees
An AppImage runs its payload only from the mountThe gateway, CLI links, or update flow break after the app exitsCopy and verify one stable payload directory per build
A late running=false report settles the next turnThe newer turn stops early or loses its prompt stateTrack one owed end report per completed turn
A missing completion frame leaves the session busyThe composer queues every later input and never sends itUse an authoritative end report to settle and hydrate the affected session
A model pill reads primary global state in a tileA tile shows or sends the wrong model choiceRead the tile's SessionView and owner-scoped model options
A search hit drops its archived flag or titleThe row shows message text and offers the wrong archive actionMap backend title and archive state onto the synthesized row
A plugin teammate delivery has an unknown result and is resentAn agent may act twiceShow the unknown outcome and require the user to open the target chat
An update child starts without claiming the handoffDesktop exits into an update that did not beginRequire the claim and keep the app alive on claim failure

Key files

FileWhy to read it
apps/…/main.tsElectron composition root for startup, connections, windows, backend lifecycle, native actions, and updates.
apps/…/local-gateway.tsLocal gateway ensure, endpoint validation, profile routing, one-use grants, and stale-owner recovery.
apps/…/connection-config.tsRemote, Cloud, SSH, OAuth, header, and shared-host routing rules.
apps/…/desktop-profile.tsRemembered connection/profile routes and missing-profile cleanup.
apps/…/payload-backend.tsThe stamped bundled-runtime contract consumed by Electron.
apps/…/appimage-payload.tsStable AppImage payload copies and cleanup ownership.
apps/…/relaunch-target.tsSafe detached relaunch targets and mount-free environments.
apps/…/after-pack.mjsPackaged payload checks, relocation, and platform post-pack work.
apps/…/packaged-payload.mjsExact prepared-to-packaged payload comparison.
apps/…/BUILDING.mdArtifact variants, update owners, payload contract, and native release boundaries.
apps/…/wiring.tsxThe renderer controller that joins gateway boot, session lists, chat, composer, terminal, and overlays.
apps/…/index.tsxShared send, queue, steer, stop, voice, attachment, and onboarding composer behavior.
apps/…/scope.tsxPer-composer session, owner, attachment, and focus scope.
apps/…/model-catalog-menu.tsxShared model selection, capability, speed, pricing, favorite, and custom-model surface.
apps/…/sessions-section.tsxSession grouping, project views, archive verbs, ordering, and row ownership.
apps/…/virtual-session-list.tsxVirtualized rendering and stable profile/session row identity.
apps/…/index.tsStream assembly and event-to-session-state reconciliation.
apps/…/turn-end-report.tsLate end-of-turn report ownership.
apps/…/session-info.tsRuntime rebind, turn settle, workspace ownership, and recovery behavior.
apps/…/use-terminal-session.tsPersistent PTY, scrollback, resize, selection, theme, and agent-reader behavior.
apps/…/flow.tsxProvider sign-in, model confirmation, and setup recovery surfaces.
apps/…/catalog-data.tsPublic catalog parsing, link policy, caching, and idle prefetch.
apps/…/registry.tsHost contribution areas and plugin lifecycle cleanup.
apps/…/index.tsPlugin SDK state views, actions, owner routing, and session doors.
apps/…/plugin.tsxBot roster, canonical chats, panes, mentions, relay, and plugin wiring.
apps/…/teammate-waits.tsxRead-only teammate delivery status above canonical Bot Chats.