# hkuds/nanobot architecture

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

- Interactive diagram: https://gitdiagram.com/hkuds/nanobot
- Repository: https://github.com/hkuds/nanobot
- Video tour (about a minute): https://gitdiagram.com/hkuds/nanobot/video

## Overview

nanobot is a self-hosted personal AI agent framework. A user submits a request through the WebUI, terminal, API, or a chat channel; the agent processes it with a configured model and tools, then returns a response through the initiating surface. Sessions preserve history, while memory, scheduled automation, integrations, and remote access extend that core workflow. The graph reflects documented capabilities and source-index references; unsampled subsystem links are omitted where their wiring is not evidenced.

Main entry points: [`nanobot/agent/loop.py`](https://github.com/hkuds/nanobot/blob/main/nanobot/agent/loop.py) (Agent loop), [`nanobot/api/server.py`](https://github.com/hkuds/nanobot/blob/main/nanobot/api/server.py) (Agent API), [`nanobot/channels/manager.py`](https://github.com/hkuds/nanobot/blob/main/nanobot/channels/manager.py) (Chat channels), [`nanobot/bus/queue.py`](https://github.com/hkuds/nanobot/blob/main/nanobot/bus/queue.py) (Message bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_webui["Browser UI<br/>[App.tsx]"]
  node_terminal["Terminal UI<br/>[app.ts]"]
  node_api["Agent API<br/>[server.py]"]
  node_channels["Chat channels<br/>[manager.py]"]
  node_gateway["Agent gateway<br/>[service.py]"]
  node_sdk["Python SDK<br/>[clients.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_bus["Message bus<br/>[queue.py]"]
  node_agent["Agent loop<br/>[loop.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tools["Agent tools<br/>[registry.py]"]
  node_memory["Long-term memory<br/>[memory.py]"]
  node_subagents["Subagent delegation<br/>[subagent.py]"]
end

subgraph group_state["Persistence and scheduling"]
  node_sessions[("Session history<br/>[manager.py]")]
  node_cron[("Scheduled tasks<br/>[service.py]")]
end

subgraph group_integrations["Models and integrations"]
  node_config["Configuration<br/>[loader.py]"]
  node_providers["Model providers<br/>[base.py]"]
  node_mcp["MCP integrations<br/>[mcp.py]"]
end

node_user(("User"))
node_externalmodel(("Model service"))

node_user -->|"submits requests"| node_webui
node_user -->|"submits requests"| node_terminal
node_user -->|"sends requests"| node_api
node_user -->|"sends messages"| node_channels
node_webui -.->|"routes messages"| node_bus
node_channels -->|"dispatches messages"| node_bus
node_bus -->|"delivers messages"| node_agent
node_api -->|"runs requests"| node_agent
node_terminal -.->|"uses HTTP API"| node_api
node_agent -->|"requests completion"| node_providers
node_providers -.->|"calls model"| node_externalmodel
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"reads and writes"| node_sessions
node_agent -->|"uses memory"| node_memory
node_agent -->|"delegates tasks"| node_subagents
node_cron -->|"runs scheduled turns"| node_agent
node_config -->|"configures models"| node_providers
node_tools -.->|"loads integrations"| node_mcp
node_gateway -.->|"hosts channel runtime"| node_channels
node_sdk -->|"starts agent turns"| node_agent

click node_webui "https://github.com/hkuds/nanobot/blob/main/webui/src/App.tsx"
click node_terminal "https://github.com/hkuds/nanobot/blob/main/tui/src/app/app.ts"
click node_api "https://github.com/hkuds/nanobot/blob/main/nanobot/api/server.py"
click node_channels "https://github.com/hkuds/nanobot/blob/main/nanobot/channels/manager.py"
click node_bus "https://github.com/hkuds/nanobot/blob/main/nanobot/bus/queue.py"
click node_agent "https://github.com/hkuds/nanobot/blob/main/nanobot/agent/loop.py"
click node_tools "https://github.com/hkuds/nanobot/blob/main/nanobot/agent/tools/registry.py"
click node_memory "https://github.com/hkuds/nanobot/blob/main/nanobot/agent/memory.py"
click node_subagents "https://github.com/hkuds/nanobot/blob/main/nanobot/agent/subagent.py"
click node_sessions "https://github.com/hkuds/nanobot/blob/main/nanobot/session/manager.py"
click node_cron "https://github.com/hkuds/nanobot/blob/main/nanobot/cron/service.py"
click node_config "https://github.com/hkuds/nanobot/blob/main/nanobot/config/loader.py"
click node_providers "https://github.com/hkuds/nanobot/blob/main/nanobot/providers/base.py"
click node_mcp "https://github.com/hkuds/nanobot/blob/main/nanobot/agent/tools/mcp.py"
click node_gateway "https://github.com/hkuds/nanobot/blob/main/nanobot/gateway/service.py"
click node_sdk "https://github.com/hkuds/nanobot/blob/main/nanobot/sdk/clients.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_webui,node_terminal,node_api,node_channels,node_gateway,node_sdk,node_user toneBlue
class node_bus,node_agent toneAmber
class node_tools,node_memory,node_subagents toneMint
class node_sessions,node_cron toneRose
class node_config,node_providers,node_mcp,node_externalmodel toneIndigo
```

## Components

### User surfaces

- [Browser UI](https://github.com/hkuds/nanobot/blob/main/webui/src/App.tsx): `webui/src/App.tsx`
- [Terminal UI](https://github.com/hkuds/nanobot/blob/main/tui/src/app/app.ts): `tui/src/app/app.ts`
- [Agent API](https://github.com/hkuds/nanobot/blob/main/nanobot/api/server.py): `nanobot/api/server.py`
- [Chat channels](https://github.com/hkuds/nanobot/blob/main/nanobot/channels/manager.py): `nanobot/channels/manager.py`
- [Agent gateway](https://github.com/hkuds/nanobot/blob/main/nanobot/gateway/service.py): `nanobot/gateway/service.py`
- [Python SDK](https://github.com/hkuds/nanobot/blob/main/nanobot/sdk/clients.py): `nanobot/sdk/clients.py`

### Agent runtime

- [Message bus](https://github.com/hkuds/nanobot/blob/main/nanobot/bus/queue.py): `nanobot/bus/queue.py`
- [Agent loop](https://github.com/hkuds/nanobot/blob/main/nanobot/agent/loop.py): `nanobot/agent/loop.py`

### Agent capabilities

- [Agent tools](https://github.com/hkuds/nanobot/blob/main/nanobot/agent/tools/registry.py): `nanobot/agent/tools/registry.py`
- [Long-term memory](https://github.com/hkuds/nanobot/blob/main/nanobot/agent/memory.py): `nanobot/agent/memory.py`
- [Subagent delegation](https://github.com/hkuds/nanobot/blob/main/nanobot/agent/subagent.py): `nanobot/agent/subagent.py`

### Persistence and scheduling

- [Session history](https://github.com/hkuds/nanobot/blob/main/nanobot/session/manager.py): `nanobot/session/manager.py`
- [Scheduled tasks](https://github.com/hkuds/nanobot/blob/main/nanobot/cron/service.py): `nanobot/cron/service.py`

### Models and integrations

- [Configuration](https://github.com/hkuds/nanobot/blob/main/nanobot/config/loader.py): `nanobot/config/loader.py`
- [Model providers](https://github.com/hkuds/nanobot/blob/main/nanobot/providers/base.py): `nanobot/providers/base.py`
- [MCP integrations](https://github.com/hkuds/nanobot/blob/main/nanobot/agent/tools/mcp.py): `nanobot/agent/tools/mcp.py`

### Other components

- **User**
- **Model service**

## Connections

- User → Browser UI: submits requests (evidence: `README.md`)
- User → Terminal UI: submits requests (evidence: `README.md`)
- User → Agent API: sends requests (evidence: `README.md`)
- User → Chat channels: sends messages (evidence: `README.md`)
- Browser UI → Message bus: routes messages
- Chat channels → Message bus: dispatches messages (evidence: `nanobot/channels/manager.py`)
- Message bus → Agent loop: delivers messages (evidence: `nanobot/bus/queue.py`)
- Agent API → Agent loop: runs requests (evidence: `nanobot/api/server.py`)
- Terminal UI → Agent API: uses HTTP API
- Agent loop → Model providers: requests completion (evidence: `nanobot/agent/loop.py`)
- Model providers → Model service: calls model
- Agent loop → Agent tools: dispatches tools (evidence: `nanobot/agent/loop.py`)
- Agent loop → Session history: reads and writes (evidence: `nanobot/agent/loop.py`)
- Agent loop → Long-term memory: uses memory (evidence: `nanobot/agent/loop.py`)
- Agent loop → Subagent delegation: delegates tasks (evidence: `nanobot/agent/loop.py`)
- Scheduled tasks → Agent loop: runs scheduled turns (evidence: `nanobot/cron/service.py`)
- Configuration → Model providers: configures models
- Agent tools → MCP integrations: loads integrations
- Agent gateway → Chat channels: hosts channel runtime
- Python SDK → Agent loop: starts agent turns (evidence: `nanobot/sdk/clients.py`)
