# novique-ai/retinue architecture

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

- Interactive diagram: https://gitdiagram.com/novique-ai/retinue
- Repository: https://github.com/novique-ai/retinue

## Overview

Retinue is a local-first application for hiring named AI teammates and coordinating them in shared rooms. The principal workflow is: a person configures retainers and a room in the web interface, sends a message, and the rooms platform adapter applies turn-taking while Hermes runs the selected agents; replies appear in the shared transcript. Room work can use a shared or isolated Podman/Docker workspace. Routines, voice, and IDE-attached workspaces are additional documented capabilities. The tree omits the documented web and gateway implementations, so those connections are shown only at the level supported by the README.

Main entry points: [`plugins/platforms/retinue_rooms`](https://github.com/novique-ai/retinue/tree/main/plugins/platforms/retinue_rooms) (Rooms adapter), [`agent/conversation_loop.py`](https://github.com/novique-ai/retinue/blob/main/agent/conversation_loop.py) (Agent conversation loop), [`plugins/platforms/retinue_rooms/speech_humanize/pipeline.py`](https://github.com/novique-ai/retinue/blob/main/plugins/platforms/retinue_rooms/speech_humanize/pipeline.py) (Speech humanization), [`plugins/platforms/retinue_rooms/engine.py`](https://github.com/novique-ai/retinue/blob/main/plugins/platforms/retinue_rooms/engine.py) (Turn-taking rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Room experience"]
  node_web["Web interface"]
  node_voice["Speech humanization<br/>[pipeline.py]"]
end

subgraph group_coordination["Room coordination"]
  node_room_adapter["Rooms adapter"]
  node_room_engine["Turn-taking rules<br/>[engine.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_gateway["Hermes gateway"]
  node_agent_loop["Agent conversation loop"]
  node_agent_tools["Agent tools<br/>[tool_executor.py]"]
end

subgraph group_workspace["Workspaces and routines"]
  node_workspace["Container workspace"]
  node_podman["Podman or Docker"]
  node_routines["Room routines"]
  node_host_mount["IDE host mount"]
end

node_person(("Room participant"))

node_person -->|"uses"| node_web
node_web -->|"sends room requests"| node_gateway
node_gateway -->|"dispatches room events"| node_room_adapter
node_room_adapter -->|"applies turn-taking"| node_room_engine
node_room_adapter -->|"runs agent turns"| node_agent_loop
node_agent_loop -->|"dispatches tools"| node_agent_tools
node_room_adapter -->|"publishes room updates"| node_web
node_room_adapter -.->|"prepares spoken text"| node_voice
node_workspace -->|"runs in"| node_podman
node_routines -->|"runs jobs in"| node_workspace
node_host_mount -.->|"bind-mounts"| node_workspace

click node_room_adapter "https://github.com/novique-ai/retinue/tree/main/plugins/platforms/retinue_rooms"
click node_room_engine "https://github.com/novique-ai/retinue/blob/main/plugins/platforms/retinue_rooms/engine.py"
click node_agent_loop "https://github.com/novique-ai/retinue/blob/main/agent/conversation_loop.py"
click node_agent_tools "https://github.com/novique-ai/retinue/blob/main/agent/tool_executor.py"
click node_voice "https://github.com/novique-ai/retinue/blob/main/plugins/platforms/retinue_rooms/speech_humanize/pipeline.py"
click node_routines "https://github.com/novique-ai/retinue/tree/main/plugins/platforms/retinue_rooms"

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_web,node_voice toneBlue
class node_room_adapter,node_room_engine toneAmber
class node_gateway,node_agent_loop,node_agent_tools toneMint
class node_workspace,node_podman,node_routines,node_host_mount toneRose
class node_person toneIndigo
```

## Components

### Room experience

- **Web interface**
- [Speech humanization](https://github.com/novique-ai/retinue/blob/main/plugins/platforms/retinue_rooms/speech_humanize/pipeline.py): `plugins/platforms/retinue_rooms/speech_humanize/pipeline.py`

### Room coordination

- [Rooms adapter](https://github.com/novique-ai/retinue/tree/main/plugins/platforms/retinue_rooms): `plugins/platforms/retinue_rooms`
- [Turn-taking rules](https://github.com/novique-ai/retinue/blob/main/plugins/platforms/retinue_rooms/engine.py): `plugins/platforms/retinue_rooms/engine.py`

### Agent runtime

- **Hermes gateway**
- [Agent conversation loop](https://github.com/novique-ai/retinue/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Agent tools](https://github.com/novique-ai/retinue/blob/main/agent/tool_executor.py): `agent/tool_executor.py`

### Workspaces and routines

- **Container workspace**
- **Podman or Docker**
- [Room routines](https://github.com/novique-ai/retinue/tree/main/plugins/platforms/retinue_rooms): `plugins/platforms/retinue_rooms`
- **IDE host mount**

### Other components

- **Room participant**

## Connections

- Room participant → Web interface: uses
- Web interface → Hermes gateway: sends room requests
- Hermes gateway → Rooms adapter: dispatches room events
- Rooms adapter → Turn-taking rules: applies turn-taking
- Rooms adapter → Agent conversation loop: runs agent turns
- Agent conversation loop → Agent tools: dispatches tools
- Rooms adapter → Web interface: publishes room updates
- Rooms adapter → Speech humanization: prepares spoken text
- Container workspace → Podman or Docker: runs in
- Room routines → Container workspace: runs jobs in
- IDE host mount → Container workspace: bind-mounts