# justinv200/hivemind architecture

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

- Interactive diagram: https://gitdiagram.com/justinv200/hivemind
- Repository: https://github.com/justinv200/hivemind

## Overview

HiveMind is a super-agent orchestrator: a human submits a goal, the Queen selects real or virtual compute, and supervised Workers act on Cells while the system manages tools, memory, and resources. The repository also includes the device-side Pollen gateway, Waggle messaging, a browser dashboard, and supporting stores. README statements establish the broad product relationships; sampled source confirms selected runtime details, but many domain modules were not inspected, so uncertain implementation-level links are omitted.

Main entry points: [`packages/hivemind/src/hivemind/cli/run.py`](https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/cli/run.py) (Queen orchestrator), [`packages/hivemind/src/hivemind/wardens`](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/wardens) (Worker agents), [`packages/hivemind/src/hivemind/swarm`](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/swarm) (Swarm devices), [`packages/hivemind/src/hivemind/cell`](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/cell) (Cell runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control and access"]
  node_cli["Hive CLI<br/>[app.py]"]
  node_queen["Queen orchestrator<br/>[run.py]"]
  node_entrance["Hive Entrance<br/>[app.py]"]
  node_dashboard["Observation dashboard<br/>[app.tsx]"]
  node_logging["Logging layer<br/>[logging.py]"]
end

subgraph group_compute["Cells and workers"]
  node_cell["Cell runtime"]
  node_virtual["Virtual Cell fleet<br/>[virtual_cells.py]"]
  node_swarm["Swarm devices"]
  node_warden["Cell Warden<br/>[warden.py]"]
  node_worker["Worker agents"]
  node_exoskeleton["Virtual peripherals"]
end

subgraph group_knowledge["Tools and knowledge"]
  node_royal["Royal Jelly Lab"]
  node_comb[("Comb Registry")]
  node_honey[("Honey Store<br/>[pipeline.py]")]
  node_basket[("Basket artifact store")]
end

subgraph group_protocol["Device protocol"]
  node_waggle["Waggle protocol<br/>[envelope.py]"]
  node_websocket["WebSocket transport"]
  node_pollen["Pollen Packet<br/>[service.py]"]
  node_clock["Clock abstraction<br/>[clock.py]"]
end

node_human(("Human operator"))

node_human -->|"submits goals"| node_cli
node_cli -->|"runs orchestration"| node_queen
node_queen -->|"provisions on demand"| node_virtual
node_queen -->|"dispatches work"| node_cell
node_queen -->|"dispatches remotely"| node_swarm
node_swarm -->|"provides real cells"| node_cell
node_cell -->|"hosts supervisor"| node_warden
node_warden -->|"spawns and supervises"| node_worker
node_worker -->|"uses peripherals"| node_exoskeleton
node_queen -->|"authors tools"| node_royal
node_royal -->|"promotes tools"| node_comb
node_worker -->|"uses stored knowledge"| node_honey
node_worker -->|"keeps artifacts"| node_basket
node_swarm -->|"connects through"| node_pollen
node_pollen -->|"serves messages"| node_waggle
node_websocket -->|"carries frames"| node_waggle
node_queen -->|"exposes services"| node_entrance
node_human -->|"views hive state"| node_dashboard
node_dashboard -.->|"connects to hive"| node_entrance
node_queen -->|"configures logging"| node_logging
node_websocket -->|"waits through"| node_clock

click node_cli "https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/cli/app.py"
click node_queen "https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/cli/run.py"
click node_entrance "https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/entrance/app.py"
click node_dashboard "https://github.com/justinv200/hivemind/blob/main/packages/observation-web/src/app.tsx"
click node_cell "https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/cell"
click node_virtual "https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/cli/compose/virtual_cells.py"
click node_swarm "https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/swarm"
click node_warden "https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/wardens/warden.py"
click node_worker "https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/wardens"
click node_exoskeleton "https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/exoskeleton"
click node_royal "https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/royal_jelly"
click node_comb "https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/royal_jelly"
click node_honey "https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/honey_store/ripening/pipeline.py"
click node_basket "https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/basket"
click node_waggle "https://github.com/justinv200/hivemind/blob/main/packages/waggle/src/waggle/envelope.py"
click node_websocket "https://github.com/justinv200/hivemind/blob/main/packages/waggle/src/waggle/transport/websocket_client.py"
click node_pollen "https://github.com/justinv200/hivemind/blob/main/packages/pollen/src/pollen/bootstrap/service.py"
click node_logging "https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/common/logging.py"
click node_clock "https://github.com/justinv200/hivemind/blob/main/packages/waggle/src/waggle/clock.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_cli,node_queen,node_entrance,node_dashboard,node_logging toneBlue
class node_cell,node_virtual,node_swarm,node_warden,node_worker,node_exoskeleton toneAmber
class node_royal,node_comb,node_honey,node_basket toneMint
class node_waggle,node_websocket,node_pollen,node_clock toneRose
class node_human toneIndigo
```

## Components

### Control and access

- [Hive CLI](https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/cli/app.py): `packages/hivemind/src/hivemind/cli/app.py`
- [Queen orchestrator](https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/cli/run.py): `packages/hivemind/src/hivemind/cli/run.py`
- [Hive Entrance](https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/entrance/app.py): `packages/hivemind/src/hivemind/entrance/app.py`
- [Observation dashboard](https://github.com/justinv200/hivemind/blob/main/packages/observation-web/src/app.tsx): `packages/observation-web/src/app.tsx`
- [Logging layer](https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/common/logging.py): `packages/hivemind/src/hivemind/common/logging.py`

### Cells and workers

- [Cell runtime](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/cell): `packages/hivemind/src/hivemind/cell`
- [Virtual Cell fleet](https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/cli/compose/virtual_cells.py): `packages/hivemind/src/hivemind/cli/compose/virtual_cells.py`
- [Swarm devices](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/swarm): `packages/hivemind/src/hivemind/swarm`
- [Cell Warden](https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/wardens/warden.py): `packages/hivemind/src/hivemind/wardens/warden.py`
- [Worker agents](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/wardens): `packages/hivemind/src/hivemind/wardens`
- [Virtual peripherals](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/exoskeleton): `packages/hivemind/src/hivemind/exoskeleton`

### Tools and knowledge

- [Royal Jelly Lab](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/royal_jelly): `packages/hivemind/src/hivemind/royal_jelly`
- [Comb Registry](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/royal_jelly): `packages/hivemind/src/hivemind/royal_jelly`
- [Honey Store](https://github.com/justinv200/hivemind/blob/main/packages/hivemind/src/hivemind/honey_store/ripening/pipeline.py): `packages/hivemind/src/hivemind/honey_store/ripening/pipeline.py`
- [Basket artifact store](https://github.com/justinv200/hivemind/tree/main/packages/hivemind/src/hivemind/basket): `packages/hivemind/src/hivemind/basket`

### Device protocol

- [Waggle protocol](https://github.com/justinv200/hivemind/blob/main/packages/waggle/src/waggle/envelope.py): `packages/waggle/src/waggle/envelope.py`
- [WebSocket transport](https://github.com/justinv200/hivemind/blob/main/packages/waggle/src/waggle/transport/websocket_client.py): `packages/waggle/src/waggle/transport/websocket_client.py`
- [Pollen Packet](https://github.com/justinv200/hivemind/blob/main/packages/pollen/src/pollen/bootstrap/service.py): `packages/pollen/src/pollen/bootstrap/service.py`
- [Clock abstraction](https://github.com/justinv200/hivemind/blob/main/packages/waggle/src/waggle/clock.py): `packages/waggle/src/waggle/clock.py`

### Other components

- **Human operator**

## Connections

- Human operator → Hive CLI: submits goals (evidence: `README.md`)
- Hive CLI → Queen orchestrator: runs orchestration (evidence: `README.md`)
- Queen orchestrator → Virtual Cell fleet: provisions on demand (evidence: `README.md`)
- Queen orchestrator → Cell runtime: dispatches work (evidence: `README.md`)
- Queen orchestrator → Swarm devices: dispatches remotely (evidence: `README.md`)
- Swarm devices → Cell runtime: provides real cells (evidence: `README.md`)
- Cell runtime → Cell Warden: hosts supervisor (evidence: `README.md`)
- Cell Warden → Worker agents: spawns and supervises (evidence: `README.md`)
- Worker agents → Virtual peripherals: uses peripherals (evidence: `README.md`)
- Queen orchestrator → Royal Jelly Lab: authors tools (evidence: `README.md`)
- Royal Jelly Lab → Comb Registry: promotes tools (evidence: `README.md`)
- Worker agents → Honey Store: uses stored knowledge (evidence: `README.md`)
- Worker agents → Basket artifact store: keeps artifacts (evidence: `README.md`)
- Swarm devices → Pollen Packet: connects through (evidence: `README.md`)
- Pollen Packet → Waggle protocol: serves messages (evidence: `packages/pollen/src/pollen/bootstrap/service.py`)
- WebSocket transport → Waggle protocol: carries frames (evidence: `packages/waggle/src/waggle/transport/websocket_client.py`)
- Queen orchestrator → Hive Entrance: exposes services (evidence: `README.md`)
- Human operator → Observation dashboard: views hive state (evidence: `README.md`)
- Observation dashboard → Hive Entrance: connects to hive
- Queen orchestrator → Logging layer: configures logging (evidence: `packages/hivemind/src/hivemind/common/logging.py`)
- WebSocket transport → Clock abstraction: waits through (evidence: `packages/waggle/src/waggle/transport/websocket_client.py`)
