# nousresearch/hermes-paperclip-adapter architecture

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

- Interactive diagram: https://gitdiagram.com/nousresearch/hermes-paperclip-adapter
- Repository: https://github.com/nousresearch/hermes-paperclip-adapter

## Overview

This repository is a Paperclip adapter that runs Hermes Agent as a managed employee. Paperclip supplies agent configuration and heartbeat work; the adapter builds execution inputs, resolves a model provider, launches Hermes in single-query mode, and returns run results for Paperclip. Separate capabilities expose skill snapshots and configuration/model detection, while UI parsing turns Hermes output into transcript entries. Shared constants support several layers. The README documents the broader run behavior; the shown excerpts do not expose every execution detail, so only documented or source-visible relationships are drawn.

Main entry points: [`src/server/execute.ts`](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/execute.ts) (Run executor), [`src/shared/constants.ts`](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/shared/constants.ts) (Shared constants), [`src/server/skills.ts`](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/skills.ts) (Skill APIs), [`src/ui/parse-stdout.ts`](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/ui/parse-stdout.ts) (Transcript parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_ui_config["Agent config form<br/>[build-config.ts]"]
  node_config_builder["Config builder<br/>[build-config.ts]"]
  node_model_detection["Model detection<br/>[detect-model.ts]"]
  node_adapter_metadata["Adapter metadata<br/>[index.ts]"]
  node_shared_constants["Shared constants<br/>[constants.ts]"]
end

subgraph group_execution["Execution"]
  node_executor["Run executor<br/>[execute.ts]"]
  node_hermes["Hermes CLI agent"]
  node_session_codec["Session codec<br/>[index.ts]"]
end

subgraph group_skills["Skills"]
  node_skill_api["Skill APIs<br/>[skills.ts]"]
  node_paperclip_skills["Paperclip skills"]
  node_hermes_skills["Hermes skill files"]
end

subgraph group_presentation["Presentation"]
  node_transcript_parser["Transcript parser<br/>[parse-stdout.ts]"]
  node_cli_formatter["CLI event formatter<br/>[format-event.ts]"]
end

node_paperclip(("Paperclip"))

node_paperclip -->|"configures"| node_ui_config
node_ui_config -->|"provides values"| node_config_builder
node_paperclip -->|"invokes heartbeat"| node_executor
node_executor -->|"spawns CLI"| node_hermes
node_executor -->|"detects model"| node_model_detection
node_model_detection -->|"uses provider rules"| node_shared_constants
node_executor -->|"uses defaults"| node_shared_constants
node_executor -->|"reports run results"| node_paperclip
node_hermes -->|"emits parsed output"| node_transcript_parser
node_paperclip -->|"renders transcript"| node_transcript_parser
node_executor -->|"persists session state"| node_session_codec
node_paperclip -->|"validates session state"| node_session_codec
node_paperclip -->|"requests skill snapshot"| node_skill_api
node_skill_api -->|"reads managed skills"| node_paperclip_skills
node_skill_api -->|"scans skill files"| node_hermes_skills
node_skill_api -->|"returns snapshot"| node_paperclip
node_hermes -.->|"streams events"| node_cli_formatter
node_adapter_metadata -->|"uses adapter identity"| node_shared_constants
node_config_builder -->|"uses defaults"| node_shared_constants
node_transcript_parser -->|"uses output markers"| node_shared_constants

click node_ui_config "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/ui/build-config.ts"
click node_config_builder "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/ui/build-config.ts"
click node_model_detection "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/detect-model.ts"
click node_adapter_metadata "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/index.ts"
click node_shared_constants "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/shared/constants.ts"
click node_executor "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/execute.ts"
click node_session_codec "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/index.ts"
click node_transcript_parser "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/ui/parse-stdout.ts"
click node_cli_formatter "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/cli/format-event.ts"
click node_skill_api "https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/skills.ts"

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_ui_config,node_config_builder,node_model_detection,node_adapter_metadata,node_shared_constants toneBlue
class node_executor,node_hermes,node_session_codec toneAmber
class node_skill_api,node_paperclip_skills,node_hermes_skills toneMint
class node_transcript_parser,node_cli_formatter toneRose
class node_paperclip toneIndigo
```

## Components

### Configuration

- [Agent config form](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/ui/build-config.ts): `src/ui/build-config.ts`
- [Config builder](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/ui/build-config.ts): `src/ui/build-config.ts`
- [Model detection](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/detect-model.ts): `src/server/detect-model.ts`
- [Adapter metadata](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/index.ts): `src/index.ts`
- [Shared constants](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/shared/constants.ts): `src/shared/constants.ts`

### Execution

- [Run executor](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/execute.ts): `src/server/execute.ts`
- **Hermes CLI agent**
- [Session codec](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/index.ts): `src/server/index.ts`

### Skills

- [Skill APIs](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/server/skills.ts): `src/server/skills.ts`
- **Paperclip skills**
- **Hermes skill files**

### Presentation

- [Transcript parser](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/ui/parse-stdout.ts): `src/ui/parse-stdout.ts`
- [CLI event formatter](https://github.com/nousresearch/hermes-paperclip-adapter/blob/main/src/cli/format-event.ts): `src/cli/format-event.ts`

### Other components

- **Paperclip**

## Connections

- Paperclip → Agent config form: configures (evidence: `README.md`)
- Agent config form → Config builder: provides values (evidence: `src/ui/build-config.ts`)
- Paperclip → Run executor: invokes heartbeat (evidence: `README.md`)
- Run executor → Hermes CLI agent: spawns CLI (evidence: `src/server/execute.ts`)
- Run executor → Model detection: detects model (evidence: `src/server/execute.ts`)
- Model detection → Shared constants: uses provider rules (evidence: `src/server/detect-model.ts`)
- Run executor → Shared constants: uses defaults (evidence: `src/server/execute.ts`)
- Run executor → Paperclip: reports run results (evidence: `README.md`)
- Hermes CLI agent → Transcript parser: emits parsed output (evidence: `README.md`)
- Paperclip → Transcript parser: renders transcript (evidence: `README.md`)
- Run executor → Session codec: persists session state (evidence: `README.md`)
- Paperclip → Session codec: validates session state (evidence: `src/server/index.ts`)
- Paperclip → Skill APIs: requests skill snapshot (evidence: `README.md`)
- Skill APIs → Paperclip skills: reads managed skills (evidence: `src/server/skills.ts`)
- Skill APIs → Hermes skill files: scans skill files (evidence: `src/server/skills.ts`)
- Skill APIs → Paperclip: returns snapshot (evidence: `README.md`)
- Hermes CLI agent → CLI event formatter: streams events
- Adapter metadata → Shared constants: uses adapter identity (evidence: `src/index.ts`)
- Config builder → Shared constants: uses defaults (evidence: `src/ui/build-config.ts`)
- Transcript parser → Shared constants: uses output markers (evidence: `src/ui/parse-stdout.ts`)
