the-nexus/docs/ATLAS-COCKPIT-PATTERNS.md

ATLAS Cockpit — Source Patterns: Adopted, Adapted, and Rejected

Issue: #1695 Date: 2026-04-22

---

Source Repos Audited

Repo	Role in audit
dodo-reach/hermes-desktop	Primary pattern source for inspector/right rail layout
outsourc-e/hermes-workspace	Session taxonomy vocabulary (group/tag/pin/archive)
nesquena/hermes-webui	Session switcher UI patterns; status badge styling

---

Patterns Adopted

1. Inspector / Right Rail (from dodo-reach/hermes-desktop)

What: A collapsible right panel with discrete sections (Files, Artifacts, Status, Terminal). Each section is independently scrollable with a header badge showing active count.

How we adopted it:

• cockpit-inspector.js builds the rail as a fixed position: fixed; right: 0 DOM element
• Collapse/expand is stored in localStorage (key: nexus-inspector-collapsed) — identical pattern to hermes-desktop's sidebar persistence
• Section headers use the same icon + ALL CAPS LABEL + badge visual grammar
• Toggle button sits on the left edge of the rail (pulled out ~22px) — same affordance pattern

What we changed:

• Theming: Nexus uses #4af0c0 / dark-space palette instead of hermes-desktop's purple/grey Electron chrome
• Git state section is added (not present in hermes-desktop)
• Memory/Skills section maps to Nexus's SpatialMemory regions (Nexus-specific)

---

2. Session Taxonomy Vocabulary (from outsourc-e/hermes-workspace)

What: Sessions are first-class objects with group, tag[], pinned, and archived state. Pinned sessions always sort first. Archived sessions are hidden from default lists.

How we adopted it:

• session-manager.js implements the exact four operations: group(), tag(), pin(), archive()
• list() filters archived by default, sorts pinned first, then by updatedAt desc — identical to hermes-workspace's sessionList() sort contract
• Export/import as JSON (hermes-workspace's backup mechanism)

What we changed:

• Persistence is localStorage (not IndexedDB or a backend store) — appropriate for local-first, single-operator Nexus
• Added on()/off() event bus so cockpit-inspector.js can reactively re-render when sessions change
• Session IDs use sess_<timestamp>_<random> prefix rather than UUID v4

---

3. Status Badge Styling (from nesquena/hermes-webui)

What: Section header badges use a small pill with a count; color encodes state (green = ok, amber = warn, red = error).

How we adopted it:

• .ci-section-badge, .badge-warn, .badge-ok classes in style.css follow the same color semantics
• Agent health dots (agent-idle, agent-working, agent-error) map to the same three-color system

What we changed:

• Font is JetBrains Mono (Nexus default) instead of hermes-webui's Inter
• Animations are subtler (pulse only on agent-working, not on all badges)

---

4. xterm.js PTY Terminal (common pattern across all three repos)

All three source repos use xterm.js as the browser terminal component. The transport varies:

• hermes-desktop: IPC bridge to a native Node.js node-pty subprocess
• hermes-workspace: WebSocket to a server-side shell
• hermes-webui: WebSocket to a ttyd-style relay

How we adopted it:

• xterm.js 5.3.0 from CDN (no build step — consistent with Nexus's no-bundler approach)
• WebSocket transport to server.py's pty_handler() on port 8766
• FitAddon for terminal resize (same as all three source repos)

What we changed:

• Transport is Python pty stdlib (not node-pty, not ttyd) — see ADR-001
• PTY runs in server.py's asyncio event loop via run_in_executor (non-blocking reads)

---

Patterns Intentionally Rejected

A. Multi-pane split terminal (hermes-desktop)

hermes-desktop supports splitting the terminal into multiple panes (tmux-style). Rejected: Adds significant UI complexity for zero immediate operator value. The Nexus operator uses native terminal splits in their OS. One PTY pane is sufficient.

B. Session persistence to remote backend (outsourc-e/hermes-workspace)

hermes-workspace stores sessions in a PostgreSQL backend with real-time sync across clients. Rejected: The Nexus is local-first and single-operator. localStorage is sufficient and adds zero infrastructure.

C. File tree browser in the rail (dodo-reach/hermes-desktop)

hermes-desktop has a full VS Code–style file tree in the inspector. Rejected: The Nexus 3D world is not a code editor. Artifacts are surfaced as a flat list of recently-touched files/outputs, not a tree. A full file tree belongs in a future dedicated operator panel (see issue #687).

D. Session thumbnails / previews (nesquena/hermes-webui)

hermes-webui renders a mini-canvas screenshot as a session thumbnail. Rejected: The Nexus Three.js canvas is expensive to snapshot. Thumbnails would require canvas-capture overhead. Deferred to a future issue.

E. Inline skill invocation buttons (nesquena/hermes-webui)

hermes-webui adds quick-action buttons directly on each agent health row. Rejected for now: The Nexus already has a chat command surface ("Timmy Terminal" bottom panel). Duplicating invocation paths would fragment the operator model. The inspector rail is read-focused; actions flow through chat.

---

Summary

Pattern	Source	Status
Inspector right rail layout	hermes-desktop	Adopted
Collapse/expand + localStorage	hermes-desktop	Adopted
Session group/tag/pin/archive	hermes-workspace	Adopted
Session sort (pinned first, then updatedAt)	hermes-workspace	Adopted
Status badge color semantics	hermes-webui	Adopted
xterm.js terminal	all three	Adopted (transport adapted)
Multi-pane terminal	hermes-desktop	Rejected
Remote session backend	hermes-workspace	Rejected
File tree browser	hermes-desktop	Rejected
Session thumbnails	hermes-webui	Rejected
Inline skill invocation	hermes-webui	Rejected