# asimons81/hermes-gpt architecture

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

- Interactive diagram: https://gitdiagram.com/asimons81/hermes-gpt
- Repository: https://github.com/asimons81/hermes-gpt

## Overview

hermes-gpt is a local-first MCP sidecar that exposes selected Hermes Agent capabilities to trusted clients. The principal workflow is a client request reaching the MCP server, passing through an Operator tool surface, and returning a result; mission tools add planning, budget and capability views, recovery decisions, and gated execution. The repository also provides a browser Flight Deck, chat/session access, OAuth, and Fabric/Fleet features. The README documents these capabilities, but most implementation excerpts were not sampled, so uncertain internal call wiring is omitted.

Main entry points: [`operator_policy.py`](https://github.com/asimons81/hermes-gpt/blob/master/operator_policy.py) (Operator tools), [`operator_controller.py`](https://github.com/asimons81/hermes-gpt/blob/master/operator_controller.py) (Mission controller), [`server.py`](https://github.com/asimons81/hermes-gpt/blob/master/server.py) (MCP server), [`operator_contract.py`](https://github.com/asimons81/hermes-gpt/blob/master/operator_contract.py) (Work contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry"]
  node_server["MCP server<br/>[server.py]"]
  node_operator_tools["Operator tools<br/>[operator_policy.py]"]
end

subgraph group_mission["Mission operations"]
  node_missions["Mission lifecycle"]
  node_mission_plan["Mission plans"]
  node_mission_ledger[("Mission ledger")]
  node_mission_budget["Budget envelope"]
  node_capability_manifest["Capability index"]
  node_placement["Placement scoring"]
  node_failure_recovery["Recovery decisions"]
  node_controller["Mission controller"]
  node_contracts["Work contracts"]
  node_delegations["Delegation authority"]
end

subgraph group_fabric["Fabric and fleet"]
  node_fabric["Fabric routing"]
  node_fleet["Fleet operations<br/>[operator_fleet.py]"]
  node_swarm["Swarm workflows"]
end

subgraph group_identity["Identity and sessions"]
  node_oauth["OAuth access<br/>[operator_oauth.py]"]
  node_token_store[("Token store<br/>[token_store.py]")]
  node_sessions["Sessions and chat"]
end

subgraph group_web["Flight Deck"]
  node_web_app["Flight Deck app<br/>[App.tsx]"]
  node_web_api["Web API client<br/>[client.ts]"]
  node_ui_routes["UI API routes<br/>[ui_api.py]"]
  node_ui_missions["Mission views<br/>[ui_missions.py]"]
end

node_mcp_clients(("MCP clients"))
node_hermes_agent["Hermes Agent"]
node_browser(("Browser user"))

node_mcp_clients -->|"send requests"| node_server
node_server -->|"serves tools"| node_operator_tools
node_operator_tools -->|"exposes operations"| node_missions
node_operator_tools -->|"exposes operations"| node_mission_plan
node_operator_tools -->|"exposes queries"| node_mission_ledger
node_operator_tools -->|"exposes checks"| node_mission_budget
node_operator_tools -->|"exposes queries"| node_capability_manifest
node_operator_tools -->|"exposes scoring"| node_placement
node_operator_tools -->|"exposes decisions"| node_failure_recovery
node_operator_tools -->|"exposes controls"| node_controller
node_operator_tools -->|"exposes routing"| node_fabric
node_operator_tools -->|"exposes operations"| node_fleet
node_operator_tools -->|"exposes workflows"| node_swarm
node_operator_tools -->|"exposes auth"| node_oauth
node_operator_tools -->|"exposes chat"| node_sessions
node_controller -->|"dispatches through"| node_contracts
node_controller -->|"checks authority"| node_delegations
node_controller -->|"uses budget gate"| node_mission_budget
node_contracts -.->|"routes work"| node_fabric
node_server -->|"integrates with"| node_hermes_agent
node_oauth -->|"stores tokens"| node_token_store
node_browser -->|"uses"| node_web_app
node_web_app -->|"requests data"| node_web_api
node_web_api -->|"calls endpoints"| node_ui_routes
node_ui_routes -->|"serves mission views"| node_ui_missions
node_ui_missions -->|"reads mission data"| node_missions

click node_server "https://github.com/asimons81/hermes-gpt/blob/master/server.py"
click node_operator_tools "https://github.com/asimons81/hermes-gpt/blob/master/operator_policy.py"
click node_missions "https://github.com/asimons81/hermes-gpt/blob/master/operator_mission.py"
click node_mission_plan "https://github.com/asimons81/hermes-gpt/blob/master/operator_mission_plan.py"
click node_mission_ledger "https://github.com/asimons81/hermes-gpt/blob/master/operator_mission_ledger.py"
click node_mission_budget "https://github.com/asimons81/hermes-gpt/blob/master/operator_mission_budget.py"
click node_capability_manifest "https://github.com/asimons81/hermes-gpt/blob/master/operator_capability_manifest.py"
click node_placement "https://github.com/asimons81/hermes-gpt/blob/master/operator_placement.py"
click node_failure_recovery "https://github.com/asimons81/hermes-gpt/blob/master/operator_failure_semantics.py"
click node_controller "https://github.com/asimons81/hermes-gpt/blob/master/operator_controller.py"
click node_contracts "https://github.com/asimons81/hermes-gpt/blob/master/operator_contract.py"
click node_delegations "https://github.com/asimons81/hermes-gpt/blob/master/operator_delegations.py"
click node_fabric "https://github.com/asimons81/hermes-gpt/blob/master/operator_fabric_router.py"
click node_fleet "https://github.com/asimons81/hermes-gpt/blob/master/operator_fleet.py"
click node_swarm "https://github.com/asimons81/hermes-gpt/blob/master/operator_swarm_workflows.py"
click node_oauth "https://github.com/asimons81/hermes-gpt/blob/master/operator_oauth.py"
click node_token_store "https://github.com/asimons81/hermes-gpt/blob/master/token_store.py"
click node_sessions "https://github.com/asimons81/hermes-gpt/blob/master/operator_session.py"
click node_web_app "https://github.com/asimons81/hermes-gpt/blob/master/web/src/App.tsx"
click node_web_api "https://github.com/asimons81/hermes-gpt/blob/master/web/src/api/client.ts"
click node_ui_routes "https://github.com/asimons81/hermes-gpt/blob/master/ui_api.py"
click node_ui_missions "https://github.com/asimons81/hermes-gpt/blob/master/ui_missions.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_server,node_operator_tools,node_mcp_clients,node_browser toneBlue
class node_missions,node_mission_plan,node_mission_ledger,node_mission_budget,node_capability_manifest,node_placement,node_failure_recovery,node_controller,node_contracts,node_delegations toneAmber
class node_fabric,node_fleet,node_swarm toneMint
class node_oauth,node_token_store,node_sessions toneRose
class node_web_app,node_web_api,node_ui_routes,node_ui_missions,node_hermes_agent toneIndigo
```

## Components

### Client entry

- [MCP server](https://github.com/asimons81/hermes-gpt/blob/master/server.py): `server.py`
- [Operator tools](https://github.com/asimons81/hermes-gpt/blob/master/operator_policy.py): `operator_policy.py`

### Mission operations

- [Mission lifecycle](https://github.com/asimons81/hermes-gpt/blob/master/operator_mission.py): `operator_mission.py`
- [Mission plans](https://github.com/asimons81/hermes-gpt/blob/master/operator_mission_plan.py): `operator_mission_plan.py`
- [Mission ledger](https://github.com/asimons81/hermes-gpt/blob/master/operator_mission_ledger.py): `operator_mission_ledger.py`
- [Budget envelope](https://github.com/asimons81/hermes-gpt/blob/master/operator_mission_budget.py): `operator_mission_budget.py`
- [Capability index](https://github.com/asimons81/hermes-gpt/blob/master/operator_capability_manifest.py): `operator_capability_manifest.py`
- [Placement scoring](https://github.com/asimons81/hermes-gpt/blob/master/operator_placement.py): `operator_placement.py`
- [Recovery decisions](https://github.com/asimons81/hermes-gpt/blob/master/operator_failure_semantics.py): `operator_failure_semantics.py`
- [Mission controller](https://github.com/asimons81/hermes-gpt/blob/master/operator_controller.py): `operator_controller.py`
- [Work contracts](https://github.com/asimons81/hermes-gpt/blob/master/operator_contract.py): `operator_contract.py`
- [Delegation authority](https://github.com/asimons81/hermes-gpt/blob/master/operator_delegations.py): `operator_delegations.py`

### Fabric and fleet

- [Fabric routing](https://github.com/asimons81/hermes-gpt/blob/master/operator_fabric_router.py): `operator_fabric_router.py`
- [Fleet operations](https://github.com/asimons81/hermes-gpt/blob/master/operator_fleet.py): `operator_fleet.py`
- [Swarm workflows](https://github.com/asimons81/hermes-gpt/blob/master/operator_swarm_workflows.py): `operator_swarm_workflows.py`

### Identity and sessions

- [OAuth access](https://github.com/asimons81/hermes-gpt/blob/master/operator_oauth.py): `operator_oauth.py`
- [Token store](https://github.com/asimons81/hermes-gpt/blob/master/token_store.py): `token_store.py`
- [Sessions and chat](https://github.com/asimons81/hermes-gpt/blob/master/operator_session.py): `operator_session.py`

### Flight Deck

- [Flight Deck app](https://github.com/asimons81/hermes-gpt/blob/master/web/src/App.tsx): `web/src/App.tsx`
- [Web API client](https://github.com/asimons81/hermes-gpt/blob/master/web/src/api/client.ts): `web/src/api/client.ts`
- [UI API routes](https://github.com/asimons81/hermes-gpt/blob/master/ui_api.py): `ui_api.py`
- [Mission views](https://github.com/asimons81/hermes-gpt/blob/master/ui_missions.py): `ui_missions.py`

### Other components

- **MCP clients**
- **Hermes Agent**
- **Browser user**

## Connections

- MCP clients → MCP server: send requests
- MCP server → Operator tools: serves tools
- Operator tools → Mission lifecycle: exposes operations
- Operator tools → Mission plans: exposes operations
- Operator tools → Mission ledger: exposes queries
- Operator tools → Budget envelope: exposes checks
- Operator tools → Capability index: exposes queries
- Operator tools → Placement scoring: exposes scoring
- Operator tools → Recovery decisions: exposes decisions
- Operator tools → Mission controller: exposes controls
- Operator tools → Fabric routing: exposes routing
- Operator tools → Fleet operations: exposes operations
- Operator tools → Swarm workflows: exposes workflows
- Operator tools → OAuth access: exposes auth
- Operator tools → Sessions and chat: exposes chat
- Mission controller → Work contracts: dispatches through
- Mission controller → Delegation authority: checks authority
- Mission controller → Budget envelope: uses budget gate
- Work contracts → Fabric routing: routes work
- MCP server → Hermes Agent: integrates with
- OAuth access → Token store: stores tokens
- Browser user → Flight Deck app: uses
- Flight Deck app → Web API client: requests data
- Web API client → UI API routes: calls endpoints
- UI API routes → Mission views: serves mission views
- Mission views → Mission lifecycle: reads mission data