Hermes Desktop Pane Placement
How the desktop app decides WHERE a plugin pane lands, and how to control it.
Complements hermes-desktop-plugins (the SDK surface) with the layout-engine
internals. Verified against the fork reference 2026-08-13 while placing the
Hermes-Bot-Mode Bots pane.
When to Use
- User asks to put a plugin pane at a specific place ("under New session, above Capabilities").
- A pane adopted into the wrong column/tab and you must explain or fix it.
- Need to know whether a position is even ACHIEVABLE via the plugin API before promising it.
The layout model (what maps where)
sessions pane (placement: 'left', core) IS the whole left column: nav
rail + session list. workspace pane (placement: 'main') is the chat and
its title is 'New session' — don't confuse the title with a nav row.
- A plugin pane with
placement: 'left' joins the SAME group as sessions
→ it becomes a TAB in the left column's tab strip: [sessions] [plugin].
- The nav rail rows (New session / Capabilities / Messaging / Artifacts) are
CORE CHROME inside the sessions pane. Plugin panes CANNOT be placed between
those rows.
SIDEBAR_NAV_AREA rows always render BELOW Artifacts.
The closest achievable "top of left workspace" is a left-column tab ordered
with dock.before — say so honestly instead of promising an inline slot.
Controlling tab order
pos: 'center' joins the group as a tab; add before: '<pane-id>' to insert
before that tab. Bots-style roster first in the left column:
data: {
placement: 'left',
width: '260px',
dock: { pane: 'sessions', pos: 'center', before: 'sessions' }
}
Pitfalls
- Dock hints are ONE-TIME. Adoption runs once per pane lifetime and the
committed layout tree remembers user drags. Editing a hint into an
already-adopted plugin does NOT re-position it — the user must drag the
tab or reset the layout.
- Adoption is silent — it never fronts the zone's active tab, so a new
pane can land in a stack the user doesn't notice.
- Packaged builds have no CDP port (no live DOM). Dev-server runs open
127.0.0.1:9222. On a packaged app, reason from the fork reference source
(~/hermes-agent-fork-reference/apps/desktop/src) instead of DOM inspection.
- Syntax-check before shipping:
node --input-type=module --check < plugin.js
— the app loads the file uncompiled; a parse error surfaces only as a toast.
- Plugin panes are never dismissed anymore: Close on a plugin pane DISABLES
the plugin (contributed-pane dismissal entries are dropped on adoption).
Verification
- After registering a dock hint, confirm tab order on the NEXT adoption (fresh
profile or layout reset) — existing trees keep their committed order.
- Read the pane tree's committed layout in the fork reference tests or reason
from
adoptContributedPanes (see reference) when no CDP is available.
References
references/pane-placement.md — source map: adoption code paths,
insertAtGroup semantics, PaneDockHint, file:line anchors.
1---
2name: hermes-desktop-pane-placement
3description: Place or reorder Hermes desktop plugin panes (tabs, docks).
4version: 1.0.0
5author: Hermes Agent
6license: MIT
7platforms: [linux, macos, windows]
8metadata:
9 source: https://skillmd.com/skills/theheavenlyd3mon/hermes-desktop-pane-placement
10 hermes:
11 tags: [desktop, panes, layout, placement, plugins]
12 category: hermes
13 related_skills: [hermes-desktop-plugins, inspecting-hermes-desktop-dom]
14---
15
16# Hermes Desktop Pane Placement
17
18How the desktop app decides WHERE a plugin pane lands, and how to control it.
19Complements `hermes-desktop-plugins` (the SDK surface) with the layout-engine
20internals. Verified against the fork reference 2026-08-13 while placing the
21Hermes-Bot-Mode Bots pane.
22
23## When to Use
24
25- User asks to put a plugin pane at a specific place ("under New session, above Capabilities").
26- A pane adopted into the wrong column/tab and you must explain or fix it.
27- Need to know whether a position is even ACHIEVABLE via the plugin API before promising it.
28
29## The layout model (what maps where)
30
31- `sessions` pane (`placement: 'left'`, core) IS the whole left column: nav
32 rail + session list. `workspace` pane (`placement: 'main'`) is the chat and
33 its title is `'New session'` — don't confuse the title with a nav row.
34- A plugin pane with `placement: 'left'` joins the SAME group as `sessions`
35 → it becomes a TAB in the left column's tab strip: `[sessions] [plugin]`.
36- The nav rail rows (New session / Capabilities / Messaging / Artifacts) are
37 CORE CHROME inside the sessions pane. Plugin panes CANNOT be placed between
38 those rows. `SIDEBAR_NAV_AREA` rows always render BELOW Artifacts.
39 The closest achievable "top of left workspace" is a left-column tab ordered
40 with `dock.before` — say so honestly instead of promising an inline slot.
41
42## Controlling tab order
43
44`pos: 'center'` joins the group as a tab; add `before: '<pane-id>'` to insert
45before that tab. Bots-style roster first in the left column:
46
47```js
48data: {
49 placement: 'left',
50 width: '260px',
51 dock: { pane: 'sessions', pos: 'center', before: 'sessions' }
52}
53```
54
55## Pitfalls
56
57- **Dock hints are ONE-TIME.** Adoption runs once per pane lifetime and the
58 committed layout tree remembers user drags. Editing a hint into an
59 already-adopted plugin does NOT re-position it — the user must drag the
60 tab or reset the layout.
61- **Adoption is silent** — it never fronts the zone's active tab, so a new
62 pane can land in a stack the user doesn't notice.
63- **Packaged builds have no CDP port** (no live DOM). Dev-server runs open
64 `127.0.0.1:9222`. On a packaged app, reason from the fork reference source
65 (`~/hermes-agent-fork-reference/apps/desktop/src`) instead of DOM inspection.
66- **Syntax-check before shipping:** `node --input-type=module --check < plugin.js`
67 — the app loads the file uncompiled; a parse error surfaces only as a toast.
68- Plugin panes are never dismissed anymore: Close on a plugin pane DISABLES
69 the plugin (contributed-pane dismissal entries are dropped on adoption).
70
71## Verification
72
73- After registering a dock hint, confirm tab order on the NEXT adoption (fresh
74 profile or layout reset) — existing trees keep their committed order.
75- Read the pane tree's committed layout in the fork reference tests or reason
76 from `adoptContributedPanes` (see reference) when no CDP is available.
77
78## References
79
80- `references/pane-placement.md` — source map: adoption code paths,
81 `insertAtGroup` semantics, `PaneDockHint`, file:line anchors.