nanobot - Moses Yebei

The Problem

Personal AI assistants such as Clawdbot are enormous (430k+ lines of code), which makes them hard to read, modify, and extend for research. nanobot solves this by delivering the core agent loop, tooling, and multi-channel chat integration in roughly 4,000 lines of Python, so a developer can trace the whole system in an afternoon.

What This Does

nanobot is a lightweight personal AI assistant. The Python core in nanobot/ handles the agent loop (nanobot/agent/loop.py), tool execution (nanobot/agent/tools/), provider abstraction via LiteLLM (nanobot/providers/litellm_provider.py), cron scheduling (nanobot/cron/service.py), session memory (nanobot/session/manager.py), and chat channels for Discord, Telegram, Feishu, DingTalk, and WhatsApp. A separate TypeScript bridge/ package handles WhatsApp transport. The repo also ships skill definitions (nanobot/skills/) and a Dockerfile.

How It Is Wired

Execution starts at nanobot/__main__.py, which routes through nanobot/cli/commands.py into the agent loop's run() (nanobot/agent/loop.py:110), which reaches 67 functions. From there start_all in nanobot/channels/manager.py dispatches outbound messages over the network via channel.send — two hops from the entry point to a socket. The filesystem path is similar: execute → _add_job → _load_store, which reads store_path directly.

Everything routes through nanobot/bus/events.py — 13 modules import it — making it the highest-blast-radius hub; churn there breaks a third of the codebase. _load_store is called from 7 places, _now_ms and ensure_dir from 6 each, so changes to those ripple widely. The module graph resolves 117 import edges with zero circular dependencies, which keeps the architecture navigable.

How To Use It

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

Configuration lives in nanobot/config/schema.py; providers and API keys are resolved there. The Dockerfile builds a container image. The README documents a uv-based install path as well. No CI workflow or lockfile exists, so builds are not reproducible as shipped.

Real-World Use

A developer runs nanobot as a 24/7 assistant: it watches a chat channel, routes messages through the agent loop, calls tools (filesystem, shell, web, cron), and schedules recurring jobs via nanobot/cron/service.py — e.g., a daily market-analysis task that posts results back to Discord or Feishu. The cron store persists to disk through _load_store/_save_store, and session history is kept per-user in nanobot/session/manager.py.

Code Health & Issues

Static analysis found 25 findings (2 high, 23 medium) across 5 kinds. High: deep nesting (max indentation depth 6 in nanobot/bus/queue.py, nanobot/session/manager.py, nanobot/agent/subagent.py) and duplicated 6-line blocks across agent/loop.py, agent/subagent.py, and both provider files. Medium: broad exception handling in 6 spots, high branching density in agent/skills.py, and the bus/events.py hub.

SDLC gaps: no CI workflow, no lockfile beside bridge/package.json, no Docker build gate, no Dependabot, unpinned base image in the Dockerfile, 3 GIFs over 5MB in case/, no non-root USER in the image, and a test suite of 1 file against 52 source files.

The Bottom Line

nanobot is a genuinely small, readable agent core with clean module boundaries and no circular imports — a good base for research or a self-hosted personal assistant. It ships without CI, lockfiles, or meaningful tests, so treat it as a starting point and add those gates before trusting it in production.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

85 files

Python48
Markdown16
TypeScript4
Shell4
JSON2
TOML1

ReactFlaskDocker

Module dependencies

The 10 most depended-upon modules of 52, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_nanobot_bus_events["events"] n1_nanobot_bus_queue["queue"] n2_nanobot_config_schema["schema"] n3_nanobot_agent_tools_base["base"] n4_nanobot_channels_base["base"] n5_nanobot_session_manager["manager"] n6_nanobot_utils_helpers["helpers"] n7_nanobot_agent_tools_registry["registry"] n8_nanobot_cron_service["service"] n9_nanobot_cron_types["types"] n7_nanobot_agent_tools_registry --> n3_nanobot_agent_tools_base n1_nanobot_bus_queue --> n0_nanobot_bus_events n4_nanobot_channels_base --> n0_nanobot_bus_events n4_nanobot_channels_base --> n1_nanobot_bus_queue n8_nanobot_cron_service --> n9_nanobot_cron_types n5_nanobot_session_manager --> n6_nanobot_utils_helpers

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
LowDependencies declared without a lockfile - non-reproducible builds bridge/package.json

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

Commit a lockfile beside the manifesthigh

bridge/package.json

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Add a workflow that builds and tests this repositoryhigh

52 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh

Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

ghcr.io/astral-sh/uv:python3.12-bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Move large binaries to Git LFS or out of the repositorymedium4 occurrences

case/code.gif

4 blobs over 5MB: code.gif 11.7MB, scedule.gif 6.8MB, search.gif 6.0MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Expand the test suite; it cannot cover this codebasemedium

1 test files against 52 source files (ratio 0.019)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.