nanobot/README.md

nanobot: Your Lightweight Personal AI Assistant

🐈 nanobot is an ultra-lightweight personal AI assistant inspired by Clawdbot

⚡️ Delivers core agent functionality in just ~4,000 lines of code — 99% smaller than Clawdbot's 430k+ lines.

📢 News

• 2025-02-01 🎉 nanobot launched! Welcome to try 🐈 nanobot!

Key Features of nanobot:

⚡️ Ultra-Lightweight: At just ~4,000 lines of code, nanobot is 99% smaller than comparable AI assistants while delivering full functionality.

🔬 Research-Ready: Clean, readable architecture makes it perfect for researchers and developers who need to understand, modify, or extend the codebase.

⚡️ Lightning Fast: Minimal footprint means faster startup, lower resource usage, and quicker iteration cycles.

🏗️ Architecture

✨ Features

🔍 Web Search	💻 Code & Files	📅 Scheduled Tasks	🧠 Memory
Search real-time info	Read, write, execute	Cron jobs & reminders	Remember context

📦 Install

Install from PyPi

pip install nanobot-ai

Install from source (recommended for development)

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

🚀 Quick Start

Tip

Set your API key in ~/.nanobot/config.json. Get one at OpenRouter.

1. Initialize

nanobot onboard

2. Configure (~/.nanobot/config.json)

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  }
}

3. Chat

nanobot agent -m "What is 2+2?"

That's it! You have a working AI assistant in 2 minutes.

💬 Chat Apps

Talk to your nanobot through Telegram or WhatsApp — anytime, anywhere.

Channel	Setup
Telegram	Easy (just a token)
WhatsApp	Medium (scan QR)

Telegram (Recommended)

1. Create a bot

• Open Telegram, search @BotFather
• Send /newbot, follow prompts
• Copy the token

2. Configure

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

Get your user ID from @userinfobot on Telegram.

3. Run

nanobot gateway

WhatsApp

Requires Node.js ≥18.

1. Link device

nanobot channels login
# Scan QR with WhatsApp → Settings → Linked Devices

2. Configure

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}

3. Run (two terminals)

# Terminal 1
nanobot channels login

# Terminal 2
nanobot gateway

⚙️ Configuration

Full config example

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABC...",
      "allowFrom": ["123456789"]
    },
    "whatsapp": {
      "enabled": false
    }
  },
  "tools": {
    "web": {
      "search": {
        "apiKey": "BSA..."
      }
    }
  }
}

API Keys:

• OpenRouter: https://openrouter.ai/keys
• Brave Search (optional): https://brave.com/search/api/

CLI Reference

Command	Description
nanobot onboard	Initialize config & workspace
nanobot agent -m "..."	Chat with the agent
nanobot agent	Interactive chat mode
nanobot gateway	Start the gateway
nanobot status	Show status
nanobot channels login	Link WhatsApp (scan QR)
nanobot channels status	Show channel status

Scheduled Tasks (Cron)

# Add a job
nanobot cron add --name "daily" --message "Good morning!" --cron "0 9 * * *"
nanobot cron add --name "hourly" --message "Check status" --every 3600

# List jobs
nanobot cron list

# Remove a job
nanobot cron remove <job_id>

📁 Project Structure

nanobot/
├── agent/          # 🧠 Core agent logic
│   ├── loop.py     #    Agent loop (LLM ↔ tool execution)
│   ├── context.py  #    Prompt builder
│   ├── memory.py   #    Persistent memory
│   ├── skills.py   #    Skills loader
│   └── tools/      #    Built-in tools
├── skills/         # 🎯 Bundled skills (github, weather, tmux...)
├── channels/       # 📱 Telegram, WhatsApp
├── bus/            # 🚌 Message routing
├── cron/           # ⏰ Scheduled tasks
├── providers/      # 🤖 LLM providers (OpenRouter, etc.)
├── session/        # 💬 Conversation sessions
├── config/         # ⚙️ Configuration
└── cli/            # 🖥️ Commands

🗺️ Roadmap

• Multi-modal — See and hear (images, voice, video)
• Long-term memory — Never forget important context
• Better reasoning — Multi-step planning and reflection
• More integrations — Discord, Slack, email, calendar
• Self-improvement — Learn from feedback and mistakes

Want to help? Pick an item and open a PR!

🤝 Contribute

PRs welcome! The codebase is intentionally small and readable.