# burning-ice420/agentic-os architecture

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

- Interactive diagram: https://gitdiagram.com/burning-ice420/agentic-os
- Repository: https://github.com/burning-ice420/agentic-os

## Overview

Agentic-OS is a workspace spanning a bare-metal interactive OS, a reusable asynchronous HiveMind kernel/API, a desktop observer, and a VM/mesh service. The OS workflow runs from boot into shell and desktop interaction, with state held in Hive memory and persisted through disk/VFS; agents and an LLM accelerator provide reactive and delegated cognition. The README only names the product, so capability detail comes from the sampled source and SOURCE INDEX; unsampled subsystem links are omitted where their callers are unclear.

Main entry points: [`hivemind/hivemind-os/src/shell.rs`](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/shell.rs) (Interactive shell), [`hivemind/hivemind-os/src/hive/mod.rs`](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/hive/mod.rs) (Memory graph), [`hivemind/hivemind-os/src/disk/persist.rs`](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/disk/persist.rs) (Hive persistence), [`hivemind/hivemind-kernel/src/api.rs`](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/api.rs) (Kernel API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_os["Bare-metal OS"]
  node_osboot["OS boot runtime<br/>[main.rs]"]
  node_shell["Interactive shell<br/>[shell.rs]"]
  node_desktop["Desktop UI<br/>[desktop.rs]"]
  node_hive[("Memory graph<br/>[mod.rs]")]
  node_blob["Blob values<br/>[blob.rs]"]
  node_memnode["Memory nodes<br/>[memory_node.rs]"]
  node_agents["Reactive agents<br/>[mod.rs]"]
  node_llm["LLM accelerator<br/>[llm.rs]"]
  node_mesh["Serial mesh<br/>[mod.rs]"]
  node_disk["ATA disk driver<br/>[mod.rs]"]
  node_persistence["Hive persistence<br/>[persist.rs]"]
  node_vfs[("RAM filesystem<br/>[mod.rs]")]
  node_interrupts["Interrupt and ticks<br/>[interrupts.rs]"]
end

subgraph group_kernel["HiveMind Kernel"]
  node_kernelapi["Kernel API<br/>[api.rs]"]
  node_kernelhive[("Async Hive graph<br/>[hive.rs]")]
  node_kernelagent["Kernel agents<br/>[agent.rs]"]
  node_kernelblob["Kernel blobs<br/>[blob.rs]"]
  node_kernelmemory[("Kernel memory<br/>[memory.rs]")]
end

subgraph group_observer["Observer UI"]
  node_observerui["Observer application<br/>[main.rs]"]
  node_graphview["Graph view<br/>[graph_view.rs]"]
  node_layout["Graph layout<br/>[layout.rs]"]
  node_sidebar["Detail sidebar<br/>[sidebar.rs]"]
end

subgraph group_vos["VM and Mesh"]
  node_vosapi["VM service API<br/>[api.rs]"]
  node_vmmanager["VM manager<br/>[vm.rs]"]
  node_meshbridge["VM mesh bridge<br/>[mesh_bridge.rs]"]
end

node_user(("OS user"))
node_qemu["QEMU process"]

node_user -->|"enters commands"| node_shell
node_osboot -->|"starts runtime"| node_shell
node_osboot -->|"starts UI"| node_desktop
node_osboot -->|"initializes state"| node_hive
node_shell -->|"reads and mutates"| node_hive
node_shell -->|"configures agents"| node_agents
node_shell -->|"requests inference"| node_llm
node_shell -->|"uses filesystem"| node_vfs
node_shell -->|"marks state dirty"| node_persistence
node_desktop -->|"reads and mutates"| node_hive
node_desktop -->|"uses filesystem"| node_vfs
node_hive -->|"stores values"| node_blob
node_hive -->|"creates nodes"| node_memnode
node_agents -->|"watches blobs"| node_hive
node_agents -->|"delegates decisions"| node_llm
node_agents -.->|"uses mesh"| node_mesh
node_persistence -->|"reads and writes"| node_disk
node_persistence -->|"serializes state"| node_hive
node_persistence -->|"serializes filesystem"| node_vfs
node_persistence -->|"checks tick"| node_interrupts
node_interrupts -->|"forwards keys"| node_shell
node_kernelapi -->|"dispatches operations"| node_kernelhive
node_kernelapi -->|"dispatches operations"| node_kernelagent
node_kernelapi -->|"uses blob types"| node_kernelblob
node_kernelapi -->|"dispatches operations"| node_kernelmemory
node_kernelhive -->|"manages agents"| node_kernelagent
node_kernelhive -->|"stores blobs"| node_kernelblob
node_kernelhive -->|"stores memories"| node_kernelmemory
node_observerui -->|"renders graph"| node_graphview
node_observerui -->|"uses layout"| node_layout
node_observerui -->|"renders details"| node_sidebar
node_graphview -->|"positions graph"| node_layout
node_vosapi -->|"dispatches VM actions"| node_vmmanager
node_vosapi -->|"dispatches mesh actions"| node_meshbridge
node_meshbridge -->|"uses VM state"| node_vmmanager
node_vmmanager -->|"starts and stops"| node_qemu

click node_osboot "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/main.rs"
click node_shell "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/shell.rs"
click node_desktop "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/desktop.rs"
click node_hive "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/hive/mod.rs"
click node_blob "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/hive/blob.rs"
click node_memnode "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/hive/memory_node.rs"
click node_agents "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/agent/mod.rs"
click node_llm "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/llm.rs"
click node_mesh "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/net/mod.rs"
click node_disk "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/disk/mod.rs"
click node_persistence "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/disk/persist.rs"
click node_vfs "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/vfs/mod.rs"
click node_interrupts "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/interrupts.rs"
click node_kernelapi "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/api.rs"
click node_kernelhive "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/hive.rs"
click node_kernelagent "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/agent.rs"
click node_kernelblob "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/blob.rs"
click node_kernelmemory "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/memory.rs"
click node_observerui "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-observer/src/main.rs"
click node_graphview "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-observer/src/graph_view.rs"
click node_layout "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-observer/src/layout.rs"
click node_sidebar "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-observer/src/sidebar.rs"
click node_vosapi "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-vos/src/api.rs"
click node_vmmanager "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-vos/src/vm.rs"
click node_meshbridge "https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-vos/src/mesh_bridge.rs"

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_osboot,node_shell,node_desktop,node_hive,node_blob,node_memnode,node_agents,node_llm,node_mesh,node_disk,node_persistence,node_vfs,node_interrupts,node_user toneBlue
class node_kernelapi,node_kernelhive,node_kernelagent,node_kernelblob,node_kernelmemory toneAmber
class node_observerui,node_graphview,node_layout,node_sidebar toneMint
class node_vosapi,node_vmmanager,node_meshbridge toneRose
class node_qemu toneIndigo
```

## Components

### Bare-metal OS

- [OS boot runtime](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/main.rs): `hivemind/hivemind-os/src/main.rs`
- [Interactive shell](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/shell.rs): `hivemind/hivemind-os/src/shell.rs`
- [Desktop UI](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/desktop.rs): `hivemind/hivemind-os/src/desktop.rs`
- [Memory graph](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/hive/mod.rs): `hivemind/hivemind-os/src/hive/mod.rs`
- [Blob values](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/hive/blob.rs): `hivemind/hivemind-os/src/hive/blob.rs`
- [Memory nodes](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/hive/memory_node.rs): `hivemind/hivemind-os/src/hive/memory_node.rs`
- [Reactive agents](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/agent/mod.rs): `hivemind/hivemind-os/src/agent/mod.rs`
- [LLM accelerator](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/llm.rs): `hivemind/hivemind-os/src/llm.rs`
- [Serial mesh](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/net/mod.rs): `hivemind/hivemind-os/src/net/mod.rs`
- [ATA disk driver](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/disk/mod.rs): `hivemind/hivemind-os/src/disk/mod.rs`
- [Hive persistence](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/disk/persist.rs): `hivemind/hivemind-os/src/disk/persist.rs`
- [RAM filesystem](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/vfs/mod.rs): `hivemind/hivemind-os/src/vfs/mod.rs`
- [Interrupt and ticks](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-os/src/interrupts.rs): `hivemind/hivemind-os/src/interrupts.rs`

### HiveMind Kernel

- [Kernel API](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/api.rs): `hivemind/hivemind-kernel/src/api.rs`
- [Async Hive graph](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/hive.rs): `hivemind/hivemind-kernel/src/hive.rs`
- [Kernel agents](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/agent.rs): `hivemind/hivemind-kernel/src/agent.rs`
- [Kernel blobs](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/blob.rs): `hivemind/hivemind-kernel/src/blob.rs`
- [Kernel memory](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-kernel/src/memory.rs): `hivemind/hivemind-kernel/src/memory.rs`

### Observer UI

- [Observer application](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-observer/src/main.rs): `hivemind/hivemind-observer/src/main.rs`
- [Graph view](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-observer/src/graph_view.rs): `hivemind/hivemind-observer/src/graph_view.rs`
- [Graph layout](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-observer/src/layout.rs): `hivemind/hivemind-observer/src/layout.rs`
- [Detail sidebar](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-observer/src/sidebar.rs): `hivemind/hivemind-observer/src/sidebar.rs`

### VM and Mesh

- [VM service API](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-vos/src/api.rs): `hivemind/hivemind-vos/src/api.rs`
- [VM manager](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-vos/src/vm.rs): `hivemind/hivemind-vos/src/vm.rs`
- [VM mesh bridge](https://github.com/burning-ice420/agentic-os/blob/main/hivemind/hivemind-vos/src/mesh_bridge.rs): `hivemind/hivemind-vos/src/mesh_bridge.rs`

### Other components

- **OS user**
- **QEMU process**

## Connections

- OS user → Interactive shell: enters commands (evidence: `hivemind/hivemind-os/src/shell.rs`)
- OS boot runtime → Interactive shell: starts runtime (evidence: `hivemind/hivemind-os/src/main.rs`)
- OS boot runtime → Desktop UI: starts UI (evidence: `hivemind/hivemind-os/src/main.rs`)
- OS boot runtime → Memory graph: initializes state (evidence: `hivemind/hivemind-os/src/main.rs`)
- Interactive shell → Memory graph: reads and mutates (evidence: `hivemind/hivemind-os/src/shell.rs`)
- Interactive shell → Reactive agents: configures agents (evidence: `hivemind/hivemind-os/src/shell.rs`)
- Interactive shell → LLM accelerator: requests inference (evidence: `hivemind/hivemind-os/src/shell.rs`)
- Interactive shell → RAM filesystem: uses filesystem (evidence: `hivemind/hivemind-os/src/shell.rs`)
- Interactive shell → Hive persistence: marks state dirty (evidence: `hivemind/hivemind-os/src/shell.rs`)
- Desktop UI → Memory graph: reads and mutates (evidence: `hivemind/hivemind-os/src/desktop.rs`)
- Desktop UI → RAM filesystem: uses filesystem (evidence: `hivemind/hivemind-os/src/desktop.rs`)
- Memory graph → Blob values: stores values (evidence: `hivemind/hivemind-os/src/hive/mod.rs`)
- Memory graph → Memory nodes: creates nodes (evidence: `hivemind/hivemind-os/src/hive/mod.rs`)
- Reactive agents → Memory graph: watches blobs (evidence: `hivemind/hivemind-os/src/agent/mod.rs`)
- Reactive agents → LLM accelerator: delegates decisions (evidence: `hivemind/hivemind-os/src/agent/mod.rs`)
- Reactive agents → Serial mesh: uses mesh (evidence: `hivemind/hivemind-os/src/agent/mod.rs`)
- Hive persistence → ATA disk driver: reads and writes (evidence: `hivemind/hivemind-os/src/disk/persist.rs`)
- Hive persistence → Memory graph: serializes state (evidence: `hivemind/hivemind-os/src/disk/persist.rs`)
- Hive persistence → RAM filesystem: serializes filesystem (evidence: `hivemind/hivemind-os/src/disk/persist.rs`)
- Hive persistence → Interrupt and ticks: checks tick (evidence: `hivemind/hivemind-os/src/disk/persist.rs`)
- Interrupt and ticks → Interactive shell: forwards keys (evidence: `hivemind/hivemind-os/src/interrupts.rs`)
- Kernel API → Async Hive graph: dispatches operations (evidence: `hivemind/hivemind-kernel/src/api.rs`)
- Kernel API → Kernel agents: dispatches operations (evidence: `hivemind/hivemind-kernel/src/api.rs`)
- Kernel API → Kernel blobs: uses blob types (evidence: `hivemind/hivemind-kernel/src/api.rs`)
- Kernel API → Kernel memory: dispatches operations (evidence: `hivemind/hivemind-kernel/src/api.rs`)
- Async Hive graph → Kernel agents: manages agents (evidence: `hivemind/hivemind-kernel/src/hive.rs`)
- Async Hive graph → Kernel blobs: stores blobs (evidence: `hivemind/hivemind-kernel/src/hive.rs`)
- Async Hive graph → Kernel memory: stores memories (evidence: `hivemind/hivemind-kernel/src/hive.rs`)
- Observer application → Graph view: renders graph (evidence: `hivemind/hivemind-observer/src/main.rs`)
- Observer application → Graph layout: uses layout (evidence: `hivemind/hivemind-observer/src/main.rs`)
- Observer application → Detail sidebar: renders details (evidence: `hivemind/hivemind-observer/src/main.rs`)
- Graph view → Graph layout: positions graph (evidence: `hivemind/hivemind-observer/src/graph_view.rs`)
- VM service API → VM manager: dispatches VM actions (evidence: `hivemind/hivemind-vos/src/api.rs`)
- VM service API → VM mesh bridge: dispatches mesh actions (evidence: `hivemind/hivemind-vos/src/api.rs`)
- VM mesh bridge → VM manager: uses VM state (evidence: `hivemind/hivemind-vos/src/mesh_bridge.rs`)
- VM manager → QEMU process: starts and stops (evidence: `hivemind/hivemind-vos/src/vm.rs`)