ouyangbo/hermes-agent
1
0
Fork 0
Code Issues Pull Requests Actions 10 Packages Projects Releases Wiki Activity

docs(desktop): document Linux and Wayland HUD behavior

Browse Source 
Spell out native-compositor drag, the ozone_platform_hint escape hatch
for COSMIC always-on-top, and the snap-to-pointer no-op on Wayland.
This commit is contained in:
Brooklyn Nicholson
2026-08-23 23:34:57 -05:00
committed by brooklyn!
parent d467da9100
commit 4fee6f31a0
1 changed files with 14 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/docs/user-guide/desktop.md
+14 -2
View File
@@ -131,11 +131,23 @@ Talk to Hermes and hear it back, the same [voice mode](./features/voice-mode.md)
**⌘/Ctrl+Shift+H** (or the titlebar button) detaches the chat into a chrome-free, always-on-top floating bar that sits over whatever you are working in. The app window steps aside; the HUD keeps your live conversation and a composer. Where you park it is context — the bar's position tells Hermes which app and screen you're asking about, so "this", "here", and "that page" resolve to what's underneath it.
- **Moving the bar** — **press and hold** anywhere on the composer for a beat, then drag. A quick press still types; a held press grabs the window. This is the only way to move the HUD — there is no titlebar to drag.
- **Moving the bar** — on macOS and Windows, **press and hold** anywhere on the composer for a beat, then drag. A quick press still types; a held press grabs the window. On Linux the composer bar is a native window-manager drag handle (the compositor moves it — the only way that works on Wayland, where an app cannot place its own window).
- **Resizing** — drag the bottom-right corner of the bar.
- **Snap to pointer** — **⌘/Ctrl+Shift+G** (a global hotkey, works from any app) jumps the HUD to wherever your cursor is.
- **Reset layout** — the discard control on the bar restores the default size and (on X11 / macOS / Windows) position. Use this if a persisted size leaves the HUD unusable.
- **Snap to pointer** — **⌘/Ctrl+Shift+G** (a global hotkey, works from any app) jumps the HUD to wherever your cursor is. On native Wayland this is a no-op — the compositor owns placement.
- **Exiting** — click the exit button on the bar, or press **⌘/Ctrl+Shift+H** again. The app window comes back with your session intact.
#### Linux / Wayland
Electron 20+ already runs as a native Wayland client on a Wayland session. Drag, click-through, and resize work on that path. A few compositors (notably COSMIC) ignore `always-on-top` for native Wayland windows. To restore pinning, run the app under XWayland:
```yaml
desktop:
ozone_platform_hint: x11
```
That bridges to `ELECTRON_OZONE_PLATFORM_HINT` at launch (an explicit env var still wins). The trade: X11 cannot restore a window that has ignored the mouse, so the HUD stays a solid window instead of click-through. Some KDE setups also report keyboard breakage with the X11 ozone backend — leave the hint on `auto` unless you need always-on-top.
### Settings & onboarding
Manage providers, models, tools, and credentials from a real UI instead of editing YAML. First-run onboarding gets you to your first message in seconds. The settings panes cover providers/keys, model selection, toolset configuration, MCP servers, the gateway, and session management.