How human-plus-machine/monkeybot works
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: sse/routes.py Session routes · backends.py Storage factory · provider.py Model providers · realtime/routes.py Realtime routes
Components 27
User entrypoints
- Agent CLI
cli/src/monkeybot_cli/main.py - Realtime CLI
cli/src/monkeybot_cli/realtime/session_controller.py
Gateway interfaces
- SSE gateway
src/monkeybot/gateway/sse/app.py - Session routes
src/monkeybot/gateway/sse/routes.py - Realtime routes
src/monkeybot/gateway/realtime/routes.py - Session manager
src/monkeybot/gateway/realtime/manager.py
Agent runtime
- Runtime config
src/monkeybot/core/config/snapshot.py - Agent turn loop
src/monkeybot/core/runtime/loop.py - Model providers
src/monkeybot/core/llm/provider.py - Tool execution
src/monkeybot/core/tools/core_tool_executor.py - Attachments
src/monkeybot/core/attachments/catalog.py
State and storage
- Memory subsystem
src/monkeybot/core/memory/ingest.py - Storage factory
src/monkeybot/core/persistence/backends.py - Transcript storage
src/monkeybot/core/persistence/transcript.py - SQLite backend
src/monkeybot/core/persistence/sqlite_backend.py - Postgres backend
src/monkeybot/core/persistence/postgres.py - Cloud storage
src/monkeybot/core/workspace/factory.py
Integrations
- MCP clients
src/monkeybot/core/mcp/mcp_client.py - Scheduled loops
src/monkeybot/scheduler/engine.py - Browser MCP
integrations/browser-mcp/src/browser_mcp/app.py - Browser MCP server
integrations/browser-mcp/src/browser_mcp/server.py - Chat browser state
integrations/browser-mcp/src/browser_mcp/chat_context.py - Browser tabs
integrations/browser-mcp/src/browser_mcp/tabs.py
Other components
- User or UI
- External model API
- MCP tool service
- Browser engine
Connections 28
- User or UI → Agent CLI: runs commands
README.md - Agent CLI → SSE gateway: starts gateway
README.md - User or UI → SSE gateway: connects UI
README.md - SSE gateway → Session routes: routes requests
- User or UI → Session routes: submits turns
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
src/monkeybot/core/mcp/mcp_client.py - MCP clients → MCP tool service: calls tools
- Session routes → Attachments: handles uploads
src/monkeybot/gateway/sse/routes.py - Session routes → Storage factory: uses backend
src/monkeybot/gateway/sse/routes.py - Storage factory → SQLite backend: creates backend
src/monkeybot/core/persistence/backends.py - Storage factory → Postgres backend: creates backend
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
src/monkeybot/core/memory/ingest.py - Runtime config → Model providers: configures providers
src/monkeybot/core/config/snapshot.py - User or UI → Realtime CLI: starts talk
README.md - Realtime CLI → Realtime routes: opens WebSocket
cli/src/monkeybot_cli/realtime/session_controller.py - Realtime routes → Session manager: manages sessions
src/monkeybot/gateway/realtime/routes.py - Realtime routes → Model providers: uses realtime model
src/monkeybot/gateway/realtime/routes.py - Scheduled loops → Storage factory: loads schedules
src/monkeybot/scheduler/engine.py - Browser MCP → Browser MCP server: serves tools
integrations/browser-mcp/src/browser_mcp/server.py - Browser MCP server → Chat browser state: uses chat state
- Chat browser state → Browser tabs: tracks tabs
integrations/browser-mcp/src/browser_mcp/chat_context.py - Browser MCP → Browser engine: controls browser