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?

Benefit	Details
Compact	4,000 lines of clean, readable code – 99% smaller than other agents.
Fast	Minimal footprint means lower RAM/CPU usage and quick startup.
Research‑ready	Modular architecture (skills, tools, channels) makes it easy to extend or modify.
Flexible deployment	Works out‑of‑the‑box with OpenRouter, or any local LLM via vLLM, with a simple config file.
Multi‑channel	Chat over Telegram or WhatsApp, even voice transcription via Groq.
Scheduling	Cron‑style jobs let you run recurring tasks – perfect for reminders or data‑fetching.

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"] }
}

1. Run:

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

Edit the config:

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

Run the agent as usual.

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 * * *"

List jobs:

nanobot cron list

Remove a job:

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!