The Problem

Personal AI assistants are typically monolithic—Clawdbot, the project this forks, runs 430k+ lines of code. That scale makes them hard to audit, hard to modify, and impractical for researchers or individuals who want a self-hosted agent without the operational overhead. Nanobot targets that gap: a functional agent loop, tool system, and multi-channel messaging support in roughly 3,500 lines of Python.

What This Does

Nanobot is a Python-based agent runtime with a plugin-style architecture. The core loop lives in nanobot/agent/loop.py, with a tool registry (nanobot/agent/tools/registry.py) that dispatches to filesystem, shell, web, cron, and message tools. A provider abstraction (nanobot/providers/) supports multiple LLM backends—LiteLLM is the default, with DeepSeek, Qwen, and Moonshot/Kimi added recently. Scheduled tasks are handled by a cron service (nanobot/cron/service.py), and memory persistence is managed through nanobot/agent/memory.py.

The repo also includes a TypeScript bridge (bridge/src/index.ts, bridge/src/server.ts) for WhatsApp integration, plus channel adapters for Telegram, Discord, Feishu, and DingTalk (nanobot/channels/). The workspace/ directory contains agent configuration files—AGENTS.md, SOUL.md, TOOLS.md, USER.md, and a memory/ folder—that define the agent's behavior and persistent state.

How To Use It

Setup: The project installs via pip install -e . from source or with uv. A Dockerfile is present for containerized deployment. The bridge/ directory has its own package.json for the TypeScript WhatsApp bridge, installed separately with npm.

Configuration: LLM provider credentials and channel tokens are configured through environment variables or a config file loaded by nanobot/config/loader.py. The exact variable names are not documented in the README excerpt; check nanobot/config/schema.py for the expected fields. The workspace/ files are runtime configuration, not setup-time config.

Running it: The Python entry point is nanobot/main.py, invoked as python -m nanobot. The Dockerfile provides an alternative deployment path.

git clone https://github.com/HKUDS/nanobot.git cd nanobot pip install -e . configure provider credentials, then: python -m nanobot

The README documents pip install -e . and uv installation; the runtime command is inferred from main.py.

Real-World Use

A solo developer could run nanobot as a personal ops assistant: the cron service schedules daily market checks (nanobot/skills/cron/SKILL.md), the shell tool executes maintenance scripts, and the Telegram channel surfaces results to a phone. The skill system (nanobot/skills/) lets you add domain-specific behaviors—weather, GitHub, tmux, summarization—as markdown SKILL.md files without touching the core loop. For a research lab, the clean provider abstraction makes swapping LLM backends a two-step change.

Code Health & Issues

Med - No CI/CD pipeline: No .github/ or CI config detected. No automated test gate on commits; tests/ has only two files (testdocker.sh, testtool_validation.py), so the test surface is thin. Low - Missing lockfile: bridge/package.json declares dependencies without a lockfile, so npm builds are not reproducible. The Python side uses pyproject.toml without a pinned lock either. Low - Security posture: SECURITY.md exists, which is good, but the shell tool (nanobot/agent/tools/shell.py) gives the agent arbitrary command execution. That's the intended design, but it means the agent's prompt is a security boundary—worth acknowledging before deployment. Low - Docs quality: Three doc files exist, but the README leans heavily on feature marketing (animated GIFs, community badges) rather than operational details like env var names or config schema. workspace/TOOLS.md and workspace/AGENTS.md are the real behavioral docs.

The Bottom Line

Nanobot is a genuinely lightweight agent runtime with a sensible modular design and an unusually small code footprint. It's better suited to researchers, tinkerers, and self-hosters who value auditability over feature completeness than to teams needing a production SLA. The missing CI and thin test suite are the main risks; the codebase itself appears clean and well-factored.