How nova-liu/nanobot works
1. Repository shape
- nanobot/ is the main Python runtime and package.
- webui/ is a separate TypeScript/React frontend for interactive chat.
- bridge/ is a separate TypeScript WhatsApp bridge service.
- tests/ mirrors the runtime subsystems closely, which is a good clue that the architecture is intentionally modular.
2. Primary runtime entrypoints
- The Python package exposes CLI-style entrypoints for onboarding, chatting, a gateway/websocket mode, and an API server.
- nanobot/__main__.py, nanobot/cli/, and nanobot/api/server.py are the main operational entrances.
- Dockerfile, docker-compose.yml, and entrypoint.sh indicate it is designed to run as a long-lived service, not just a library.
3. Core execution model: one agent loop
- The heart of the system is the agent loop in nanobot/agent/loop.py, backed by runner.py, context.py, and hook.py.
- Incoming messages are normalized into a session context, enriched with memory/skills, then sent to an LLM provider.
- Tool calls, retries, compaction, and lifecycle hooks all happen inside or around this loop rather than in external orchestration code.
4. Session and persistence boundary
- nanobot/session/manager.py owns conversation/session state and history.
- Persistence helpers such as utils/gitstore.py, agent/tools/file_state.py, and the session-related tests suggest local durable storage is a first-class concern.
- The design keeps conversation state separate from channel transport, which is important for sharing one agent across many surfaces.
5. Provider abstraction for model backends
- nanobot/providers/ contains adapters for OpenAI-compatible APIs, Anthropic, Azure OpenAI, GitHub Copilot, and other model backends.
- providers/registry.py selects providers, while providers/openai_responses/ handles OpenAI Responses-specific parsing and conversions.
- This is a clean boundary: the agent loop talks to a provider interface, not to vendor SDKs directly.
6. Tool system as the agent’s action layer
- nanobot/agent/tools/ is a structured tool runtime with a registry, schemas, and base classes.
- Tools cover filesystem, shell, web search/fetch, sandboxing, notebooks, messaging, spawning subagents, cron, MCP, and self/introspection.
- The loop delegates external actions through this tool layer, so tool execution is isolated from message transport and model selection.
7. Skills and prompt composition
- nanobot/skills/ stores reusable skill packages, each with its own SKILL.md and, in some cases, helper scripts.
- nanobot/templates/ contains the prompt scaffolding for agent identity, tool instructions, memory, heartbeat, and subagent behavior.
- Skills are injected as context, not as code plugins, which keeps the runtime lightweight while still extensible.
8. Channel adapters for external chat systems
- nanobot/channels/ defines the channel abstraction and concrete adapters for Slack, Discord, Telegram, Matrix, Feishu, WeCom, WhatsApp, email, WebSocket, and others.
- channels/manager.py and channels/registry.py manage fan-in/fan-out and channel discovery.
- These adapters are the transport boundary: they translate platform-specific events into the unified session/message model, and translate agent output back into platform-specific messages.
9. WebSocket and WebUI path
- The WebUI in webui/ talks to the Python backend through the WebSocket channel and associated API helpers.
- webui/src/hooks/useNanobotStream.ts, webui/src/lib/nanobot-client.ts, and the chat components show that the frontend is a thin client over streamed session updates.
- This path is separate from the traditional chat-app integrations and is optimized for interactive debugging and local development.
10. OpenAI-compatible API boundary
- nanobot/api/server.py exposes an API surface for programmatic use and streaming.
- The README and tests indicate it supports OpenAI-compatible behavior, including SSE-style streaming in newer versions.
- This lets nanobot act both as a standalone agent and as a backend for other tooling.
11. Background services
- nanobot/cron/ schedules recurring tasks and reminders.
- nanobot/heartbeat/ keeps long-running sessions and agent state alive.
- nanobot/bus/ provides an internal event/queue mechanism for moving events between services without coupling them directly to the channel layer.
12. Configuration, security, and runtime controls
- nanobot/config/ handles config loading, paths, and schema validation.
- nanobot/security/network.py and the security-oriented tests suggest network/tool access is constrained intentionally.
- This boundary matters because the agent can execute shell, web, and filesystem actions, so policy and runtime safeguards are part of the architecture rather than an afterthought.
13. Bridge service
- bridge/ is a separate Node/TypeScript service, with its own package and server, likely used to connect WhatsApp to the Python core.
- It sits at the edge of the system rather than inside the main agent runtime.
- Architecturally, this is a transport bridge: external messaging platform on one side, nanobot’s unified message/session model on the other.
14. Operational view
- Typical flow is: channel/API/WebUI input → session manager/context assembly → agent loop → provider call and/or tool execution → streamed response back through the same channel.
- Cron and heartbeat can inject work independently of user messages.
- Memory and skills are not separate services; they are contextual inputs that shape the loop and make the agent persistent without heavy orchestration.
Main entry points: loop.py Agent loop · context.py Context · channels/manager.py Channels · session/manager.py Session mgr
Components 22
Python runtime
Core nanobot agent system, APIs, channels, and services.
- Entrypoints · Main operational starts: package entry, CLI, and API server.
nanobot/__main__.py - CLI · User-facing commands for onboarding, chat, and stream modes.
nanobot/cli/commands.py - API server · Programmatic and streaming backend surface for external clients.
nanobot/api/server.py - Session mgr · Owns conversation state, history, and persistence boundaries.
nanobot/session/manager.py - Agent loop · Central execution loop for turns, retries, compaction, and lifecycle hooks.
nanobot/agent/loop.py - Context · Builds the per-turn context from messages, memory, skills, and metadata.
nanobot/agent/context.py - Runner · Drives loop execution and turn lifecycle.
nanobot/agent/runner.py - Providers · Vendor-neutral model backend adapters and response parsing boundary.
nanobot/providers/registry.py - Tool runtime · Registry and execution layer for filesystem, shell, web, messaging, MCP, and subagent tools.
nanobot/agent/tools/registry.py - Skills · Reusable skill bundles injected as contextual capability, not plugins.
nanobot/skills/README.md - Templates · Prompt fragments for identity, tools, memory, heartbeat, and subagents.
nanobot/templates/AGENTS.md - Channels · Platform adapters for Slack, Discord, Telegram, Matrix, email, WebSocket, and others.
nanobot/channels/manager.py - Event bus · Internal event/queue mechanism connecting services without tight coupling.
nanobot/bus/queue.py - Cron · Recurring task scheduling and reminder execution.
nanobot/cron/service.py - Heartbeat · Keeps long-running sessions and agent state active.
nanobot/heartbeat/service.py - Config · Loads settings, paths, and schema validation for runtime behavior.
nanobot/config/loader.py - Security · Network and tool-access constraints for risky runtime capabilities.
nanobot/security/network.py
Web UI
React client for interactive chat and session streaming.
- Web UI app · Interactive chat application for local or remote use.
webui/src/App.tsx - Stream client · Hook and client layer for streaming session updates from nanobot.
webui/src/hooks/useNanobotStream.ts - Chat shell · Thread, sidebar, composer, and message presentation components.
webui/src/components/thread/ThreadShell.tsx
WhatsApp bridge
Separate TypeScript service for WhatsApp transport integration.
- Bridge server · Separate WhatsApp integration service in TypeScript.
bridge/src/server.ts - WhatsApp adapter · WhatsApp-specific connection and message translation logic.
bridge/src/whatsapp.ts
Connections 22
- Entrypoints → CLI: invokes · Package entrypoint dispatches to CLI modes.
- Entrypoints → API server: starts · Can run the backend API/server mode.
- CLI → Session mgr: opens · CLI commands interact with stored sessions.
- API server → Session mgr: reads/writes · API requests operate on shared session state.
- Session mgr → Context: supplies state · Conversation history and metadata feed context assembly.
- Context → Skills: injects · Skills are loaded into the turn context.
- Context → Templates: renders · Prompt scaffolding shapes the assembled context.
- Context → Security: applies policy · Tool and network constraints are part of context/runtime setup.
- Context → Agent loop: feeds · Prepared context enters the main execution loop.
- Agent loop → Runner: driven by · Runner controls loop execution and lifecycle.
- Agent loop → Providers: calls model · Loop delegates inference to provider adapters.
- Agent loop → Tool runtime: executes actions · Tool calls are routed through the tool runtime.
- Tool runtime → Event bus: emits events · Tools can publish internal events and results.
- Cron → Event bus: schedules work · Recurring jobs inject work into the internal event flow.
- Heartbeat → Event bus: signals · Heartbeat service keeps active sessions alive through events.
- Channels → Session mgr: attaches to · Transport adapters map platform events onto sessions.
- Channels → Agent loop: delivers turns · Normalized inbound messages trigger agent execution.
- Agent loop → Channels: streams output · Agent responses are sent back through the originating transport.
- Web UI app → Stream client: uses · UI composition is driven by the stream client.
- Stream client → Channels: connects via websocket · Frontend consumes the WebSocket-based backend path.
- Bridge server → WhatsApp adapter: wraps · Bridge server uses WhatsApp-specific integration logic.
- Bridge server → Channels: relays messages · Bridge acts as an edge transport into the unified message model.