---

name: hermes-chat-bubble description: Install, verify, and troubleshoot the Hermes Chat Bubble dashboard plugin. version: 0.1.0-beta author: Clearmud / Hermes Agent license: MIT metadata: hermes: tags: [hermes, dashboard, plugins, floating-chat, tui] created_by: agent

Hermes Chat Bubble

Use this skill when a user asks to install, test, package, beta-test, or troubleshoot the Hermes Chat Bubble dashboard plugin.

The plugin adds a floating Hermes TUI launcher/bubble to the Hermes Dashboard. It should reuse the dashboard's persistent embedded chat host instead of spawning a second PTY/WebSocket session.

Install target

Install the dashboard payload into the active Hermes home:

$HERMES_HOME/plugins/hermes-chat-bubble/dashboard/
├── manifest.json
└── dist/
    ├── index.js
    └── style.css

For named profiles, $HERMES_HOME is usually:

~/.hermes/profiles/<profile>

Do not assume root ~/.hermes if the dashboard is running under a profile.

Preferred install

From the plugin repo/package:

bash install.sh

Optional profile-specific install:

bash install.sh --profile <profile>

Explicit home:

bash install.sh --hermes-home /path/to/hermes/home

Manual install

PLUGIN_SRC="/path/to/hermes-chat-bubble/dashboard"
HERMES_HOME="/resolved/hermes/home"
PLUGIN_DEST="$HERMES_HOME/plugins/hermes-chat-bubble/dashboard"

mkdir -p "$PLUGIN_DEST"
rm -rf "$PLUGIN_DEST/dist"
cp "$PLUGIN_SRC/manifest.json" "$PLUGIN_DEST/manifest.json"
cp -R "$PLUGIN_SRC/dist" "$PLUGIN_DEST/dist"

Verification

Filesystem:

test -f "$PLUGIN_DEST/manifest.json"
test -f "$PLUGIN_DEST/dist/index.js"
test -f "$PLUGIN_DEST/dist/style.css"
python -m json.tool "$PLUGIN_DEST/manifest.json" >/dev/null
grep -q "HCB_VERSION" "$PLUGIN_DEST/dist/index.js"

Dashboard API, if running at the default URL:

curl -fsS http://127.0.0.1:9119/api/dashboard/plugins/rescan || true
curl -fsS http://127.0.0.1:9119/api/dashboard/plugins | grep hermes-chat-bubble
curl -fsS http://127.0.0.1:9119/dashboard-plugins/hermes-chat-bubble/dist/index.js | grep HCB_VERSION
curl -fsS http://127.0.0.1:9119/dashboard-plugins/hermes-chat-bubble/dist/style.css | grep hermes-chat-bubble

Browser QA:

1. Refresh Hermes Dashboard.
2. Confirm the floating Hermes TUI launcher appears.
3. Open it on a non-/chat tab.
4. Navigate tabs while open.
5. Click Open full chat.
6. Confirm /chat returns to normal full-page layout with no stale fixed bubble styles.
7. Leave /chat, reopen the bubble, and confirm it still uses the same chat surface.

Pitfalls

• Wrong Hermes home/profile is the most common install failure.
• hermes plugins list is not enough; verify /api/dashboard/plugins and served /dashboard-plugins/... assets when possible.
• Do not restart the messaging gateway for dashboard JS/CSS changes.
• If the bubble falls back to /chat, the dashboard probably lacks the persistent chat host (data-chat-active).
• If the full /chat route is stuck as a small bubble, floating inline styles leaked; close/reopen, refresh, and report the exact route sequence.

Agent reporting format

When installing for a user, report:

• Install destination.
• Filesystem verification result.
• Dashboard discovery result.
• Served asset verification result.
• Browser QA status or what remains for the user to check manually.