# rkfshakti/hermes-glassbox architecture

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

- Interactive diagram: https://gitdiagram.com/rkfshakti/hermes-glassbox
- Repository: https://github.com/rkfshakti/hermes-glassbox

## Overview

Hermes Glassbox is a macOS Seatbelt terminal backend and inspection plugin. Hermes routes terminal and file-tool work through the provider; a preflight hook can give early denials for path-based file tools, while the generated Seatbelt profile is the actual boundary. The provider runs commands and records outcomes in a local audit log. Users and agents can inspect policy, verify containment, and view reports through registered tools, slash commands, or the CLI. The README documents these capabilities; some implementation details are unsampled, so the graph omits unverified links.

Main entry points: [`handlers.py`](https://github.com/rkfshakti/hermes-glassbox/blob/main/handlers.py) (Inspection Tools), [`provider.py`](https://github.com/rkfshakti/hermes-glassbox/blob/main/provider.py) (Terminal Provider), [`audit.py`](https://github.com/rkfshakti/hermes-glassbox/blob/main/audit.py) (Audit Log), [`__init__.py`](https://github.com/rkfshakti/hermes-glassbox/blob/main/__init__.py) (Plugin Registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Hermes Integration"]
  node_plugin["Plugin Registration<br/>[__init__.py]"]
  node_preflight["File Preflight<br/>[preflight.py]"]
  node_tool_handlers["Inspection Tools<br/>[handlers.py]"]
  node_tool_schemas["Tool Schemas<br/>[schemas.py]"]
  node_slash_command["Slash Command<br/>[__init__.py]"]
end

subgraph group_containment["Containment Runtime"]
  node_terminal_provider["Terminal Provider<br/>[provider.py]"]
  node_policy["Policy Builder<br/>[policy.py]"]
  node_seatbelt{{"macOS Seatbelt"}}
  node_command_process["Sandboxed Commands<br/>[provider.py]"]
end

subgraph group_audit["Audit and Inspection"]
  node_audit_log[("Audit Log<br/>[audit.py]")]
  node_audit_summary["Audit Summaries<br/>[audit.py]"]
  node_reports["Text and HTML Reports<br/>[audit.py]"]
  node_cli["Glassbox CLI<br/>[cli.py]"]
end

subgraph group_verification["Verification"]
  node_verify["Containment Checks<br/>[verify.py]"]
  node_tool_results["Tool Results<br/>[handlers.py]"]
end

node_hermes(("Hermes Agent"))
node_hermes_cli(("Hermes CLI"))
node_local_filesystem[("Local Filesystem")]

node_hermes -->|"loads plugin"| node_plugin
node_plugin -->|"registers provider"| node_terminal_provider
node_plugin -->|"registers hook"| node_preflight
node_plugin -->|"registers tools"| node_tool_handlers
node_plugin -->|"registers schemas"| node_tool_schemas
node_hermes -->|"dispatches commands"| node_terminal_provider
node_hermes -->|"checks file paths"| node_preflight
node_preflight -->|"checks access"| node_policy
node_terminal_provider -->|"builds profile"| node_policy
node_terminal_provider -->|"runs commands"| node_command_process
node_command_process -->|"executes under"| node_seatbelt
node_seatbelt -->|"enforces access"| node_local_filesystem
node_terminal_provider -->|"records outcomes"| node_audit_log
node_audit_log -->|"writes JSONL"| node_local_filesystem
node_audit_log -->|"summarizes entries"| node_audit_summary
node_audit_summary -->|"renders reports"| node_reports
node_hermes_cli -->|"invokes commands"| node_cli
node_cli -->|"reads entries"| node_audit_log
node_cli -->|"renders reports"| node_reports
node_cli -->|"runs checks"| node_verify
node_hermes -->|"calls inspection tools"| node_tool_handlers
node_tool_handlers -->|"reads entries"| node_audit_log
node_tool_handlers -->|"summarizes entries"| node_audit_summary
node_tool_handlers -->|"builds preview"| node_policy
node_tool_handlers -->|"runs checks"| node_verify
node_verify -->|"creates test environment"| node_terminal_provider
node_verify -->|"returns checks"| node_tool_results
node_hermes -->|"invokes command"| node_slash_command
node_slash_command -->|"reads entries"| node_audit_log
node_slash_command -->|"runs checks"| node_verify
node_slash_command -->|"renders profile"| node_policy

click node_plugin "https://github.com/rkfshakti/hermes-glassbox/blob/main/__init__.py"
click node_preflight "https://github.com/rkfshakti/hermes-glassbox/blob/main/preflight.py"
click node_tool_handlers "https://github.com/rkfshakti/hermes-glassbox/blob/main/handlers.py"
click node_tool_schemas "https://github.com/rkfshakti/hermes-glassbox/blob/main/schemas.py"
click node_terminal_provider "https://github.com/rkfshakti/hermes-glassbox/blob/main/provider.py"
click node_policy "https://github.com/rkfshakti/hermes-glassbox/blob/main/policy.py"
click node_command_process "https://github.com/rkfshakti/hermes-glassbox/blob/main/provider.py"
click node_audit_log "https://github.com/rkfshakti/hermes-glassbox/blob/main/audit.py"
click node_audit_summary "https://github.com/rkfshakti/hermes-glassbox/blob/main/audit.py"
click node_reports "https://github.com/rkfshakti/hermes-glassbox/blob/main/audit.py"
click node_cli "https://github.com/rkfshakti/hermes-glassbox/blob/main/cli.py"
click node_verify "https://github.com/rkfshakti/hermes-glassbox/blob/main/verify.py"
click node_tool_results "https://github.com/rkfshakti/hermes-glassbox/blob/main/handlers.py"
click node_slash_command "https://github.com/rkfshakti/hermes-glassbox/blob/main/__init__.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_plugin,node_preflight,node_tool_handlers,node_tool_schemas,node_slash_command toneBlue
class node_terminal_provider,node_policy,node_seatbelt,node_command_process,node_local_filesystem toneAmber
class node_audit_log,node_audit_summary,node_reports,node_cli toneMint
class node_verify,node_tool_results toneRose
class node_hermes,node_hermes_cli toneIndigo
```

## Components

### Hermes Integration

- [Plugin Registration](https://github.com/rkfshakti/hermes-glassbox/blob/main/__init__.py): `__init__.py`
- [File Preflight](https://github.com/rkfshakti/hermes-glassbox/blob/main/preflight.py): `preflight.py`
- [Inspection Tools](https://github.com/rkfshakti/hermes-glassbox/blob/main/handlers.py): `handlers.py`
- [Tool Schemas](https://github.com/rkfshakti/hermes-glassbox/blob/main/schemas.py): `schemas.py`
- [Slash Command](https://github.com/rkfshakti/hermes-glassbox/blob/main/__init__.py): `__init__.py`

### Containment Runtime

- [Terminal Provider](https://github.com/rkfshakti/hermes-glassbox/blob/main/provider.py): `provider.py`
- [Policy Builder](https://github.com/rkfshakti/hermes-glassbox/blob/main/policy.py): `policy.py`
- **macOS Seatbelt**
- [Sandboxed Commands](https://github.com/rkfshakti/hermes-glassbox/blob/main/provider.py): `provider.py`

### Audit and Inspection

- [Audit Log](https://github.com/rkfshakti/hermes-glassbox/blob/main/audit.py): `audit.py`
- [Audit Summaries](https://github.com/rkfshakti/hermes-glassbox/blob/main/audit.py): `audit.py`
- [Text and HTML Reports](https://github.com/rkfshakti/hermes-glassbox/blob/main/audit.py): `audit.py`
- [Glassbox CLI](https://github.com/rkfshakti/hermes-glassbox/blob/main/cli.py): `cli.py`

### Verification

- [Containment Checks](https://github.com/rkfshakti/hermes-glassbox/blob/main/verify.py): `verify.py`
- [Tool Results](https://github.com/rkfshakti/hermes-glassbox/blob/main/handlers.py): `handlers.py`

### Other components

- **Hermes Agent**
- **Hermes CLI**
- **Local Filesystem**

## Connections

- Hermes Agent → Plugin Registration: loads plugin (evidence: `__init__.py`)
- Plugin Registration → Terminal Provider: registers provider (evidence: `__init__.py`)
- Plugin Registration → File Preflight: registers hook (evidence: `__init__.py`)
- Plugin Registration → Inspection Tools: registers tools (evidence: `__init__.py`)
- Plugin Registration → Tool Schemas: registers schemas (evidence: `__init__.py`)
- Hermes Agent → Terminal Provider: dispatches commands (evidence: `README.md`)
- Hermes Agent → File Preflight: checks file paths (evidence: `README.md`)
- File Preflight → Policy Builder: checks access (evidence: `preflight.py`)
- Terminal Provider → Policy Builder: builds profile (evidence: `provider.py`)
- Terminal Provider → Sandboxed Commands: runs commands (evidence: `provider.py`)
- Sandboxed Commands → macOS Seatbelt: executes under (evidence: `README.md`)
- macOS Seatbelt → Local Filesystem: enforces access (evidence: `README.md`)
- Terminal Provider → Audit Log: records outcomes (evidence: `provider.py`)
- Audit Log → Local Filesystem: writes JSONL (evidence: `audit.py`)
- Audit Log → Audit Summaries: summarizes entries (evidence: `audit.py`)
- Audit Summaries → Text and HTML Reports: renders reports (evidence: `audit.py`)
- Hermes CLI → Glassbox CLI: invokes commands (evidence: `cli.py`)
- Glassbox CLI → Audit Log: reads entries (evidence: `cli.py`)
- Glassbox CLI → Text and HTML Reports: renders reports (evidence: `cli.py`)
- Glassbox CLI → Containment Checks: runs checks (evidence: `cli.py`)
- Hermes Agent → Inspection Tools: calls inspection tools
- Inspection Tools → Audit Log: reads entries (evidence: `handlers.py`)
- Inspection Tools → Audit Summaries: summarizes entries (evidence: `handlers.py`)
- Inspection Tools → Policy Builder: builds preview (evidence: `handlers.py`)
- Inspection Tools → Containment Checks: runs checks (evidence: `handlers.py`)
- Containment Checks → Terminal Provider: creates test environment (evidence: `verify.py`)
- Containment Checks → Tool Results: returns checks (evidence: `handlers.py`)
- Hermes Agent → Slash Command: invokes command (evidence: `__init__.py`)
- Slash Command → Audit Log: reads entries (evidence: `__init__.py`)
- Slash Command → Containment Checks: runs checks (evidence: `__init__.py`)
- Slash Command → Policy Builder: renders profile (evidence: `__init__.py`)