# rkfshakti/hermes-sidecar architecture

> Architecture diagram of the GitHub repository rkfshakti/hermes-sidecar, 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-sidecar
- Repository: https://github.com/rkfshakti/hermes-sidecar

## Overview

Sidecar bridges a remote Hermes agent to command execution on the user's local machine: Hermes selects the Sidecar terminal backend, which sends requests to a paired local daemon. The daemon authenticates each request, applies local policy and approval, executes permitted commands, and records decisions in a local audit log. Pairing and inspection are supporting workflows. The README documents the overall bridge; sampled source confirms the provider/client and daemon internals, while some daemon execution details are not shown in the excerpts.

Main entry points: [`daemon.py`](https://github.com/rkfshakti/hermes-sidecar/blob/main/daemon.py) (Local HTTP daemon), [`client.py`](https://github.com/rkfshakti/hermes-sidecar/blob/main/client.py) (HTTP client), [`provider.py`](https://github.com/rkfshakti/hermes-sidecar/blob/main/provider.py) (Terminal provider), [`__init__.py`](https://github.com/rkfshakti/hermes-sidecar/blob/main/__init__.py) (Plugin registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hermes["Hermes integration"]
  node_provider["Terminal provider<br/>[provider.py]"]
  node_config["Remote settings<br/>[config.py]"]
  node_tools["Status and audit tools<br/>[handlers.py]"]
  node_plugin["Plugin registration<br/>[__init__.py]"]
end

subgraph group_bridge["Pairing and bridge"]
  node_cli["Sidecar CLI<br/>[cli.py]"]
  node_pairing["Pairing tokens<br/>[pairing.py]"]
  node_client["HTTP client<br/>[client.py]"]
  node_daemon["Local HTTP daemon<br/>[daemon.py]"]
end

subgraph group_local["Local execution controls"]
  node_policy["Command policy<br/>[policy.py]"]
  node_approval["Approval prompt<br/>[daemon.py]"]
  node_execution["Command execution<br/>[daemon.py]"]
end

subgraph group_records["Audit and inspection"]
  node_auditlog[("Local audit log<br/>[audit.py]")]
end

node_remote(("Remote Hermes"))
node_localuser(("Local user"))

node_remote -->|"selects backend"| node_provider
node_plugin -->|"registers"| node_provider
node_plugin -->|"registers"| node_tools
node_provider -->|"loads settings"| node_config
node_provider -->|"sends commands"| node_client
node_client -->|"HTTP requests"| node_daemon
node_daemon -->|"returns output"| node_client
node_cli -->|"creates pairing"| node_pairing
node_pairing -->|"authorizes requests"| node_daemon
node_daemon -->|"checks command"| node_policy
node_daemon -->|"requests approval"| node_approval
node_localuser -->|"approves or denies"| node_approval
node_daemon -->|"runs approved command"| node_execution
node_daemon -->|"records decisions"| node_auditlog
node_tools -->|"reads status and audit"| node_client
node_client -->|"fetches audit entries"| node_auditlog
node_cli -->|"tests bridge"| node_client

click node_provider "https://github.com/rkfshakti/hermes-sidecar/blob/main/provider.py"
click node_config "https://github.com/rkfshakti/hermes-sidecar/blob/main/config.py"
click node_tools "https://github.com/rkfshakti/hermes-sidecar/blob/main/handlers.py"
click node_plugin "https://github.com/rkfshakti/hermes-sidecar/blob/main/__init__.py"
click node_cli "https://github.com/rkfshakti/hermes-sidecar/blob/main/cli.py"
click node_pairing "https://github.com/rkfshakti/hermes-sidecar/blob/main/pairing.py"
click node_client "https://github.com/rkfshakti/hermes-sidecar/blob/main/client.py"
click node_daemon "https://github.com/rkfshakti/hermes-sidecar/blob/main/daemon.py"
click node_policy "https://github.com/rkfshakti/hermes-sidecar/blob/main/policy.py"
click node_approval "https://github.com/rkfshakti/hermes-sidecar/blob/main/daemon.py"
click node_execution "https://github.com/rkfshakti/hermes-sidecar/blob/main/daemon.py"
click node_auditlog "https://github.com/rkfshakti/hermes-sidecar/blob/main/audit.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_provider,node_config,node_tools,node_plugin,node_localuser toneBlue
class node_cli,node_pairing,node_client,node_daemon toneAmber
class node_policy,node_approval,node_execution toneMint
class node_auditlog toneRose
class node_remote toneIndigo
```

## Components

### Hermes integration

- [Terminal provider](https://github.com/rkfshakti/hermes-sidecar/blob/main/provider.py): `provider.py`
- [Remote settings](https://github.com/rkfshakti/hermes-sidecar/blob/main/config.py): `config.py`
- [Status and audit tools](https://github.com/rkfshakti/hermes-sidecar/blob/main/handlers.py): `handlers.py`
- [Plugin registration](https://github.com/rkfshakti/hermes-sidecar/blob/main/__init__.py): `__init__.py`

### Pairing and bridge

- [Sidecar CLI](https://github.com/rkfshakti/hermes-sidecar/blob/main/cli.py): `cli.py`
- [Pairing tokens](https://github.com/rkfshakti/hermes-sidecar/blob/main/pairing.py): `pairing.py`
- [HTTP client](https://github.com/rkfshakti/hermes-sidecar/blob/main/client.py): `client.py`
- [Local HTTP daemon](https://github.com/rkfshakti/hermes-sidecar/blob/main/daemon.py): `daemon.py`

### Local execution controls

- [Command policy](https://github.com/rkfshakti/hermes-sidecar/blob/main/policy.py): `policy.py`
- [Approval prompt](https://github.com/rkfshakti/hermes-sidecar/blob/main/daemon.py): `daemon.py`
- [Command execution](https://github.com/rkfshakti/hermes-sidecar/blob/main/daemon.py): `daemon.py`

### Audit and inspection

- [Local audit log](https://github.com/rkfshakti/hermes-sidecar/blob/main/audit.py): `audit.py`

### Other components

- **Remote Hermes**
- **Local user**

## Connections

- Remote Hermes → Terminal provider: selects backend (evidence: `README.md`)
- Plugin registration → Terminal provider: registers (evidence: `__init__.py`)
- Plugin registration → Status and audit tools: registers (evidence: `__init__.py`)
- Terminal provider → Remote settings: loads settings (evidence: `provider.py`)
- Terminal provider → HTTP client: sends commands (evidence: `provider.py`)
- HTTP client → Local HTTP daemon: HTTP requests (evidence: `README.md`)
- Local HTTP daemon → HTTP client: returns output (evidence: `README.md`)
- Sidecar CLI → Pairing tokens: creates pairing (evidence: `README.md`)
- Pairing tokens → Local HTTP daemon: authorizes requests (evidence: `README.md`)
- Local HTTP daemon → Command policy: checks command (evidence: `daemon.py`)
- Local HTTP daemon → Approval prompt: requests approval (evidence: `README.md`)
- Local user → Approval prompt: approves or denies (evidence: `README.md`)
- Local HTTP daemon → Command execution: runs approved command (evidence: `README.md`)
- Local HTTP daemon → Local audit log: records decisions (evidence: `README.md`)
- Status and audit tools → HTTP client: reads status and audit (evidence: `handlers.py`)
- HTTP client → Local audit log: fetches audit entries (evidence: `README.md`)
- Sidecar CLI → HTTP client: tests bridge (evidence: `cli.py`)