# mugen0815/hermes-streamdeck architecture

> Architecture diagram of the GitHub repository mugen0815/hermes-streamdeck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mugen0815/hermes-streamdeck
- Repository: https://github.com/mugen0815/hermes-streamdeck

## Overview

Hermes Streamdeck is a Stream Deck remote control for an existing Hermes API server, not an agent runtime. A key press resolves a configured prompt, starts a run, tracks its live state, and presents the outcome; Stop and Steer keys act on selected runs. The plugin also tests connectivity, manages an optional SSH tunnel, provides a local approval page, and saves run results. The graph combines shown source references with documented workflows; several action, tracker, and UI implementations were not excerpted, so their links rely on README statements rather than inspected calls.

Main entry points: [`src/app.ts`](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/app.ts) (Application coordinator), [`src/hermes/client.ts`](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/client.ts) (Hermes API client), [`src/runs/manager.ts`](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/runs/manager.ts) (Run manager), [`src/actions/start-run.ts`](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/start-run.ts) (Start Run action)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_controls["Stream Deck controls"]
  node_plugin["Plugin registration<br/>[plugin.ts]"]
  node_start["Start Run action<br/>[start-run.ts]"]
  node_stop["Stop Run action<br/>[stop-run.ts]"]
  node_steer["Steer Run action<br/>[steer-run.ts]"]
  node_tunnel_action["Tunnel action<br/>[tunnel.ts]"]
end

subgraph group_coordination["Run coordination"]
  node_app["Application coordinator<br/>[app.ts]"]
  node_manager["Run manager<br/>[manager.ts]"]
  node_tracker["Run tracker<br/>[tracker.ts]"]
  node_state["Run state model<br/>[state.ts]"]
end

subgraph group_hermes["Hermes integration"]
  node_hermes_client["Hermes API client<br/>[client.ts]"]
  node_sse["SSE parser<br/>[sse.ts]"]
  node_errors["API error mapping<br/>[errors.ts]"]
  node_types["API data types<br/>[types.ts]"]
end

subgraph group_support["Connectivity and tunnel"]
  node_connection["Connection monitor<br/>[connection.ts]"]
  node_connection_test["Connection test<br/>[connection-test.ts]"]
  node_tunnel["SSH tunnel controller<br/>[tunnel.ts]"]
end

subgraph group_experience["User interaction and results"]
  node_prompt["Prompt templates<br/>[template.ts]"]
  node_desktop["Desktop interaction<br/>[desktop.ts]"]
  node_key_render["Key status rendering<br/>[render.ts]"]
  node_approval_server["Approval web server<br/>[server.ts]"]
  node_approval_page["Approval page<br/>[page.ts]"]
  node_results[("Run result storage<br/>[store.ts]")]
  node_settings_ui["Property inspector<br/>[ui]"]
end

node_user(("Stream Deck user"))
node_hermes_api{{"Hermes API server"}}
node_ssh_host{{"SSH tunnel host"}}

node_user -->|"presses key"| node_start
node_user -->|"presses key"| node_stop
node_user -->|"sends guidance"| node_steer
node_user -->|"toggles tunnel"| node_tunnel_action
node_plugin -->|"initializes"| node_app
node_plugin -->|"registers"| node_start
node_plugin -->|"registers"| node_stop
node_plugin -->|"registers"| node_steer
node_plugin -->|"registers"| node_tunnel_action
node_start -->|"uses services"| node_app
node_start -->|"resolves template"| node_prompt
node_start -->|"reads input"| node_desktop
node_start -->|"renders status"| node_key_render
node_start -->|"starts run"| node_manager
node_stop -->|"uses services"| node_app
node_stop -->|"requests stop"| node_manager
node_stop -->|"renders status"| node_key_render
node_steer -->|"uses services"| node_app
node_steer -->|"sends guidance"| node_manager
node_steer -->|"resolves text"| node_prompt
node_steer -->|"renders status"| node_key_render
node_tunnel_action -->|"uses services"| node_app
node_tunnel_action -->|"controls tunnel"| node_tunnel
node_app -->|"constructs"| node_manager
node_app -->|"configures"| node_connection
node_app -->|"runs test"| node_connection_test
node_app -->|"monitors changes"| node_tunnel
node_app -->|"constructs"| node_approval_server
node_app -->|"writes results"| node_results
node_app -->|"uses desktop"| node_desktop
node_manager -->|"requests runs"| node_hermes_client
node_manager -->|"creates tracker"| node_tracker
node_manager -->|"checks phases"| node_state
node_tracker -->|"tracks events"| node_hermes_client
node_tracker -->|"updates phases"| node_state
node_connection -->|"checks health"| node_hermes_client
node_connection_test -->|"tests endpoints"| node_hermes_client
node_connection_test -->|"checks tunnel"| node_tunnel
node_tunnel -->|"opens forward"| node_ssh_host
node_hermes_client -->|"calls API"| node_hermes_api
node_hermes_client -->|"parses events"| node_sse
node_hermes_client -->|"maps failures"| node_errors
node_hermes_client -->|"uses contracts"| node_types
node_approval_server -->|"handles choices"| node_manager
node_approval_server -->|"serves page"| node_approval_page
node_user -->|"configures plugin"| node_settings_ui
node_settings_ui -->|"requests test"| node_connection_test
node_app -->|"saves completed run"| node_results

click node_plugin "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/plugin.ts"
click node_start "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/start-run.ts"
click node_stop "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/stop-run.ts"
click node_steer "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/steer-run.ts"
click node_tunnel_action "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/tunnel.ts"
click node_app "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/app.ts"
click node_manager "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/runs/manager.ts"
click node_tracker "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/runs/tracker.ts"
click node_state "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/runs/state.ts"
click node_hermes_client "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/client.ts"
click node_sse "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/sse.ts"
click node_errors "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/errors.ts"
click node_types "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/types.ts"
click node_connection "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/connection.ts"
click node_connection_test "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/connection-test.ts"
click node_tunnel "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/tunnel/tunnel.ts"
click node_prompt "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/prompt/template.ts"
click node_desktop "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/system/desktop.ts"
click node_key_render "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/ui/render.ts"
click node_approval_server "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/approval/server.ts"
click node_approval_page "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/approval/page.ts"
click node_results "https://github.com/mugen0815/hermes-streamdeck/blob/main/src/results/store.ts"
click node_settings_ui "https://github.com/mugen0815/hermes-streamdeck/tree/main/io.github.mugen0815.hermes-streamdeck.sdPlugin/ui"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_start,node_stop,node_steer,node_tunnel_action,node_user toneBlue
class node_app,node_manager,node_tracker,node_state toneAmber
class node_hermes_client,node_sse,node_errors,node_types,node_hermes_api toneMint
class node_connection,node_connection_test,node_tunnel toneRose
class node_prompt,node_desktop,node_key_render,node_approval_server,node_approval_page,node_results,node_settings_ui,node_ssh_host toneIndigo
```

## Components

### Stream Deck controls

- [Plugin registration](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/plugin.ts): `src/plugin.ts`
- [Start Run action](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/start-run.ts): `src/actions/start-run.ts`
- [Stop Run action](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/stop-run.ts): `src/actions/stop-run.ts`
- [Steer Run action](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/steer-run.ts): `src/actions/steer-run.ts`
- [Tunnel action](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/actions/tunnel.ts): `src/actions/tunnel.ts`

### Run coordination

- [Application coordinator](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/app.ts): `src/app.ts`
- [Run manager](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/runs/manager.ts): `src/runs/manager.ts`
- [Run tracker](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/runs/tracker.ts): `src/runs/tracker.ts`
- [Run state model](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/runs/state.ts): `src/runs/state.ts`

### Hermes integration

- [Hermes API client](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/client.ts): `src/hermes/client.ts`
- [SSE parser](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/sse.ts): `src/hermes/sse.ts`
- [API error mapping](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/errors.ts): `src/hermes/errors.ts`
- [API data types](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/hermes/types.ts): `src/hermes/types.ts`

### Connectivity and tunnel

- [Connection monitor](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/connection.ts): `src/connection.ts`
- [Connection test](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/connection-test.ts): `src/connection-test.ts`
- [SSH tunnel controller](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/tunnel/tunnel.ts): `src/tunnel/tunnel.ts`

### User interaction and results

- [Prompt templates](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/prompt/template.ts): `src/prompt/template.ts`
- [Desktop interaction](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/system/desktop.ts): `src/system/desktop.ts`
- [Key status rendering](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/ui/render.ts): `src/ui/render.ts`
- [Approval web server](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/approval/server.ts): `src/approval/server.ts`
- [Approval page](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/approval/page.ts): `src/approval/page.ts`
- [Run result storage](https://github.com/mugen0815/hermes-streamdeck/blob/main/src/results/store.ts): `src/results/store.ts`
- [Property inspector](https://github.com/mugen0815/hermes-streamdeck/tree/main/io.github.mugen0815.hermes-streamdeck.sdPlugin/ui): `io.github.mugen0815.hermes-streamdeck.sdPlugin/ui`

### Other components

- **Stream Deck user**
- **Hermes API server**
- **SSH tunnel host**

## Connections

- Stream Deck user → Start Run action: presses key (evidence: `README.md`)
- Stream Deck user → Stop Run action: presses key (evidence: `README.md`)
- Stream Deck user → Steer Run action: sends guidance (evidence: `README.md`)
- Stream Deck user → Tunnel action: toggles tunnel (evidence: `README.md`)
- Plugin registration → Application coordinator: initializes (evidence: `src/plugin.ts`)
- Plugin registration → Start Run action: registers (evidence: `src/plugin.ts`)
- Plugin registration → Stop Run action: registers (evidence: `src/plugin.ts`)
- Plugin registration → Steer Run action: registers (evidence: `src/plugin.ts`)
- Plugin registration → Tunnel action: registers (evidence: `src/plugin.ts`)
- Start Run action → Application coordinator: uses services (evidence: `src/actions/start-run.ts`)
- Start Run action → Prompt templates: resolves template (evidence: `src/actions/start-run.ts`)
- Start Run action → Desktop interaction: reads input (evidence: `src/actions/start-run.ts`)
- Start Run action → Key status rendering: renders status (evidence: `src/actions/start-run.ts`)
- Start Run action → Run manager: starts run (evidence: `README.md`)
- Stop Run action → Application coordinator: uses services (evidence: `src/actions/stop-run.ts`)
- Stop Run action → Run manager: requests stop (evidence: `README.md`)
- Stop Run action → Key status rendering: renders status (evidence: `src/actions/stop-run.ts`)
- Steer Run action → Application coordinator: uses services (evidence: `src/actions/steer-run.ts`)
- Steer Run action → Run manager: sends guidance (evidence: `README.md`)
- Steer Run action → Prompt templates: resolves text (evidence: `src/actions/steer-run.ts`)
- Steer Run action → Key status rendering: renders status (evidence: `src/actions/steer-run.ts`)
- Tunnel action → Application coordinator: uses services (evidence: `src/actions/tunnel.ts`)
- Tunnel action → SSH tunnel controller: controls tunnel (evidence: `README.md`)
- Application coordinator → Run manager: constructs (evidence: `src/app.ts`)
- Application coordinator → Connection monitor: configures (evidence: `src/app.ts`)
- Application coordinator → Connection test: runs test (evidence: `src/app.ts`)
- Application coordinator → SSH tunnel controller: monitors changes (evidence: `src/app.ts`)
- Application coordinator → Approval web server: constructs (evidence: `src/app.ts`)
- Application coordinator → Run result storage: writes results (evidence: `src/app.ts`)
- Application coordinator → Desktop interaction: uses desktop (evidence: `src/app.ts`)
- Run manager → Hermes API client: requests runs (evidence: `src/runs/manager.ts`)
- Run manager → Run tracker: creates tracker (evidence: `src/runs/manager.ts`)
- Run manager → Run state model: checks phases (evidence: `src/runs/manager.ts`)
- Run tracker → Hermes API client: tracks events (evidence: `src/runs/tracker.ts`)
- Run tracker → Run state model: updates phases (evidence: `src/runs/tracker.ts`)
- Connection monitor → Hermes API client: checks health (evidence: `src/connection.ts`)
- Connection test → Hermes API client: tests endpoints (evidence: `src/connection-test.ts`)
- Connection test → SSH tunnel controller: checks tunnel (evidence: `src/connection-test.ts`)
- SSH tunnel controller → SSH tunnel host: opens forward (evidence: `README.md`)
- Hermes API client → Hermes API server: calls API (evidence: `README.md`)
- Hermes API client → SSE parser: parses events (evidence: `src/hermes/client.ts`)
- Hermes API client → API error mapping: maps failures (evidence: `src/hermes/client.ts`)
- Hermes API client → API data types: uses contracts (evidence: `src/hermes/client.ts`)
- Approval web server → Run manager: handles choices (evidence: `src/approval/server.ts`)
- Approval web server → Approval page: serves page (evidence: `src/approval/server.ts`)
- Stream Deck user → Property inspector: configures plugin (evidence: `README.md`)
- Property inspector → Connection test: requests test (evidence: `README.md`)
- Application coordinator → Run result storage: saves completed run (evidence: `src/app.ts`)
