# human-plus-machine/monkeybot architecture

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

- Interactive diagram: https://gitdiagram.com/human-plus-machine/monkeybot
- Repository: https://github.com/human-plus-machine/monkeybot

## Overview

MonkeyBot is a multi-cloud agent runtime for tool-using LLMs. A user can start with the CLI or connect a custom UI to the SSE gateway; the gateway manages sessions and streams agent results. The runtime combines configured model providers with tools, MCP, skills, and memory, while pluggable persistence supports session and transcript data. Separate branches provide realtime voice/text, scheduled loops, and browser automation. The README documents these capabilities; several internal connections below are dashed because the sampled excerpts do not show their wiring.

Main entry points: [`src/monkeybot/gateway/sse/routes.py`](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/sse/routes.py) (Session routes), [`src/monkeybot/core/persistence/backends.py`](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/backends.py) (Storage factory), [`src/monkeybot/core/llm/provider.py`](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/llm/provider.py) (Model providers), [`src/monkeybot/gateway/realtime/routes.py`](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/realtime/routes.py) (Realtime routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entrypoints"]
  node_cli["Agent CLI<br/>[main.py]"]
  node_realtime_cli["Realtime CLI"]
end

subgraph group_gateway["Gateway interfaces"]
  node_sse["SSE gateway<br/>[app.py]"]
  node_sse_routes["Session routes<br/>[routes.py]"]
  node_realtime["Realtime routes<br/>[routes.py]"]
  node_realtime_manager["Session manager<br/>[manager.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_config["Runtime config<br/>[snapshot.py]"]
  node_runtime_loop["Agent turn loop<br/>[loop.py]"]
  node_provider["Model providers<br/>[provider.py]"]
  node_tool_execution["Tool execution"]
  node_attachments["Attachments<br/>[catalog.py]"]
end

subgraph group_state["State and storage"]
  node_memory["Memory subsystem<br/>[ingest.py]"]
  node_storage["Storage factory<br/>[backends.py]"]
  node_transcript["Transcript storage<br/>[transcript.py]"]
  node_sqlite[("SQLite backend<br/>[sqlite_backend.py]")]
  node_postgres[("Postgres backend<br/>[postgres.py]")]
  node_cloud_storage["Cloud storage<br/>[factory.py]"]
end

subgraph group_extensions["Integrations"]
  node_mcp["MCP clients<br/>[mcp_client.py]"]
  node_scheduler["Scheduled loops<br/>[engine.py]"]
  node_browser["Browser MCP<br/>[app.py]"]
  node_browser_server["Browser MCP server<br/>[server.py]"]
  node_browser_context["Chat browser state<br/>[chat_context.py]"]
  node_browser_tabs["Browser tabs<br/>[tabs.py]"]
end

node_user(("User or UI"))
node_model_service["External model API"]
node_mcp_service["MCP tool service"]
node_browser_engine["Browser engine"]

node_user -->|"runs commands"| node_cli
node_cli -.->|"starts gateway"| node_sse
node_user -->|"connects UI"| node_sse
node_sse -.->|"routes requests"| node_sse_routes
node_user -->|"submits turns"| node_sse_routes
node_sse_routes -.->|"dispatches turns"| node_runtime_loop
node_runtime_loop -.->|"requests completion"| node_provider
node_provider -.->|"calls model"| node_model_service
node_runtime_loop -.->|"dispatches tools"| node_tool_execution
node_tool_execution -.->|"invokes MCP"| node_mcp
node_mcp -.->|"calls tools"| node_mcp_service
node_sse_routes -->|"handles uploads"| node_attachments
node_sse_routes -->|"uses backend"| node_storage
node_storage -->|"creates backend"| node_sqlite
node_storage -->|"creates backend"| node_postgres
node_storage -.->|"selects workspace"| node_cloud_storage
node_sse_routes -.->|"stores history"| node_transcript
node_memory -->|"reads and writes"| node_storage
node_config -->|"configures providers"| node_provider
node_user -->|"starts talk"| node_realtime_cli
node_realtime_cli -.->|"opens WebSocket"| node_realtime
node_realtime -->|"manages sessions"| node_realtime_manager
node_realtime -->|"uses realtime model"| node_provider
node_scheduler -->|"loads schedules"| node_storage
node_browser -->|"serves tools"| node_browser_server
node_browser_server -->|"uses chat state"| node_browser_context
node_browser_context -->|"tracks tabs"| node_browser_tabs
node_browser -.->|"controls browser"| node_browser_engine

click node_cli "https://github.com/human-plus-machine/monkeybot/blob/develop/cli/src/monkeybot_cli/main.py"
click node_config "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/config/snapshot.py"
click node_sse "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/sse/app.py"
click node_sse_routes "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/sse/routes.py"
click node_realtime "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/realtime/routes.py"
click node_realtime_manager "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/realtime/manager.py"
click node_runtime_loop "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/runtime/loop.py"
click node_provider "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/llm/provider.py"
click node_tool_execution "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/tools/core_tool_executor.py"
click node_mcp "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/mcp/mcp_client.py"
click node_attachments "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/attachments/catalog.py"
click node_memory "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/memory/ingest.py"
click node_storage "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/backends.py"
click node_transcript "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/transcript.py"
click node_scheduler "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/scheduler/engine.py"
click node_realtime_cli "https://github.com/human-plus-machine/monkeybot/blob/develop/cli/src/monkeybot_cli/realtime/session_controller.py"
click node_browser "https://github.com/human-plus-machine/monkeybot/blob/develop/integrations/browser-mcp/src/browser_mcp/app.py"
click node_browser_server "https://github.com/human-plus-machine/monkeybot/blob/develop/integrations/browser-mcp/src/browser_mcp/server.py"
click node_browser_context "https://github.com/human-plus-machine/monkeybot/blob/develop/integrations/browser-mcp/src/browser_mcp/chat_context.py"
click node_browser_tabs "https://github.com/human-plus-machine/monkeybot/blob/develop/integrations/browser-mcp/src/browser_mcp/tabs.py"
click node_sqlite "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/sqlite_backend.py"
click node_postgres "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/postgres.py"
click node_cloud_storage "https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/workspace/factory.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_realtime_cli,node_user,node_browser_engine toneBlue
class node_sse,node_sse_routes,node_realtime,node_realtime_manager toneAmber
class node_config,node_runtime_loop,node_provider,node_tool_execution,node_attachments,node_model_service toneMint
class node_memory,node_storage,node_transcript,node_sqlite,node_postgres,node_cloud_storage toneRose
class node_mcp,node_scheduler,node_browser,node_browser_server,node_browser_context,node_browser_tabs,node_mcp_service toneIndigo
```

## Components

### User entrypoints

- [Agent CLI](https://github.com/human-plus-machine/monkeybot/blob/develop/cli/src/monkeybot_cli/main.py): `cli/src/monkeybot_cli/main.py`
- [Realtime CLI](https://github.com/human-plus-machine/monkeybot/blob/develop/cli/src/monkeybot_cli/realtime/session_controller.py): `cli/src/monkeybot_cli/realtime/session_controller.py`

### Gateway interfaces

- [SSE gateway](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/sse/app.py): `src/monkeybot/gateway/sse/app.py`
- [Session routes](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/sse/routes.py): `src/monkeybot/gateway/sse/routes.py`
- [Realtime routes](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/realtime/routes.py): `src/monkeybot/gateway/realtime/routes.py`
- [Session manager](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/gateway/realtime/manager.py): `src/monkeybot/gateway/realtime/manager.py`

### Agent runtime

- [Runtime config](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/config/snapshot.py): `src/monkeybot/core/config/snapshot.py`
- [Agent turn loop](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/runtime/loop.py): `src/monkeybot/core/runtime/loop.py`
- [Model providers](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/llm/provider.py): `src/monkeybot/core/llm/provider.py`
- [Tool execution](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/tools/core_tool_executor.py): `src/monkeybot/core/tools/core_tool_executor.py`
- [Attachments](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/attachments/catalog.py): `src/monkeybot/core/attachments/catalog.py`

### State and storage

- [Memory subsystem](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/memory/ingest.py): `src/monkeybot/core/memory/ingest.py`
- [Storage factory](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/backends.py): `src/monkeybot/core/persistence/backends.py`
- [Transcript storage](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/transcript.py): `src/monkeybot/core/persistence/transcript.py`
- [SQLite backend](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/sqlite_backend.py): `src/monkeybot/core/persistence/sqlite_backend.py`
- [Postgres backend](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/persistence/postgres.py): `src/monkeybot/core/persistence/postgres.py`
- [Cloud storage](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/workspace/factory.py): `src/monkeybot/core/workspace/factory.py`

### Integrations

- [MCP clients](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/core/mcp/mcp_client.py): `src/monkeybot/core/mcp/mcp_client.py`
- [Scheduled loops](https://github.com/human-plus-machine/monkeybot/blob/develop/src/monkeybot/scheduler/engine.py): `src/monkeybot/scheduler/engine.py`
- [Browser MCP](https://github.com/human-plus-machine/monkeybot/blob/develop/integrations/browser-mcp/src/browser_mcp/app.py): `integrations/browser-mcp/src/browser_mcp/app.py`
- [Browser MCP server](https://github.com/human-plus-machine/monkeybot/blob/develop/integrations/browser-mcp/src/browser_mcp/server.py): `integrations/browser-mcp/src/browser_mcp/server.py`
- [Chat browser state](https://github.com/human-plus-machine/monkeybot/blob/develop/integrations/browser-mcp/src/browser_mcp/chat_context.py): `integrations/browser-mcp/src/browser_mcp/chat_context.py`
- [Browser tabs](https://github.com/human-plus-machine/monkeybot/blob/develop/integrations/browser-mcp/src/browser_mcp/tabs.py): `integrations/browser-mcp/src/browser_mcp/tabs.py`

### Other components

- **User or UI**
- **External model API**
- **MCP tool service**
- **Browser engine**

## Connections

- User or UI → Agent CLI: runs commands (evidence: `README.md`)
- Agent CLI → SSE gateway: starts gateway (evidence: `README.md`)
- User or UI → SSE gateway: connects UI (evidence: `README.md`)
- SSE gateway → Session routes: routes requests
- User or UI → Session routes: submits turns (evidence: `README.md`)
- Session routes → Agent turn loop: dispatches turns
- Agent turn loop → Model providers: requests completion
- Model providers → External model API: calls model
- Agent turn loop → Tool execution: dispatches tools
- Tool execution → MCP clients: invokes MCP (evidence: `src/monkeybot/core/mcp/mcp_client.py`)
- MCP clients → MCP tool service: calls tools
- Session routes → Attachments: handles uploads (evidence: `src/monkeybot/gateway/sse/routes.py`)
- Session routes → Storage factory: uses backend (evidence: `src/monkeybot/gateway/sse/routes.py`)
- Storage factory → SQLite backend: creates backend (evidence: `src/monkeybot/core/persistence/backends.py`)
- Storage factory → Postgres backend: creates backend (evidence: `src/monkeybot/core/persistence/backends.py`)
- Storage factory → Cloud storage: selects workspace
- Session routes → Transcript storage: stores history
- Memory subsystem → Storage factory: reads and writes (evidence: `src/monkeybot/core/memory/ingest.py`)
- Runtime config → Model providers: configures providers (evidence: `src/monkeybot/core/config/snapshot.py`)
- User or UI → Realtime CLI: starts talk (evidence: `README.md`)
- Realtime CLI → Realtime routes: opens WebSocket (evidence: `cli/src/monkeybot_cli/realtime/session_controller.py`)
- Realtime routes → Session manager: manages sessions (evidence: `src/monkeybot/gateway/realtime/routes.py`)
- Realtime routes → Model providers: uses realtime model (evidence: `src/monkeybot/gateway/realtime/routes.py`)
- Scheduled loops → Storage factory: loads schedules (evidence: `src/monkeybot/scheduler/engine.py`)
- Browser MCP → Browser MCP server: serves tools (evidence: `integrations/browser-mcp/src/browser_mcp/server.py`)
- Browser MCP server → Chat browser state: uses chat state
- Chat browser state → Browser tabs: tracks tabs (evidence: `integrations/browser-mcp/src/browser_mcp/chat_context.py`)
- Browser MCP → Browser engine: controls browser
