Nanobot Review: HKU's 4K-Line Personal AI Agent Framework

Originally published on andrew.ooo — visit the original for any updates, code snippets that aged out, or follow-up posts.

TL;DR

nanobot is an open-source, ultra-lightweight personal AI agent from the HKUDS (HKU Data Intelligence Lab) team. It positions itself in the same family as OpenClaw, Claude Code, and Codex — but with a deliberately small, readable core that you can fit in your head in an afternoon.

Key facts:

• 41,700+ GitHub stars as of early May 2026, climbing fast on this week's trending list
• MIT licensed, Python ≥3.11, packaged on PyPI as nanobot-ai
• ~4,000 lines of core code — by community accounts, ~90% of an OpenClaw-style core in a fraction of the size
• 20+ LLM providers: OpenAI, Anthropic, DeepSeek (V4), Kimi (K2.6), Qwen, GLM, MiniMax, Moonshot, Gemini, Mistral, vLLM, Ollama, LM Studio, GitHub Copilot (GPT-5/o-series), OpenRouter, Azure OpenAI, VolcEngine, StepFun, MiMo, Hugging Face
• Channel plugins: Telegram, Discord, Slack, Feishu, WeChat, WeCom, DingTalk, QQ, WhatsApp, Matrix, MS Teams, Email, Web UI, plus an OpenAI-compatible API and WebSocket
• MCP support for tools, resources, and prompts; ships with a built-in ClawHub skill for installable agent skills
• Long-running by design: scheduled tasks, natural-language cron, two-stage memory ("Dream"), atomic session writes, mid-turn follow-ups
• Install paths: uv tool install nanobot-ai, pip install nanobot-ai, Docker, or macOS LaunchAgent
• Honest caveat: surface area is huge for a "tiny" agent — a 4K-line core with 20 providers and 14 channels means most of the bytes live in plugin code, and not every channel is equally polished

If you wanted Claude Code's loop and Codex's CLI vibe, but in a hackable Python repo you can fork on a Sunday and run on your own keys against DeepSeek V4 over Telegram — nanobot is exactly that shape.

Why nanobot is showing up everywhere

Three reasons the trending charts caught it this week.

It compresses an idea everyone wants. "Personal AI agent that runs in chat, has memory, can call tools, and survives a Friday night unattended" is the product behind every shiny demo. The v0.1.5 release notes literally frame the goal that way — memory that doesn't forget, runs that don't crash mid-task, channels that don't drop messages.

It picks great defaults for 2026. DeepSeek V4 and Kimi K2.6 came in within days of release; GitHub Copilot GPT-5/o-series is wired through OAuth; MCP exposes tools, resources, and prompts; the Dream memory system is two-stage. Plus /history, /restart, /status — small things that reveal someone has actually run this for weeks.

The code is studyable. Most agent frameworks pad themselves with abstraction layers. nanobot's contributors describe walking in cold, reading the code top-to-bottom, and shipping their first PR the same week — Kiplangat Korir's Medium write-up hit 21 merged contributions starting from a tool-validation crash they fixed on day one.

What's in the box

The repo layout is unusually clean for an agent framework:

nanobot/
├── nanobot/      # core agent loop, providers, memory, channels
├── bridge/       # protocol bridges (OpenAI-compatible API, WebSocket)
├── webui/        # browser chat UI with i18n and dark mode
├── docs/         # provider/channel guides
├── case/         # example agents and skill templates
├── tests/        # surprisingly thorough for a "lightweight" project
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml

The "research-ready" claim is the differentiator. Most personal-agent projects either ship as a CLI you can't extend (Codex) or as a giant runtime with a hundred-page spec (LangGraph, AutoGen). nanobot lands between those — small enough to read, complete enough to actually use.

Installing it

Three install paths, all working as advertised on a fresh macOS box.

The uv route (recommended for daily use):

uv tool install nanobot-ai
nanobot setup
nanobot start

That gives you the interactive setup wizard — pick a provider (OpenAI, Anthropic, DeepSeek, Kimi, Qwen, etc.), it autocompletes model names, you paste a key, and you're chatting in the terminal in under two minutes.

From PyPI inside an existing venv:

python3 -m venv .venv && source .venv/bin/activate
pip install nanobot-ai
nanobot setup

From source (for hacking):

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

Docker / docker-compose:

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
docker compose up -d

The Dockerfile pins Python 3.13 and runs the agent as a non-root user; logs go to a mounted volume so sessions survive restarts.

macOS LaunchAgent (added 2026-04-25): there's a one-liner that registers nanobot as a LaunchAgent so it auto-starts at login and stays alive across sleeps. This is the path to actually using it as a "personal assistant" in the real sense — wake the laptop, the agent is already running and reachable on Telegram.

Wiring up channels

This is where nanobot earns its weight. The same agent process can be reached through many chat platforms simultaneously, and they share session state.

A minimal nanobot.yaml:

agent:
  name: bumblebee
  model: deepseek-v4
  provider: deepseek

memory:
  backend: dream
  retention_days: 90

channels:
  telegram:
    bot_token: "${TELEGRAM_BOT_TOKEN}"
  discord:
    bot_token: "${DISCORD_BOT_TOKEN}"
    allow_channel_ids: ["1468255584485904618"]
  slack:
    bot_token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
  email:
    imap_host: "imap.gmail.com"
    smtp_host: "smtp.gmail.com"
    address: "[e-mail]"
    password: "${EMAIL_APP_PASSWORD}"

mcp:
  servers:
    - name: filesystem
      command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/notes"]
    - name: github
      command: ["npx", "-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: "${GH_TOKEN}"

Run nanobot start and the same agent is now reachable on Telegram, Discord, Slack, and email — with shared memory, MCP tools, and the OpenAI-compatible API on localhost:8000 for programmatic access.

The Discord channel allow-list (added 2026-04-16) is the quiet hero: you can drop the bot into a server with 200 channels and it'll only respond in the ones you whitelisted. Most multi-channel agent frameworks miss this and end up either spamming or silent.

Building a tool with the SDK

The Agent SDK lands in v0.1.5 as a "production-ready" surface. Here's a concrete example — a tool that reads your andrew.ooo analytics:

from nanobot.sdk import tool, Agent
import httpx

@tool(
    name="get_pageviews",
    description="Get pageviews for a URL on andrew.ooo over the last N days",
    parameters={
        "url": {"type": "string", "description": "Path on andrew.ooo, e.g. /posts/serena-mcp-review"},
        "days": {"type": "integer", "default": 7},
    },
)
async def get_pageviews(url: str, days: int = 7) -> dict:
    async with httpx.AsyncClient() as client:
        r = await client.get(
            "https://api.umami.is/v1/websites/1f0426e9-1184-4032-9fbb-d878972e7cb9/metrics",
            params={"url": url, "startAt": days_ago(days), "endAt": now()},
            headers={"x-umami-api-key": os.environ["UMAMI_API_KEY"]},
        )
    return r.json()

agent = Agent.from_yaml("nanobot.yaml")
agent.register_tool(get_pageviews)
agent.run()

That's the entire surface — decorate a Python function, register it, and your DeepSeek-backed agent on Telegram can now answer "how many pageviews did the Serena post get last week?" with a real number from Umami. No LangChain class hierarchy, no agent graph spec, no separate tool server.

For tools that need an MCP layer (i.e., used by Claude Code or Cursor in addition to your nanobot), the same function works as an MCP server with the nanobot mcp serve command.

The Dream memory system

Most agent frameworks bolt on memory by stuffing everything into the prompt or hand-rolling a vector DB. nanobot's "Dream" memory (renamed and redesigned in v0.1.5) is two-stage:

1. Hot memory — the last N turns plus a compacted summary of older context, kept in the active session.
2. Cold memory — token-budgeted, periodically distilled, stored on disk with atomic writes and auto-repair.

The "Dream learns discovered skills" line in the 2026-04-12 changelog is doing a lot of work: when the agent uses a tool successfully, the pattern is hashed and re-surfaced in similar future contexts. It's not magic — it's a learned skill cache — but it means the agent gets faster at your common workflows over a week, not just within a session.

The memory system has been the most-rewritten subsystem of the project (you can see "redesigned memory system" notes in February 2026). Worth knowing: there's no built-in vector DB. If you want semantic memory beyond Dream's compaction, you'd plug in your own MCP memory server.

Community reactions

The reception is genuinely positive, with the usual caveats people raise for any new agent framework:

• HKU lab pedigree. HKUDS also ships RAG-Anything, the multimodal RAG framework that hit our radar in April, and Vibe-Trading. There's a track record of finishing what they start.
• Jimmy Song's writeup (jimmysong.io/ai/nanobot) called out the ~4,000-line core hitting "over 90% of OpenClaw's core capabilities" — that's the line that put it on the map.
• Bright Data published a tutorial building an AI web scraping agent with nanobot using their MCP server, so third-party MCP integrations work in practice, not just in theory.
• Contributor velocity is real. PRs and issues run hot — the project has 606 open PRs and 298 open issues at the time of writing, with daily merges. The maintainer team keeps pace.
• Skepticism exists. A February 2026 security audit issue flagged "subtle security gaps in agent execution paths and credential handling" — the team responded with hardening commits, but anyone running this with shell-tool access on a real machine should review the sandbox config in v0.1.5+ before pointing it at production credentials.
• Community forks. The "ShibaClaw" fork in the discussions tab is one of several rebrands building on the core — a sign the architecture is genuinely composable.

Honest limitations

Things to know before you commit:

• Surface area is huge for a "tiny" agent. A 4K-line core paired with 20 providers and 14 channels means most of the codebase is plugin glue. If you only care about one provider on one channel, you'll carry a lot of code you don't use.
• WeChat/QQ/DingTalk are first-class; some Western channels are still catching up. The project is clearly developed primarily for the Chinese market — Feishu, WeChat, DingTalk, QQ, and WeCom integrations get more love than Slack/Discord/Teams in the changelog. Slack works fine, but features like thread isolation and mrkdwn fixes were landing as recently as February.
• Memory is not a vector DB. Dream is a compaction + skill-cache system, not semantic search. For "find me everything I've said about Postgres in the last six months," you need to bring your own MCP server.
• Sandbox is opt-in. The shell tool gives the agent real shell access by default. The 2026-04-26 "safer local provider and shell behavior" changelog tightened defaults, but you still need to review disabled_skills and workspace paths before unattended runs.
• No GUI control. Unlike trycua/cua, nanobot doesn't drive desktop GUIs. It's a chat/CLI/API agent with tools — for browser or computer-use tasks you'd pair it with an MCP server like Playwright.
• Documentation lives in the repo. The official docs site at nanobot.wiki exists but lags the changelog; for current behavior the README and docs/ folder are authoritative.

How nanobot compares

A quick triangulation with neighbors we've reviewed:

• vs OpenClaw — OpenClaw is the bigger, more polished personal-agent platform; nanobot is the readable Python alternative if you want to fork instead of configure.
• vs Claude Code — Claude Code is a closed CLI tied to Anthropic. nanobot is a Python framework that runs against any provider, including Claude.
• vs smolagents — smolagents is a code-first agent library you embed; nanobot is an agent runtime you deploy.
• vs trycua/cua — cua is computer-use sandboxes for desktop control; nanobot is chat/tool/MCP and stops at the shell.
• vs LangGraph/AutoGen — those are graph-orchestration frameworks for building agents. nanobot is the agent. Different layer.

If your question is "I want a personal agent I can run unattended on my own keys, reach over Telegram, and modify when something breaks," nanobot is closer to the answer than any of the above.

FAQ

Is nanobot really only ~4,000 lines?
The core agent loop — the part that decides what to do next, calls models, dispatches tools, and manages turns — is in that ballpark. The full repo is much larger because of channel plugins (Telegram, Discord, Slack, etc.), provider adapters, the Dream memory system, the WebUI, and tests. The "ultra-lightweight" claim is about the readable core, not lines-of-code in the install footprint.

Can nanobot run fully offline / on a local model?
Yes. It supports vLLM, Ollama, and LM Studio as providers. With uv tool install nanobot-ai and Ollama running locally, you can have a Llama-3.3 or Qwen 2.5 agent on Telegram with no cloud API key. Channels still need internet, but inference is local.

How does it handle MCP?
nanobot is an MCP client out of the box — it speaks to MCP servers (filesystem, GitHub, Bright Data, Playwright, etc.) and exposes their tools to the LLM. As of v0.1.4, it also lets you mount multiple MCP servers in one config. There's a built-in ClawHub skill for searching and installing public agent skills, which is the easiest way to discover useful MCP servers.

Is it production-ready?
For "personal assistant running on my own machine" — yes, v0.1.5 explicitly targets that. For "customer-facing agent in our SaaS" — read the security history first. The February 2026 audit flagged real issues, the team patched them, and v0.1.5+ ships with sandboxing, but agent-execution security is a live problem space and you should treat any framework giving an LLM shell access with care.

What's the relationship to OpenClaw?
The README explicitly positions nanobot as "in the spirit of OpenClaw, Claude Code, and Codex." It's not a fork — it's a from-scratch Python implementation of a similar agent loop, with a different design priority: readability and hackability over feature breadth.

Which model should I start with?
DeepSeek V4 if cost matters (cheap, fast, surprisingly competent at tool use). Claude Sonnet/Opus if quality matters more than cost. GitHub Copilot GPT-5 if you already have a paid Copilot seat — nanobot supports the OAuth flow to use it without separate keys. Avoid local models for first-time setup; you want to know whether the framework works before you also debug your inference stack.

Bottom line

nanobot is the rare "lightweight" framework that actually delivers on the word. The core is small enough to read, the install is two commands, the channel coverage is broader than anyone else's, and the Dream memory system is a credible attempt at long-running agent state without a vector-DB tax.

If you've been waiting for a Python answer to "give me a personal agent I can fork, run on DeepSeek, and reach over Telegram" — this is it. Star the repo, install with uv tool install nanobot-ai, run the setup wizard, and you'll be talking to your own agent in five minutes.

Repo: github.com/HKUDS/nanobot · Docs: nanobot.wiki · Discord: discord.gg/MnCvHqpUGB