$ show HKUDS/nanobot
Nanobot is a self-hosted, open-source personal AI assistant framework that operates as a full-stack application. The Python backend provides an agent loop with tool execution, session management, multi-provider LLM orchestration (OpenAI, Anthropic, etc.), and a plugin system for 18+ messaging channels (Telegram, Discord, Slack, WeChat, Feishu, etc.). It exposes a WebSocket-based gateway, an OpenAI-compatible API, and a CLI. Two frontends exist: a rich WebUI built with React/TypeScript/Vite/Tailwind and a terminal TUI built with Bun/OpenTUI. The architecture is event-driven via a message bus, with decoupled channel adapters, provider abstraction, and a config system supporting hot-reload. It includes security features like workspace sandboxing, credential redaction, and SSRF protection. The codebase is extensively tested (hundreds of unit/integration tests) and demonstrates strong engineering practices with clean abstractions, though its large dependency surface and multiple frontends introduce some maintenance surface area.
The LLM identified 6 files worth highlighting for reuse:
Implements a composite hook chain for agent turn lifecycle events. Factories create hooks from config, and the chain supports progress hooks, event sinks, and file edit activity tracking. The pattern is self-contained and could be extracted for any event-driven pipeline requiring ordered, composable callbacks.
Provides a reusable validation framework for channel setup. Exposes functions like `check`, `http_post`, `payload`, and `status_from_checks` that allow channel plugins to define validation steps declaratively. The pattern is generic enough to validate any external service connection and is not tied to nanobot internals.
Decodes base64 data URLs to file objects with configurable size limits and MIME-type-based extension overrides. Self-contained function with no internal dependencies, suitable for reuse in any Python project needing safe data URL to file conversion.
Implements workspace path resolution with boundary enforcement, symlink protection, and throttling of repeated violations. The `resolve_allowed_path` function and `WorkspaceBoundaryError` exception form a reusable access control layer that can be adapted for any application needing filesystem sandboxing.
Handles initial authentication for the WebUI: stores secrets in localStorage, consumes URL parameters, and derives WebSocket URLs. The pattern of one-time token consumption with fallback to stored credentials is clean and could be reused in any web client needing secure initial connection setup.
Manages draft messages with in-memory and localStorage persistence, including paste/image placeholders and size limits. The pattern of combining ephemeral state with local storage for crash recovery is well-implemented and could be extracted for any text input component needing draft preservation.