# bkashjee/hermes-bot-forge architecture

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

- Interactive diagram: https://gitdiagram.com/bkashjee/hermes-bot-forge
- Repository: https://github.com/bkashjee/hermes-bot-forge

## Overview

Bot Forge is a Hermes plugin for creating and operating Bots (Hermes profiles) from chat requests. The main flow dispatches tool calls through tools.py to forge.py, which builds a profile and its persona, memory, capabilities, routines, chat, and gateway. Other product branches manage existing Bots and teams, share templates, teach skills, maintain journals, and provide health checks and turn acknowledgements. Some subsystem links are based on README capabilities because the corresponding implementation excerpts were not sampled.

Main entry points: [`tools.py`](https://github.com/bkashjee/hermes-bot-forge/blob/main/tools.py) (Tool handlers), [`forge.py`](https://github.com/bkashjee/hermes-bot-forge/blob/main/forge.py) (Profile builder), [`team.py`](https://github.com/bkashjee/hermes-bot-forge/blob/main/team.py) (Team builder), [`portable.py`](https://github.com/bkashjee/hermes-bot-forge/blob/main/portable.py) (Template handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Plugin interface"]
  node_tools["Tool handlers<br/>[tools.py]"]
end

subgraph group_build["Bot construction"]
  node_forge["Profile builder<br/>[forge.py]"]
  node_profile[("Bot profile")]
  node_team["Team builder<br/>[team.py]"]
  node_skill["Taught skills"]
end

subgraph group_operations["Bot operations"]
  node_manage["Bot management<br/>[manage.py]"]
end

subgraph group_support["Bot runtime support"]
  node_journal["Work journal<br/>[journal.py]"]
  node_journalstore[("Profile journal files")]
  node_survey["Workspace survey<br/>[survey.py]"]
  node_doctor["Install doctor<br/>[doctor.py]"]
  node_tapback["Turn acknowledgements<br/>[tapback.py]"]
end

subgraph group_sharing["Portability"]
  node_portable["Template handling<br/>[portable.py]"]
  node_templates["Bundled templates"]
end

node_agent(("Chatting agent"))
node_hermes["Hermes platform"]
node_react["Message reaction tool"]
node_gateway["Hermes gateway"]

node_agent -->|"requests tools"| node_tools
node_tools -->|"runs builder"| node_forge
node_tools -->|"runs team builder"| node_team
node_team -->|"builds members"| node_forge
node_forge -->|"creates profile"| node_profile
node_forge -.->|"installs gateway"| node_gateway
node_forge -.->|"starts Bot Chat"| node_hermes
node_tools -->|"dispatches management"| node_manage
node_manage -->|"updates profiles"| node_profile
node_tools -->|"dispatches journal"| node_journal
node_journal -->|"reads and writes"| node_journalstore
node_tools -->|"dispatches sharing"| node_portable
node_portable -->|"exports and imports"| node_profile
node_portable -->|"loads templates"| node_templates
node_tools -->|"saves procedures"| node_skill
node_team -->|"records team roster"| node_profile
node_doctor -->|"checks installation"| node_profile
node_doctor -->|"checks gateway"| node_gateway
node_tapback -->|"dispatches reaction"| node_react
node_hermes -->|"runs turn hooks"| node_tapback
node_survey -->|"reads Bot context"| node_profile

click node_tools "https://github.com/bkashjee/hermes-bot-forge/blob/main/tools.py"
click node_forge "https://github.com/bkashjee/hermes-bot-forge/blob/main/forge.py"
click node_team "https://github.com/bkashjee/hermes-bot-forge/blob/main/team.py"
click node_skill "https://github.com/bkashjee/hermes-bot-forge/tree/main/skills"
click node_manage "https://github.com/bkashjee/hermes-bot-forge/blob/main/manage.py"
click node_portable "https://github.com/bkashjee/hermes-bot-forge/blob/main/portable.py"
click node_templates "https://github.com/bkashjee/hermes-bot-forge/tree/main/templates"
click node_journal "https://github.com/bkashjee/hermes-bot-forge/blob/main/journal.py"
click node_survey "https://github.com/bkashjee/hermes-bot-forge/blob/main/survey.py"
click node_doctor "https://github.com/bkashjee/hermes-bot-forge/blob/main/doctor.py"
click node_tapback "https://github.com/bkashjee/hermes-bot-forge/blob/main/marks/tapback.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_tools toneBlue
class node_forge,node_profile,node_team,node_skill toneAmber
class node_manage toneMint
class node_journal,node_journalstore,node_survey,node_doctor,node_tapback toneRose
class node_portable,node_templates,node_agent,node_hermes,node_react,node_gateway toneIndigo
```

## Components

### Plugin interface

- [Tool handlers](https://github.com/bkashjee/hermes-bot-forge/blob/main/tools.py): `tools.py`

### Bot construction

- [Profile builder](https://github.com/bkashjee/hermes-bot-forge/blob/main/forge.py): `forge.py`
- **Bot profile**
- [Team builder](https://github.com/bkashjee/hermes-bot-forge/blob/main/team.py): `team.py`
- [Taught skills](https://github.com/bkashjee/hermes-bot-forge/tree/main/skills): `skills`

### Bot operations

- [Bot management](https://github.com/bkashjee/hermes-bot-forge/blob/main/manage.py): `manage.py`

### Bot runtime support

- [Work journal](https://github.com/bkashjee/hermes-bot-forge/blob/main/journal.py): `journal.py`
- **Profile journal files**
- [Workspace survey](https://github.com/bkashjee/hermes-bot-forge/blob/main/survey.py): `survey.py`
- [Install doctor](https://github.com/bkashjee/hermes-bot-forge/blob/main/doctor.py): `doctor.py`
- [Turn acknowledgements](https://github.com/bkashjee/hermes-bot-forge/blob/main/marks/tapback.py): `marks/tapback.py`

### Portability

- [Template handling](https://github.com/bkashjee/hermes-bot-forge/blob/main/portable.py): `portable.py`
- [Bundled templates](https://github.com/bkashjee/hermes-bot-forge/tree/main/templates): `templates`

### Other components

- **Chatting agent**
- **Hermes platform**
- **Message reaction tool**
- **Hermes gateway**

## Connections

- Chatting agent → Tool handlers: requests tools
- Tool handlers → Profile builder: runs builder
- Tool handlers → Team builder: runs team builder
- Team builder → Profile builder: builds members
- Profile builder → Bot profile: creates profile
- Profile builder → Hermes gateway: installs gateway
- Profile builder → Hermes platform: starts Bot Chat
- Tool handlers → Bot management: dispatches management
- Bot management → Bot profile: updates profiles
- Tool handlers → Work journal: dispatches journal
- Work journal → Profile journal files: reads and writes
- Tool handlers → Template handling: dispatches sharing
- Template handling → Bot profile: exports and imports
- Template handling → Bundled templates: loads templates
- Tool handlers → Taught skills: saves procedures
- Team builder → Bot profile: records team roster
- Install doctor → Bot profile: checks installation
- Install doctor → Hermes gateway: checks gateway
- Turn acknowledgements → Message reaction tool: dispatches reaction
- Hermes platform → Turn acknowledgements: runs turn hooks
- Workspace survey → Bot profile: reads Bot context