nanobot: 4,000‑Line Python AI Assistant Built in Minutes

What is nanobot?

nanobot is an ultra‑lightweight personal AI assistant inspired by Clawdbot, but with a fraction of the code‑base – ~4,000 lines versus Clawdbot’s 430k+. Powered by open‑source tools and Python, it gives you a ready‑to‑go chatbot that runs on your laptop or a cloud VM in minutes.

Why nanobot?

Architecture Overview

nanobot/
├─ agent/          # Core loop, memory, skills
├─ skills/         # Built‑in capabilities (github, weather, tmux…)
├─ channels/       # Telegram/WhatsApp integration
├─ cron/           # Scheduler for recurring tasks
├─ bus/            # Message routing
├─ providers/      # OpenAI, OpenRouter, Groq, vLLM
├─ config/         # CLI helpers
└─ cli/            # Command‑line entry points

A skill is a self‑contained module that can be invoked by a prompt. The agent loop sends the user query to the LLM, receives a tool‑invocation token, and hands it to the appropriate skill. Memory is persisted across sessions in a simple SQLite store.

Installing nanobot

1. From PyPI (stable, quick)

pip install nanobot-ai

2. From source (latest features)

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .         # editable for development

3. With UV (fast installation)

uv tool install nanobot-ai

Quick Start Guide

Prepare a minimal config file at ~/.nanobot/config.json:

{
  "providers": {
    "openrouter": { "apiKey": "sk-or-xxxx" }
  },
  "agents": {
    "defaults": { "model": "anthropic/claude-opus-4-5" }
  }
}

Launch the chatbot:

nanobot onboard          # initializes config & workspace
nanobot agent -m "What is 2+2?"

Interactive mode:

nanobot agent            # starts a REPL

Chat over Telegram

1. Create a bot via @BotFather and copy the token.
2. Add the token and your user ID to config.json:

"channels": {
  "telegram": { "enabled": true, "token": "YOUR_BOT_TOKEN", "allowFrom": ["YOUR_USER_ID"] }
}

nanobot gateway

Now every message you send to the bot appears in the CLI and vice‑versa.

Local LLM Deployment with vLLM

# Start a local Llama‑3 model
vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000

"providers": {
  "vllm": { "apiKey": "dummy", "apiBase": "http://localhost:8000/v1" }
},
"agents": { "defaults": { "model": "meta-llama/Llama-3.1-8B-Instruct" } }

Docker‑Friendly Setup

# Build the image
docker build -t nanobot .
# One‑time onboarding
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard
# Run the gateway
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

Persisting ~/.nanobot ensures your API keys and workspace survive container restarts.

Scheduled Tasks (Cron)

Add a daily greeting:

nanobot cron add --name "daily" --message "Good morning!" --cron "0 9 * * *"

nanobot cron list

nanobot cron remove <job_id>

Extending nanobot

1. Create a new directory in skills/.
2. Add a tool.py implementing class Tool: with name, description, and run().
3. Register the skill in the skills/__init__.py scanner.
4. Restart nanobot gateway – the new skill is now available.

All skills are pure Python, making experimentation trivial.

Contributing

The goal is a minimal, understandable code base. Feel free to:

• Add new skills (weather, news, GitHub search, etc.)
• Implement voice transcription via Groq Whisper
• Expand multi‑modal support (images, voice)
• Improve reasoning and planning capabilities
• Add more channel integrations (Discord, Slack, email)

Pull requests are welcome – just follow the existing style and add tests.

In Summary

• nanobot delivers a fully‑functional personal AI assistant in a 4,000‑line Python repo.
• It runs locally or in Docker, interfaces with any OpenAI‑compatible LLM, and connects to Telegram/WhatsApp.
• The modular design lets you add custom skills, schedule tasks, and even switch to local models.
• Whether you’re a researcher wanting a clean research‑ready agent, a developer looking to prototype quickly, or a hobbyist curious about building an AI assistant, nanobot gives you everything you need with minimal friction.

Happy hacking!