# nousresearch/hermes-labs-plugins architecture

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

- Interactive diagram: https://gitdiagram.com/nousresearch/hermes-labs-plugins
- Repository: https://github.com/nousresearch/hermes-labs-plugins

## Overview

This repository is a collection of experimental Hermes Agent plugins, not one shared runtime. Their user-facing workflows are: Copilot model access through either its API provider or CLI/ACP; a read-only inbox report; owner-approved Telegram Business reply drafts; browser workflow recording; and Yuanbao messaging and tools. The map preserves these distinct products and their main internal layers. Some subsystem behavior is documented in the README but its implementation was not sampled, so those links are documented rather than inferred from unseen code.

Main entry points: [`yuanbao/adapter.py`](https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/adapter.py) (Messaging adapter), [`github-copilot/copilot/__init__.py`](https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/__init__.py) (Copilot API provider), [`telegram-business/manager.py`](https://github.com/nousresearch/hermes-labs-plugins/blob/main/telegram-business/manager.py) (Draft and approval manager), [`workflow-record/cli.py`](https://github.com/nousresearch/hermes-labs-plugins/blob/main/workflow-record/cli.py) (Record command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_copilot["GitHub Copilot"]
  node_copilot_api["Copilot API provider<br/>[__init__.py]"]
  node_copilot_catalog["Model catalog<br/>[catalog.py]"]
  node_copilot_setup["Sign-in and setup<br/>[setup.py]"]
  node_copilot_wire["API request wiring<br/>[wire.py]"]
  node_copilot_activation["GitHub call gate<br/>[activation.py]"]
  node_copilot_acp["ACP provider profile<br/>[__init__.py]"]
  node_copilot_client["ACP CLI client<br/>[client.py]"]
  node_copilot_cli["Copilot CLI"]
end

subgraph group_inbox["Inbox"]
  node_inbox_command["Inbox command<br/>[cli.py]"]
  node_inbox_report["Report assembly<br/>[report.py]"]
  node_inbox_collectors["Read-only collectors<br/>[collectors.py]"]
end

subgraph group_telegram["Telegram Business"]
  node_telegram_manager["Draft and approval manager<br/>[manager.py]"]
  node_telegram_state["Business state<br/>[state.py]"]
end

subgraph group_record["Workflow Record"]
  node_record_command["Record command<br/>[cli.py]"]
  node_record_capture["Capture and normalize<br/>[recording.py]"]
  node_record_cdp["Browser CDP transport<br/>[cdp.py]"]
end

subgraph group_yuanbao["Yuanbao"]
  node_yuanbao_register["Platform registration<br/>[register.py]"]
  node_yuanbao_adapter["Messaging adapter<br/>[adapter.py]"]
  node_yuanbao_protocol["Protocol codec<br/>[yuanbao_proto.py]"]
  node_yuanbao_media["Media handling<br/>[yuanbao_media.py]"]
  node_yuanbao_sticker["Sticker handling<br/>[yuanbao_sticker.py]"]
  node_yuanbao_capacity["Inbound capacity"]
  node_yuanbao_tools["Group and DM tools<br/>[tools.py]"]
end

node_user(("Hermes user"))
node_github["GitHub services"]
node_profile_state[("Hermes profile state")]
node_telegram_owner(("Telegram account owner"))
node_telegram_customer(("Telegram customers"))
node_telegram_api["Telegram platform"]
node_browser["Browser workflow"]
node_yuanbao_gateway["Yuanbao WebSocket"]

node_user -.->|"selects provider"| node_copilot_api
node_copilot_api -->|"checks access"| node_copilot_activation
node_copilot_api -->|"lists models"| node_copilot_catalog
node_copilot_api -->|"configures provider"| node_copilot_setup
node_copilot_api -->|"sends requests"| node_copilot_wire
node_copilot_catalog -->|"fetches catalog"| node_github
node_copilot_setup -->|"performs device login"| node_github
node_user -.->|"selects ACP"| node_copilot_acp
node_copilot_acp -->|"creates client"| node_copilot_client
node_copilot_client -->|"launches over ACP"| node_copilot_cli
node_user -.->|"runs inbox"| node_inbox_command
node_inbox_command -->|"builds report"| node_inbox_report
node_inbox_report -->|"gathers status"| node_inbox_collectors
node_inbox_collectors -.->|"reads profile data"| node_profile_state
node_user -.->|"reviews drafts"| node_telegram_manager
node_telegram_customer -.->|"sends messages"| node_telegram_manager
node_telegram_manager -.->|"uses stored state"| node_telegram_state
node_telegram_manager -.->|"sends approved replies"| node_telegram_api
node_user -.->|"starts recording"| node_record_command
node_record_command -->|"records workflow"| node_record_capture
node_record_command -->|"controls browser"| node_record_cdp
node_record_cdp -->|"observes events"| node_browser
node_record_capture -.->|"injects recorder"| node_browser
node_user -.->|"installs platform"| node_yuanbao_register
node_yuanbao_register -->|"registers adapter"| node_yuanbao_adapter
node_yuanbao_register -->|"registers tools"| node_yuanbao_tools
node_yuanbao_adapter -.->|"connects by WebSocket"| node_yuanbao_gateway
node_yuanbao_adapter -->|"encodes messages"| node_yuanbao_protocol
node_yuanbao_adapter -->|"handles media"| node_yuanbao_media
node_yuanbao_adapter -->|"handles stickers"| node_yuanbao_sticker
node_yuanbao_adapter -->|"checks intake capacity"| node_yuanbao_capacity
node_yuanbao_tools -->|"uses platform adapter"| node_yuanbao_adapter
node_yuanbao_tools -->|"uses sticker handling"| node_yuanbao_sticker

click node_copilot_api "https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/__init__.py"
click node_copilot_catalog "https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/catalog.py"
click node_copilot_setup "https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/setup.py"
click node_copilot_wire "https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/wire.py"
click node_copilot_activation "https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/activation.py"
click node_copilot_acp "https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot_acp/__init__.py"
click node_copilot_client "https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot_acp/client.py"
click node_inbox_command "https://github.com/nousresearch/hermes-labs-plugins/blob/main/inbox/cli.py"
click node_inbox_report "https://github.com/nousresearch/hermes-labs-plugins/blob/main/inbox/report.py"
click node_inbox_collectors "https://github.com/nousresearch/hermes-labs-plugins/blob/main/inbox/collectors.py"
click node_telegram_manager "https://github.com/nousresearch/hermes-labs-plugins/blob/main/telegram-business/manager.py"
click node_telegram_state "https://github.com/nousresearch/hermes-labs-plugins/blob/main/telegram-business/state.py"
click node_record_command "https://github.com/nousresearch/hermes-labs-plugins/blob/main/workflow-record/cli.py"
click node_record_capture "https://github.com/nousresearch/hermes-labs-plugins/blob/main/workflow-record/recording.py"
click node_record_cdp "https://github.com/nousresearch/hermes-labs-plugins/blob/main/workflow-record/cdp.py"
click node_yuanbao_register "https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/register.py"
click node_yuanbao_adapter "https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/adapter.py"
click node_yuanbao_protocol "https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/yuanbao_proto.py"
click node_yuanbao_media "https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/yuanbao_media.py"
click node_yuanbao_sticker "https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/yuanbao_sticker.py"
click node_yuanbao_capacity "https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/inbound_capacity.py"
click node_yuanbao_tools "https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/tools.py"

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_copilot_api,node_copilot_catalog,node_copilot_setup,node_copilot_wire,node_copilot_activation,node_copilot_acp,node_copilot_client,node_copilot_cli,node_user,node_browser toneBlue
class node_inbox_command,node_inbox_report,node_inbox_collectors,node_profile_state toneAmber
class node_telegram_manager,node_telegram_state toneMint
class node_record_command,node_record_capture,node_record_cdp toneRose
class node_yuanbao_register,node_yuanbao_adapter,node_yuanbao_protocol,node_yuanbao_media,node_yuanbao_sticker,node_yuanbao_capacity,node_yuanbao_tools,node_github,node_telegram_owner,node_telegram_customer,node_telegram_api,node_yuanbao_gateway toneIndigo
```

## Components

### GitHub Copilot

- [Copilot API provider](https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/__init__.py): `github-copilot/copilot/__init__.py`
- [Model catalog](https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/catalog.py): `github-copilot/copilot/catalog.py`
- [Sign-in and setup](https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/setup.py): `github-copilot/copilot/setup.py`
- [API request wiring](https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/wire.py): `github-copilot/copilot/wire.py`
- [GitHub call gate](https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot/activation.py): `github-copilot/copilot/activation.py`
- [ACP provider profile](https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot_acp/__init__.py): `github-copilot/copilot_acp/__init__.py`
- [ACP CLI client](https://github.com/nousresearch/hermes-labs-plugins/blob/main/github-copilot/copilot_acp/client.py): `github-copilot/copilot_acp/client.py`
- **Copilot CLI**

### Inbox

- [Inbox command](https://github.com/nousresearch/hermes-labs-plugins/blob/main/inbox/cli.py): `inbox/cli.py`
- [Report assembly](https://github.com/nousresearch/hermes-labs-plugins/blob/main/inbox/report.py): `inbox/report.py`
- [Read-only collectors](https://github.com/nousresearch/hermes-labs-plugins/blob/main/inbox/collectors.py): `inbox/collectors.py`

### Telegram Business

- [Draft and approval manager](https://github.com/nousresearch/hermes-labs-plugins/blob/main/telegram-business/manager.py): `telegram-business/manager.py`
- [Business state](https://github.com/nousresearch/hermes-labs-plugins/blob/main/telegram-business/state.py): `telegram-business/state.py`

### Workflow Record

- [Record command](https://github.com/nousresearch/hermes-labs-plugins/blob/main/workflow-record/cli.py): `workflow-record/cli.py`
- [Capture and normalize](https://github.com/nousresearch/hermes-labs-plugins/blob/main/workflow-record/recording.py): `workflow-record/recording.py`
- [Browser CDP transport](https://github.com/nousresearch/hermes-labs-plugins/blob/main/workflow-record/cdp.py): `workflow-record/cdp.py`

### Yuanbao

- [Platform registration](https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/register.py): `yuanbao/register.py`
- [Messaging adapter](https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/adapter.py): `yuanbao/adapter.py`
- [Protocol codec](https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/yuanbao_proto.py): `yuanbao/yuanbao_proto.py`
- [Media handling](https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/yuanbao_media.py): `yuanbao/yuanbao_media.py`
- [Sticker handling](https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/yuanbao_sticker.py): `yuanbao/yuanbao_sticker.py`
- [Inbound capacity](https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/inbound_capacity.py): `yuanbao/inbound_capacity.py`
- [Group and DM tools](https://github.com/nousresearch/hermes-labs-plugins/blob/main/yuanbao/tools.py): `yuanbao/tools.py`

### Other components

- **Hermes user**
- **GitHub services**
- **Hermes profile state**
- **Telegram account owner**
- **Telegram customers**
- **Telegram platform**
- **Browser workflow**
- **Yuanbao WebSocket**

## Connections

- Hermes user → Copilot API provider: selects provider (evidence: `README.md`)
- Copilot API provider → GitHub call gate: checks access
- Copilot API provider → Model catalog: lists models (evidence: `github-copilot/copilot/__init__.py`)
- Copilot API provider → Sign-in and setup: configures provider (evidence: `github-copilot/copilot/__init__.py`)
- Copilot API provider → API request wiring: sends requests (evidence: `github-copilot/copilot/__init__.py`)
- Model catalog → GitHub services: fetches catalog (evidence: `github-copilot/copilot/catalog.py`)
- Sign-in and setup → GitHub services: performs device login (evidence: `github-copilot/copilot/setup.py`)
- Hermes user → ACP provider profile: selects ACP (evidence: `README.md`)
- ACP provider profile → ACP CLI client: creates client (evidence: `github-copilot/copilot_acp/__init__.py`)
- ACP CLI client → Copilot CLI: launches over ACP (evidence: `github-copilot/copilot_acp/client.py`)
- Hermes user → Inbox command: runs inbox (evidence: `README.md`)
- Inbox command → Report assembly: builds report (evidence: `inbox/cli.py`)
- Report assembly → Read-only collectors: gathers status (evidence: `inbox/report.py`)
- Read-only collectors → Hermes profile state: reads profile data (evidence: `inbox/collectors.py`)
- Hermes user → Draft and approval manager: reviews drafts (evidence: `README.md`)
- Telegram customers → Draft and approval manager: sends messages (evidence: `README.md`)
- Draft and approval manager → Business state: uses stored state
- Draft and approval manager → Telegram platform: sends approved replies (evidence: `README.md`)
- Hermes user → Record command: starts recording (evidence: `README.md`)
- Record command → Capture and normalize: records workflow (evidence: `workflow-record/cli.py`)
- Record command → Browser CDP transport: controls browser (evidence: `workflow-record/cli.py`)
- Browser CDP transport → Browser workflow: observes events (evidence: `workflow-record/cdp.py`)
- Capture and normalize → Browser workflow: injects recorder (evidence: `workflow-record/recording.py`)
- Hermes user → Platform registration: installs platform (evidence: `README.md`)
- Platform registration → Messaging adapter: registers adapter (evidence: `yuanbao/register.py`)
- Platform registration → Group and DM tools: registers tools (evidence: `yuanbao/register.py`)
- Messaging adapter → Yuanbao WebSocket: connects by WebSocket (evidence: `yuanbao/adapter.py`)
- Messaging adapter → Protocol codec: encodes messages (evidence: `yuanbao/adapter.py`)
- Messaging adapter → Media handling: handles media (evidence: `yuanbao/adapter.py`)
- Messaging adapter → Sticker handling: handles stickers (evidence: `yuanbao/adapter.py`)
- Messaging adapter → Inbound capacity: checks intake capacity (evidence: `yuanbao/adapter.py`)
- Group and DM tools → Messaging adapter: uses platform adapter (evidence: `yuanbao/tools.py`)
- Group and DM tools → Sticker handling: uses sticker handling (evidence: `yuanbao/tools.py`)