HKUDS/nanobot

⭐ 42,124  ·  Python  ·  GitHub Repo

"🐈 nanobot: The Ultra-Lightweight Personal AI Agent"

ai ai-agent ai-agents anthropic chatgpt claude claude-code codex

1-Sentence Summary

The ultra-lightweight, open-source personal AI agent that runs persistently across any chat platform with minimal overhead.

🔥 Key Capabilities & USP

• Multi-Channel Ubiquity: Integrates with 10+ platforms (Feishu, Discord, Slack, Teams, Telegram, WeChat, QQ, WebSocket, WebUI) out of the box. Solves the pain of maintaining separate bots for each communication tool your team or community uses.
• Universal LLM Agnosticism: Supports every major provider (OpenAI, Anthropic/Claude, DeepSeek, Gemini, Ollama, LM Studio, GitHub Copilot, and more). Eliminates vendor lock-in and lets you hot-swap models based on cost, latency, or capability needs.
• Dream Two-Stage Memory System: Implements token-based memory with context compaction and auto-repair for truly long-running conversations. Solves the "agent forgets everything after 10 messages" problem that plagues most lightweight agents.
• MCP (Model Context Protocol) Native Support: Exposes MCP resources and prompts as tools, enabling integration with the growing MCP ecosystem. Keeps your agent extensible without forking the core code.
• Production-Ready Deployment Paths: Includes an interactive setup wizard, cron reminders, macOS LaunchAgent auto-start, and sandboxed shell execution. Solves the "works on my machine" gap by providing a clear path from local dev to always-on agent.

USP: nanobot is the only agent that combines ultra-lightweight code (readable, hackable core loop) with production-grade multi-channel support and a sophisticated memory system—all under 5MB of Python.

Technical Architecture

Component	Technology / Approach
Language	Python ≥3.11
LLM SDKs	Native OpenAI & Anthropic SDKs (no litellm abstraction layer)
Agent Core	Composable lifecycle with hooks, agent runner, unified channel login CLI
Streaming	SSE streaming for OpenAI-compatible API, WebSocket multi-chat multiplexing
Persistence	Session persistence with cross-channel session unification
Plugin System	Modular commands and skills via plugin architecture
Security	Sandboxed shell execution, production-ready input sanitization

The architecture prioritizes simplicity and readability over abstraction. The core agent loop is intentionally small, making it easy to understand, debug, and extend. Native SDK usage means fewer dependencies and faster response times compared to meta-frameworks.

Quick Start Guide

# Install nanobot
pip install nanobot

# Run the interactive setup wizard
nanobot init

# Start the agent
nanobot run

# Or specify a channel directly
nanobot run --channel telegram

Setup Logic: After installation, run nanobot init to configure your LLM provider (e.g., OpenAI API key) and desired channels. The wizard auto-detects environment variables and guides you through OAuth setup for platforms like Slack and Discord. Once configured, nanobot run starts the agent with persistent memory and multi-channel support.

Pros, Cons & Use Cases

Pros

• Truly lightweight: Minimal dependencies, fast install, low memory footprint (~50MB RAM idle)
• Multi-channel by design: Not an afterthought—channels are first-class citizens
• Active development: Frequent releases (weekly), responsive maintainers, growing community
• MIT license: Free for personal and commercial use, no restrictions
• Excellent documentation: README is comprehensive with architecture diagrams and configuration examples

Cons

• Python ≥3.11 required: May exclude users on older Python versions or legacy systems
• Young project: First release in early 2026; some features (WebUI) are still maturing
• Configuration complexity: Setting up multiple channels requires individual OAuth credentials and platform-specific setup
• No mobile client: Relies on existing chat apps for mobile access (e.g., Telegram, WeChat)

Who should NOT use this?

• Enterprise teams needing RBAC, audit logs, and compliance features: nanobot is designed for personal/small-team use, not enterprise governance
• Users on Python ❤️.11: The codebase uses modern Python features and won't run on older versions
• Those wanting a no-code AI agent: nanobot requires terminal access and basic configuration; it's developer-first
• Teams needing a centralized, managed agent service: This is a self-hosted tool, not a SaaS product

Ideal Use Cases

• Personal productivity assistant: A persistent agent that follows you across Telegram, Slack, and Discord to manage tasks, answer questions, and run commands
• Open-source alternative to Claude Code/Codex: For developers who want a customizable, self-hosted coding assistant without vendor lock-in
• Community bot: Deploy a single agent across your community's Discord, Telegram, and Feishu channels with unified memory and context
• Research assistant: Run long-term experiments where the agent maintains context over days or weeks, with automatic memory compaction
• Home automation hub: Connect nanobot to local LLMs (via Ollama) and MCP servers to control smart home devices through chat

Community & Activity

With 42,124 stars and counting, nanobot has clearly struck a nerve in the AI agent community. The project is under active development (last updated May 2026) with a steady cadence of releases and improvements. The maintainers are highly responsive on Discord, WeChat, and Feishu, and the GitHub Issues section shows thoughtful discussions and quick bug fixes.

The community is growing rapidly, with contributors adding new channel integrations, MCP server support, and plugin extensions. The project's momentum suggests it's quickly becoming the go-to open-source choice for personal AI agents—much like how Homebrew became the standard for macOS package management. If you're building with AI agents, this is a project worth watching (and starring).