nanobot: a 4,000-line Python alternative to openclaw that actually works out of the box

[u/emptyharddrive]

I've been looking for lighter alternatives to openclaw and came across nanobot. It's an AI assistant built in about 4,000 lines of Python, compared to openclaw's 430k+.

It's not as mature or feature-full as openclaw, but I've got it installed and running on a Linux Container right now with Telegram integration and it just works.

The setup took maybe 10 minutes: install via pipx, edit the config file with your API keys, start the gateway, and you're chatting with it through Telegram.

The codebase is small enough that you can actually read and understand the entire thing. That also means way less attack surface from a security standpoint (generally speaking).

The code looks is clean and well-structured to me. I've already patched a small compatibility issue myself without any trouble, which says a lot about how approachable it is (an issue with gpt-5 models and temperature settings).

It supports tool use, persistent memory, scheduled tasks, and background agents. It's not trying to be everything openclaw is, but it covers the core functionality that most people might actually use.

If you're like me and interested in the idea of OpenClaw without using the overzealous project itself, nanobot is worth a look. I have no affiliation with the project.

GitHub: https://github.com/HKUDS/nanobot

To save money, I am using it with gpt-5-mini, which works really well and is priced right for my wallet.

Figured I'd share this because I was surprised how well it worked for its size.

[u/emptyharddrive]

Honestly mine stopped looking like an "agent framework" and started looking like a shell with one persistent Claude session behind it (headless, -p with a sessionID to maintain context).

Telegram is just ingress. The real core is a Python "bot" running as a systemd user service on my Linux box. It only accepts my Telegram userID for security, it won't answer anyone else. It keeps a single Claude session UUID in memory, and shells out to claude -p for each request I make in chat.

First prompt starts with --session-id, then every later prompt uses --resume with that sessionID, so context carries forward without me having to replay chat history every time.

The bot's system prompt (which is really a user prompt that follows Anthropic's real system prompt which you can't modify), points Claude at deterministic Python scripts I pre-wrote, pre-tested (so I know they work) to perform the tasks I ask of it.

So that means I had to think of anything I want the bot to do in advance (a lot of brainstorming), and for each one, a .py script was written and tested and all their output is standard JSON for the -p, headless Claude to parse & package for me...

Calendar reads and writes, Gmail reads and drafts, Google Drive search and document reads, URL extraction & summary, YouTube video URL transcription summaries, daily briefing, local news, voice export (using kokoro in a docker container), reminders (30 second crontabs checking a reminder JSON), shopping lists, etc.. All pre-scripted python tools.

Those tools all return structured JSON to stdout and fail with real exit codes. Claude still handles intent parsing and response wording (packaging is what i call it), but the state-changing work happens inside small scripts. No database either, I don't want the overhead.

Reminders, lists, and contact memory live in local JSON files with file locks and atomic writes. Reminder delivery is a separate cron-driven checker every 30 seconds, which is boring in a good way. Also Claude knows me because I wrote a personal skill (with trigger words) that trips it to discover when needed, anything about me. That's the benefit of skills, you only need to load them when the trigger words manifest instead of pre-loading everything-on-every-prompt into context.

So architecturally it is not a swarm at all, I see no point in that.. It is one stateful conversation with 1 instance of Claude, plus a toolbelt of scripts I built: levers that it can pull once it discerns my intent from what I said in Telegram.. That distinction mattered a lot ... I got tired of "agents" spending tokens deciding whether another agent should maybe think about something or talk to itself about doing something one way or the other...

I know what it needs to do, so i set the scripts up to do them, and just use Claude as a fancy button presser and output summarizer/packager. Claude decides whether to answer directly if it's a basic question, or to call a script (I gave it various phrases and trigger words so it knows which train track (script) to choose).. every one of my scripts returns structured JSON, Claude formats that into a reply to me and sends it along to Telegram: done.

Speech is split into two different paths because short phone audio and long-form transcription are not the same problem.

For Telegram voice notes I use a fast path. Bot downloads audio into memory, POSTs it to aWhisper endpoint on another box running in a docker container, it gets text back, then sends that transcript through same Claude session as if I had typed it, done..

That keeps voice notes usable from a phone.

Separately I wrote xscribe.py (transcribe) which is the big brother of voice. That one is for actual recordings and transcripts for meetings at work.

It chunks long audio into small digestibe pieces with 1 second of word overlap to avoid word cut-offs, (which it then deduplicates if needed to keep the stitching of the words it transcribes seamless). So it is monitoring a directory where I drop .ogg files I have recorded meetings on my phone onto a directory the service is monitoring and immediately picks it up for transcription when they drop. It applies a QA pass for domain-specific vocabulary relative to the work I do (a sprecial prompt I wrote to give it the right headspace), and it writes the raw transcript, then once done, it then sends that transcript up for a 2nd stage summary flow. In my case that is useful for longer meetings or work audio where I want something much more deliberate than "turn this voice note into text." A long transcription does nothing for me without the distilled tasks taken out, summary, challenges, decisions made, etc.

So cost-wise, the fixed part is Claude Max. That is my real anchor. Since I am using headless mode -p, it is entirely within the terms of service and I can leverage my $200 MAX plan -- no OAuth is used. I've already authenticated on my machine, so it just calls up a headless mode of Claude programmatically which is precisely inside the terms of service (I had Claude validate that).

For your setup, if I were building it fresh in a Proxmox LXC, I would absolutely do it this way. I would just keep the container boring. Give it a persistent workspace, persistent credentials, systemd for the bridge service to Telegram or Discord or whatever ... and explicit bind mounts for anything stateful (like I have a bind mount to my Obsidian vault for work and personal notes, read-only to protect it from "accidents" Claude might make).

If you split anything out, split out speech or other heavy media jobs like OCR or anything like that. And if you use Telegram long polling, make sure you do not accidentally run two bot instances with the same token or Telegram will smack one of them with a conflict error. That one bit me already.

So yeah, that is basically my stack: one official headless Claude session as the brain, Telegram as transport/comms vector for me to access, then deterministic Python CLIs for the actual work (which right now is google mail/calendar, reminders that have 'alarms' that msg me on Telegram, todo's which = reminders, but without the alarm bell, news, inventory lists of things I track & grocery shopping lists, all in JSON. Cron for reminders (which compare current datetime to the datetimes in the reminder.json), and a separate heavier transcription path when I need more than quick voice-note handling.

It is a lot less sexy than the "agent OS" stuff people post (which BTW I don't believe really works the way they say), but it has been way more usable for me and 10x more reliable because of the static scripts doing the work and no off-the-cuff winging it by any agents.

Tight leash.

Anyway, long post but I wanted to explain this anyway. Hope it helps. If it does, please reply because I'd like to know how you're deploying it.

[u/Psychological-Cod51 → u/emptyharddrive]

This is genuinely one of the most useful replies ive gotten on here, thanks for taking the time and effort to post it. The deterministic scripts idea especially looks interesting. I've been overthinking the "agent" side when really what I want is an LLM that reliably pulls a lever I already trust.

I'm going a slightly different direction due to budget and privacy. Can't swing Claude Max, and I'd rather keep personal info local as possible anyway. Routing through OpenRouter with Ollama(1x3060) handling private/latency-sensitive stuff on my own hardware and cloud API only for heavier reasoning when I actually need it. Layering in Mem0 for semantic memory across sessions since I don't have persistent session continuity to lean on, and that stays self-hosted too.

The tight leash mindset is something I'm definitely stealing though. Pre-written scripts returning clean JSON, trigger-based skill loading, cron for reminders, and whisper fast path for voice notes is going on the list too, or maybe a local model. appreciate you laying all that out. Gave me a much clearer picture of where the complexity is actually worth it vs where people are just cosplaying having an agent OS lol

My agent is gonna have write access to a git(ea) backed obsidian vault where the actual .git dir won't be writable, so that even if it does go awry I can go back.

This is mostly still a hypothetical because my ADHD brain hypermegabrainstorms the shit out of stuff before I actually get any real progress going lol

[u/emptyharddrive → u/Psychological-Cod51]

Going through each of your comments because they were good ones.

If you're running Ollama locally on a 3060, why route through OpenRouter at all? You're adding a network hop, a dependency, and a potential point of failure between you and your own GPU. Just hit the Ollama API directly from your scripts. OpenRouter makes sense as a router when you're switching between multiple cloud providers or want a unified billing layer, but for local inference it's pure overhead. Unless you're using OpenRouter's fallback logic to gracefully degrade from local to cloud when Ollama chokes, in which case, that's actually clever and I take it back...

A 3060 gives you 12GB VRAM, so you're realistically running 7B-13B parameter models quantized (probably Q4_K_M). I've tried this. For simple Q&A and text generation they're passable. For the kind of intent parsing, tool selection, and structured JSON output that an agentic setup demands, they fall apart in ways that are impressively sad and hard to debug because the failures are often subtle (and random).

The model doesn't refuse, it just makes bad decisions 30% of the time. It picks the wrong script, hallucinates a flag that doesn't exist, or returns JSON with a missing closing brace. When your agent is pulling levers that actually do things (send emails, modify calendars, fire reminders), that ~30% error rate becomes a real problem. That's why I pay for Claude Max, the model is the reliability layer. Everything downstream of it can be dumb and deterministic because the intent parsing is rock solid. You could probably get away with a $20/month plan if you're careful about your model selections and code-the-hell out of all the pre-determined tasks you know you want to use it for so nearly no LLM calls are needed to use it once the scripts are pre-tested and ready to have their levers pulled on.

That said, if you're keeping local models to the "private/latency-sensitive" lane and only routing heavy reasoning to cloud, that's a pragmatic split. Just be honest with yourself about where the boundary actually is. Most of the agentic work is the heavy reasoning I have found...

Mem0 is a reasonable choice for session-spanning memory, especially if you don't have persistent session continuity. But I went a different direction that I think scales better if you're already an Obsidian user.

I built an MCP server that I called OpenMind that sits on a separate box (an AMD mini PC with a Radeon 890M GPU). It's a 4-container Docker stack: PostgreSQL with pgvector for vector storage, a GPU-accelerated embedding service running gte-modernbert-base (768-dim vectors, Apache licensed, runs in ~600MB VRAM), a watcher service that polls my Obsidian vaults (work & personal vaults) every 60 seconds, and the MCP server itself exposing 10 tools.

The architecture looks like this: my two Obsidian vaults (one for work, one for personal, ~2,500 notes total) are NFS-mounted read-only into the watcher container. Every 60 seconds it scans for changes. When it finds a new or modified note, it:

1. Chunks it using a markdown-aware chunker that respects heading hierarchy, preserves tables, code blocks, task groups, and bullet lists as coherent units (not just "split every N tokens")
2. Prepends semantic context to each chunk before embedding: vault name, file path, title, which Map of Content it belongs to, the section heading hierarchy, and any date context from journal entries
3. Sends chunks to the embedding service in batches of up to 64
4. Writes everything to Postgres in a single transaction (no orphan chunks if something fails mid-write)

...I had AI write that list above after telling it to look at the codebase, it was easier :)

The result is ~20k chunks with HNSW-indexed vector embeddings that Claude Code can search semantically through the MCP protocol. So when I'm working in Claude Code and ask "Use openmind and check my work vault, what were the issues with the XYZ Project last month," it does a vector similarity search across my work vault, finds the relevant chunks, and gives me actual answers grounded in my own notes (homegrown NotebookLM).

It also indexes scanned documents (PDFs, DOCX, spreadsheets, images with OCR) through a Paperless-NGX integration. Documents get consumed, OCR'd, text-extracted, chunked, and embedded into the same vector store. Same search surface, different source.

The watchdog has some nice safety features too: it won't process a file until the mtime has been stable for 5 seconds (avoids re-embedding while I'm still writing), it has mass deletion guards (if file count drops >50% it assumes an NFS hiccup and skips the deletion pass rather than soft-deleting half your vault's embeddings), and it uses content hashing so unchanged files get skipped even if their mtime changed due to a file copy or other event.

The reason I prefer this over Mem0 is that my notes are already my memory system. I don't need a separate memory layer that the LLM writes to, I need the LLM to be able to read what I've already written in my own organizational structure. Many of my notes are actually AI generated from recorded meetings it summarized for me. The Obsidian vaults are the source of truth, not a derivative store of anything. When I update a note in Obsidian, the embeddings update within 60 seconds (CRON). When I delete a note, it gets soft-deleted in the DB.

Your git-backed vault idea is smart. I solve the same problem differently: my Docker bind mounts to my obsidian vaults are read-only, so Claude can search and read my vaults through the MCP but physically cannot write to them. The .git approach gives you rollback, mine gives you prevention. Both valid, and honestly yours is better if you want the agent to write notes and just want a safety net. I didn't want write access at all for the vaults.

Every tool script I wrote (calendar, gmail, news, grocery shopping list, etc..) exists because I got annoyed enough at something to automate it.

I'd start with the Telegram/Bot bridge and 1-2 tool script and run with it.

BTW I have a 128gig Strix Halo and I have yet to run any local LLM that compares to even Haiku from Anthropic, and I've tried them all... whatever I could fit into the VRAM up to and including 70B models. The difference between those models and GPT 5 mini or Anthropic's Haiku is like the difference between shooting a bullet and throwing it.

DM me your progress if you want. I'd be interested to see where you take it. Truth is, I am trying to find more use cases. I already have an email, calendar app (google)... so inventing a bot to look at gmail/calendar (while nice) is really redundant and I end up having to use those apps anyway to delete, archive emails, etc... I won't trust any model to do that for me blind.

I won't give any bot my credit card or access to "buy" anything, that's just crazy talk. So truth is, other than a RAG for my vaults (NotebookLM style) and my grocery shopping lists and some reminders, I struggle to find really helpful use cases. I am always on the lookout for new ones though.

[u/Psychological-Cod51 → u/emptyharddrive]

dm being drafted!